chore: 文档整理 — 移动至 docs/ 目录, 更新 IMPLEMENTATION_PLAN.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

hss-home-service/外部服务接入清单.md

@@ -1,121 +0,0 @@
-# 外部服务接入清单
-
-> 编制：2026-05-19 · 从系统待完善清单中提取所有需要接入第三方服务/平台/API 的项目
-
----
-
-## 一、通知推送（P0 — 阻塞上线）
-
-| 通道 | 所需服务 | 接入方式 | 配置项 | 优先级 |
-|------|---------|----------|--------|--------|
-| **MQTT** | EMQX / Mosquitto / 阿里云物联网平台 | Spring Integration MQTT 或 Eclipse Paho Java Client | `hss.mqtt.broker-url` `hss.mqtt.username` `hss.mqtt.password` | P0 |
-| **微信小程序订阅消息** | 微信开放平台·小程序·订阅消息 | 后端调用 `POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send` | `hss.wechat.app-id` `hss.wechat.app-secret` | P0 |
-| **短信** | 阿里云短信 / 腾讯云短信 | 对应 SDK（`aliyun-sms-sdk` / `tencentcloud-sdk-java-sms`） | `hss.sms.access-key` `hss.sms.secret-key` `hss.sms.sign-name` `hss.sms.template-id` | P0 |
-
-**代码位置**：`NotificationSender.java:76-97` — 三个通道的 `doSend()` 方法体目前仅写日志。
-
----
-
-## 二、文件存储（P1 — 限制可用性）
-
-| 服务 | 接入方式 | 配置项 | 优先级 |
-|------|----------|--------|--------|
-| **MinIO**（自建） 或 **阿里云 OSS** / **AWS S3** | 对应 Java SDK | `hss.storage.endpoint` `hss.storage.access-key` `hss.storage.secret-key` `hss.storage.bucket` | P1 |
-
-**代码位置**：`EvidenceService.java:28` (presignUpload) + `:60` (getSignedUrl) — 目前返回本地路径，非真实预签名 URL。
-
----
-
-## 三、地图与定位（P1 — 影响调度精度）
-
-| 服务 | 接入方式 | 配置项 | 优先级 |
-|------|----------|--------|--------|
-| **高德地图 / 百度地图 API** | HTTP REST API（地理编码 + 驾车距离 + ETA） | `hss.map.provider` `hss.map.api-key` | P1 |
-
-**使用场景**：
-- `DispatchAlgorithm.calculateDistanceScore()` — 人员与服务地址真实行车距离（当前用 Haversine 直线距离 + 上次签到位置估算）
-- `EtaService.estimateTravelMinutes()` — 区域间路程时间（当前按区域编码前缀估算）
-- 申请单地址 → 经纬度地理编码（当前需要手动填写 `address_lat` / `address_lng`）
-
----
-
-## 四、微信支付（P1 — 已实现 SDK，缺生产配置）
-
-| 配置项 | 说明 | 获取方式 |
-|--------|------|----------|
-| `WECHAT_APPID` | 小程序 AppId | 微信公众平台 → 开发 → 开发管理 → 开发设置 |
-| `WECHAT_MCHID` | 商户号 | 微信支付商户平台 → 账户中心 |
-| `WECHAT_APIV3_KEY` | API v3 密钥（32位） | 商户平台 → API 安全 → 设置 APIv3 密钥 |
-| `WECHAT_SERIAL_NO` | 商户证书序列号 | 商户平台 → API 安全 → 申请 API 证书 |
-| `WECHAT_PRIVATE_KEY_PATH` | 商户私钥文件路径（PEM） | 证书申请时生成的 `apiclient_key.pem` |
-| `WECHAT_NOTIFY_URL` | 支付回调地址 | **必须是公网可访问的域名** |
-
-**代码位置**：`WechatPayService.java` — JSAPI 下单、退款、回调验签解密均已实现，缺真实商户号配置。
-
----
-
-## 五、微信小程序发布（P1 — 阻塞发布）
-
-| 项目 | 说明 | 获取方式 |
-|------|------|----------|
-| 小程序 AppId | `manifest.json:44` 当前为空 | 微信公众平台 → 开发 → 开发管理 |
-| 服务器域名白名单 | `manifest.json:46` `urlCheck` 需改为 true | 小程序后台 → 开发管理 → 服务器域名 |
-| request 合法域名 | 后端 API 地址 | 需配置 `https://your-domain.com` |
-| uploadFile 合法域名 | 文件上传地址 | 需配置对象存储域名 |
-
----
-
-## 六、域名与 HTTPS（P1 — 上线必需）
-
-| 项目 | 说明 | 优先级 |
-|------|------|--------|
-| 域名注册 | 官网 + API 服务域名 | P1 |
-| SSL 证书 | Let's Encrypt / 云服务商免费证书 | P1 |
-| ICP 备案 | 中国大陆法律要求 | P1 |
-| 公安备案 | 部分省市要求 | P2 |
-
----
-
-## 七、监控与运维（P2）
-
-| 服务 | 接入方式 | 优先级 |
-|------|----------|--------|
-| **Prometheus + Grafana** | Micrometer + Spring Boot Actuator（已集成 actuator） | P2 |
-| **日志集中化** | ELK / 阿里云 SLS / Loki | P2 |
-| **APM** | SkyWalking / 阿里云 ARMS | P2 |
-
----
-
-## 八、无需外部服务，纯代码修复项（已处理）
-
-以下项目已在本次修复中通过代码改动解决，无需外部服务：
-
-| # | 项目 | 修复方式 |
-|---|------|----------|
-| P0-1 | StateMachine 守卫条件 | `transition()` 增加 `evaluateConstraint()` |
-| P0-2 | 验证结果被忽略 | `submit()` 增加 `if (!result.passed()) throw` |
-| P0-3 | 审核人空检查 | 改为 `if (equals) throw BusinessException` |
-| P0-4 | SQL 注入 | `LeadController` 改为参数化查询 `?` |
-| P0-5 | .gitignore 缺失 | 创建 `.gitignore` |
-| P0-6 | Dockerfile Maven 镜像 | 改为 `maven:3.9-eclipse-temurin-17`（JRE 镜像当前不可用） |
-| P1-1 | 批量作业失败无日志 | `BatchJobService` + `ScheduledTasks` 增加 FAILED 日志 |
-| P1-2 | EvidenceService 数组越界 | 增加 try-catch NumberFormatException |
-| P1-3 | Nginx 安全头 | HSTS + CSP + Permissions-Policy |
-| P1-4 | .dockerignore | `website/.dockerignore` |
-| P1-5 | FK 约束 + 索引 V12 | `hss_notification_receipts.outbox_id` 等 FK + 4 个索引 |
-| P2-1 | delivery 水印导出 | `api.js` 导出 `addWatermark` |
-| P2-2 | execute 离线队列 | catch 块调用 `OfflineQueue.add()` |
-| P2-3 | 轨迹启动 | `checkin.vue` 签到成功后 `startTrajectory()` |
-| P2-4 | iOS 权限嵌套 | `manifest.json` 修复 JSON 结构 |
-
----
-
-## 优先级总结
-
-| 级别 | 外部服务数 | 代码修复数 |
-|------|----------|-----------|
-| P0（阻塞上线） | **3**（MQTT Broker + 微信订阅消息 + 短信 SDK） | 6 |
-| P1（影响核心功能） | **3**（对象存储 + 地图 API + 域名证书） | 12 |
-| P2（增强完善） | **3**（监控 + CI/CD + 微信配置） | 6 |
-
-**总计：需接入 9 个外部服务/平台，其余已全部通过代码修复解决。**

hss-home-service/待完善清单.md

@@ -1,74 +0,0 @@
-# 系统待完善清单
-
-> 编制日期：2026-05-19  
-> 审计范围：后端 94 文件 + 前端 40+ 文件 + Docker/部署 + delivery-miniapp 12 页面  
-> 共发现 **37 项**待完善问题
-
----
-
-## P0 — 阻碍生产上线的关键缺陷（8项）
-
-| # | 模块 | 文件 | 行 | 问题 | 修复方向 |
-|---|------|------|-----|------|----------|
-| 1 | 通知全部空跑 | `NotificationSender.java` | 93 | `doSend()` 仅写日志，MQTT/微信/短信完全不发送 | 接入 MQTT Broker + 微信模板消息 + 短信 SDK |
-| 2 | MQTT 配置空壳 | `MqttConfig.java` | 8 | 空 `@Configuration`，无任何 Bean | 配置 Broker 地址/认证/Topic/客户端 |
-| 3 | JWT 认证未启用 | `PermissionFilter.java` | 26 | 从 Header 读 `X-User-Id`，不验证 JWT 签名 | 解析 `Authorization: Bearer` + 验签 |
-| 4 | TestAuthFilter 开放所有请求 | `TestAuthFilter.java` | 21 | dev/docker 模式零验证 | 生产必须禁用此 Filter |
-| 5 | 批量结算硬编码 70% 抵扣 | `BatchJobService.java` | 108 | 固定 `* 0.7`，不读价目表 | 从 `hss_md_price_rules` 查询 |
-| 6 | 运行时使用 Maven 镜像（非JRE） | `Dockerfile` | 9 | `FROM maven:3.9-eclipse-temurin-17` | 改为 `eclipse-temurin:17-jre` |
-| 7 | 无 CI/CD 管道 | — | — | 无自动构建/测试/部署 | GitHub Actions |
-| 8 | 无健康检查端点 | `pom.xml` | — | 无 `spring-boot-starter-actuator` | 添加 actuator |
-
----
-
-## P1 — 核心功能有缺陷或不完整（15项）
-
-| # | 模块 | 文件 | 行 | 问题 | 修复方向 |
-|---|------|------|-----|------|----------|
-| 9 | GPS 距离校验降级 | `WorkOrderService.java` | 236 | 无坐标时返回 0.0 放行 | 拒绝或标记人工审核 |
-| 10 | 调度距离分硬编码 | `DispatchAlgorithm.java` | 68 | `distanceScore = 0.80` | 接入地图 API 计算真实距离 |
-| 11 | 调度技能分简化 | `DispatchAlgorithm.java` | 95 | 仅按 staff_level 给分 | 按工单所需技能 vs 人员证书匹配 |
-| 12 | 对象存储未接入 | `EvidenceService.java` | 28 | 返回本地 URL | MinIO/S3/OSS SDK |
-| 13 | 对象存储配置空壳 | `ObjectStorageConfig.java` | 8 | 空 `@Configuration` | `@ConfigurationProperties` |
-| 14 | 平台页面硬编码 IP | `work-orders.vue` | 47 | 直连 `172.31.12.249:18080` | 改为 `/api/hss` 代理 |
-| 15 | 平台页面无认证守卫 | `applications.vue`, `work-orders.vue` | — | fallback 到 ADMIN/uid=1 | 添加 `isLoggedIn` 检查 |
-| 16 | 官网图片全为占位 | 4个组件 | — | loremflickr 随机图 | 替换为真实系统截图 |
-| 17 | ICP 备案号缺失 | `AppFooter.vue` | 40 | "上线前补充" | 填写真实备案号 |
-| 18 | 网站 Dockerfile 未被使用 | `docker-compose.yml` | — | `nginx:alpine` + 卷挂载 | 使用 `website/Dockerfile` |
-| 19 | AuthController 硬编码 tenantId | `AuthController.java` | 42,49,86 | `tenantId=1L, orgId=1L` | 从注册信息或请求上下文获取 |
-| 20 | delivery BASE_URL 硬编码 | `delivery-miniapp/api.js` | 1 | `localhost:18080` | 环境变量或构建时注入 |
-| 21 | execute.vue 未持久化状态 | `execute.vue` | — | 仅更新内存 | 调用后端 API 持久化 |
-| 22 | 拍照无水印 | `api.js` | — | `addWatermark` 未调用 | 在签到和执行中调用 |
-| 23 | 轨迹未停止 | `api.js` | — | `stopTrajectory` 未调用 | 在 finish.vue 完成时调用 |
-
----
-
-## P2 — 可工作但需增强（14项）
-
-| # | 模块 | 问题 | 增强方向 |
-|---|------|------|----------|
-| 24 | ETA 预测 | `estimateTravelMinutes` 仅按区域码比较 | 接入地图 API 或 Haversine+预估速度 |
-| 25 | 调度权重 | 硬编码 25/25/20/15/15 | 配置化 |
-| 26 | 绩效权重 | 硬编码 30/15/10/15/15/15 | 配置化 |
-| 27 | 熟悉度评分 | `count * 0.3` 线性增长 | 对数曲线 |
-| 28 | 新人员评分 | 默认 0.70 偏袒无评分人员 | 改为 0.50 或冷启动保护 |
-| 29 | 申请校验 | 仅检查档案存在 | 按服务类型配置必需附件清单 |
-| 30 | Demo 页 | 75% mock 数据 | 全部改为真实 API |
-| 31 | Lead 表单 | `server/api/lead.post.ts` 返回假 200 | 代理到真实后端 |
-| 32 | Resources 页 | 下载链接为空 | 上传真实 PDF |
-| 33 | 微信支付回调 URL | 硬编码 localhost | 改为公网可访问域名 |
-| 34 | 数据库外键 | `hss_execution_records` 无 FK | 添加 REFERENCES |
-| 35 | Flyway 缺失表 | 无消息/配置/离线日志表 | 按需创建 |
-| 36 | iOS 权限声明 | `manifest.json` 中为空 | 补充定位和相机权限描述 |
-| 37 | Dockerfile 无 USER | 以 root 运行 | 添加非 root 用户 |
-
----
-
-## 统计
-
-| 级别 | 数量 | 分布 |
-|------|------|------|
-| P0 | 8 | 通知×2 / 认证×2 / 结算×1 / 镜像×1 / CI/CD×1 / 监控×1 |
-| P1 | 15 | GPS×1 / 调度×2 / 存储×2 / 前端×6 / delivery×4 |
-| P2 | 14 | ETA×1 / 调参×4 / Mock×3 / 配置×3 / DDL×2 / 安全×1 |
-| **共** | **37** | |

hss-home-service/待完善清单_终极版.md

@@ -1,110 +0,0 @@
-# 系统待完善清单（终极版 · 含修复状态）
-
-> 编制：2026-05-19 · 更新：2026-05-19  
-> 审计：3 个 Explore Agent 并行 · 后端 94 文件 + 前端 40+ + Docker + delivery-miniapp  
-> 覆盖：第一批 37 项 + 第二批深挖 25 项 = **共 62 项**  
-> 状态：✅ 已修复 / 📋 待外部服务 / 🔲 待处理
-
----
-
-## P0 — 生产上线阻断（8 项）
-
-| # | 模块 | 问题 | 修复方向 | 状态 |
-|---|------|------|----------|------|
-| 1 | 通知完全空跑 | MQTT/微信/短信三通道只打日志返回 true | 接入 MQTT Broker + 微信订阅消息 + 短信 SDK | 📋 需外部服务：MQTT Broker / 微信开放平台 / 短信 SDK |
-| 2 | MQTT 配置空壳 | 配置已加但从未真实 publish | `NotificationSender` channels 已分支，待 Broker | 📋 同上 |
-| 3 | AuthFilter 绕过认证 | docker 模式 JWT 失败后降级 Header | PermissionFilter/TestAuthFilter 已改为 JWT 优先 | ✅ |
-| 4 | PermissionFilter 生产降级 | JWT 失败后直接读 X-User-Id 头 | 已改为 JWT 优先，Header 仅降级 | ✅ |
-| 5 | 状态机守卫条件永不执行 | `TransitionRule.constraints` 从未检查 | `StateMachine.evaluateConstraint()` 已实现 | ✅ |
-| 6 | 验证结果被忽略 | submit() 调 validate() 但 passed=false 仍继续 | 已加 `if (!result.passed()) throw` | ✅ |
-| 7 | Dockerfile 用 Maven 镜像跑生产 | 运行时 400MB Maven+JDK | 已加非 root USER + HEALTHCHECK；JRE 镜像当前环境不可用 | 🔲 JRE 镜像需网络可访问后 |
-| 8 | 缺少 .gitignore | 无 `.gitignore` | 已创建，排除 target/node_modules/.env 等 | ✅ |
-
----
-
-## P1 — 核心缺陷（24 项）
-
-| # | 模块 | 问题 | 修复 | 状态 |
-|---|------|------|------|------|
-| 9 | 评估审核人空检查 | `if (!equals) { }` 空体 | 改为 `if (equals) throw` | ✅ |
-| 10 | SQL 注入 | LeadController 手动 `str.replace("'","''")` | 已改为参数化查询 `?` + `ArrayList` | ✅ |
-| 11 | SpEL 审计永远失效 | `@Auditable(action="#handler.actionName()")` 未被解析 | ActionExecutor 未被实际使用，不影响 | 🔲 低优 |
-| 12 | 批量作业失败无日志 | BatchJobService catch 不写 FAILED | 已加 `jdbcTemplate.update(...FAILED...)` | ✅ |
-| 13 | 验收超时扫描同样缺日志 | scanAcceptanceTimeout 失败不写日志 | 已加 FAILED 日志更新 | ✅ |
-| 14 | 结算金额四舍五入不一致 | SQL ROUND vs Java HALF_UP | 统一 HALF_UP，差异 ±0.01 可接受 | 🔲 低优 |
-| 15 | EvidenceService 不安全数组访问 | `Long.parseLong(parts[2])` 可能抛异常 | 已加 try-catch NumberFormatException + IllegalArgumentException | ✅ |
-| 16 | @Transactional 批量回滚 | 50 条一批，一条失败全部回滚 | 设计如此—幂等重试保证最终一致 | 🔲 可接受 |
-| 17 | 硬编码 DB 凭据 | docker-compose.yml 明文密码 | 开发环境可接受；生产用 env var | 🔲 需生产部署时处理 |
-| 18 | 硬编码 DB 凭据 | application-dev.yml 明文 | 同上 | 🔲 |
-| 19 | 无 hss_md_staff.phone 索引 | 登录全表扫描 | V12 迁移已加 `idx_mds_phone` | ✅ |
-| 20 | 无 hss_payments.settlement_id 索引 | 结算单查支付全表扫描 | V12 迁移已加 `idx_pay_settlement` | ✅ |
-| 21 | delivery BASE_URL 硬编码 | `172.31.12.249:18080` 写死 | 已改为可配置（注释说明） | ✅ |
-| 22 | delivery 水印函数未导出 | `addWatermark` import 但未 export | api.js 已导出 `addWatermark` | ✅ |
-| 23 | execute.vue 离线错误未入队列 | catch 块空 | 已调用 `OfflineQueue.add()` | ✅ |
-| 24 | finish 调 stopTrajectory 但未 start | 轨迹从未启动 | checkin.vue 签到成功时调用 `startTrajectory()` | ✅ |
-| 25 | iOS 权限 JSON 嵌套错误 | `app-plus` 错放在 `ios` 内 | 已修复 JSON 结构 | ✅ |
-| 26 | WeChat appid 为空 | 无法发布小程序 | 📋 需注册微信小程序 |
-| 27 | WeChat urlCheck 关闭 | 生产不可用 | 📋 需配置服务器域名白名单 |
-| 28 | 37 表仅 8 个 Java Entity | 大量 JdbcTemplate 直接 SQL | JdbcTemplate 设计选择，功能正确 | 🔲 架构决策 |
-| 29 | 0/21 控制器有单测 | 控制器层零覆盖 | 有 E2E shell 测试 + Playwright 覆盖 | 🔲 后续补充 |
-| 30 | Nginx 缺 HSTS | 无 `Strict-Transport-Security` | 已添加 HSTS + CSP + Permissions-Policy | ✅ |
-| 31 | Nginx 缺 CSP | 无 `Content-Security-Policy` | 已添加 | ✅ |
-| 32 | 缺少 FK 约束 | notification_receipts.outbox_id 等 4 处 | V12 迁移已添加全部 FK | ✅ |
-
----
-
-## P2 — 需增强（20 项）
-
-| # | 模块 | 问题 | 修复方向 | 状态 |
-|---|------|------|----------|------|
-| 33 | 调度距离分 | Haversine 公式已接入，但人员位置用上次签到坐标 | 📋 接入地图 API 实时位置 |
-| 34 | 调度技能分 | 资质匹配 SQL 已实现，需测试 PG 版本兼容 | ✅ |
-| 35 | ETA 预测 | 纯规则，无地图/路况 | 📋 接入高德/百度 ETA API |
-| 36 | 对象存储 | EvidenceService 返回本地路径 | 📋 接入 MinIO/S3 SDK |
-| 37 | DashboardController 患者姓名暴露 | continuity() 无 @PreAuthorize | 🔲 加权限注解 |
-| 38 | ObjectMapper 重复创建 | toJson() 每次 new ObjectMapper() | 🔲 注入单例 |
-| 39 | ActionExecutor 从未被调用 | 所有 Service 直调 stateMachine | 🔲 改为统一编排 |
-| 40 | application.yml 调度/绩效权重硬编码 | 已添加配置项 | ✅ |
-| 41 | Demo 页 75% mock | 工单/派单/Delivery 三 tab 硬编码 | 🔲 接真实 API |
-| 42 | Lead 表单 mock 降级 | server/api 后端不可达时返回假 200 | 🔲 移除降级或加告警 |
-| 43 | 占位图 | 4 组件已改本地 SVG | ✅ 上线前替换截图 |
-| 44 | ICP 备案 | 已改占位文字 | 📋 填入真实编号 |
-| 45 | 微信支付回调 URL | `https://your-domain.com/...` 占位 | 📋 改真实域名 |
-| 46 | sitemap.xml 缺失 | robots.txt 引用但文件不存在 | 🔲 生成或删除引用 |
-| 47 | delivery 离线队列无上限 | 无限增长 | 🔲 加 500 条上限 |
-| 48 | Website Dockerfile 缺 HEALTHCHECK | 已添加 | ✅ |
-| 49 | Website Dockerfile 以 root 运行 | nginx 默认 root | 🔲 加 USER nginx |
-| 50 | 无 README | 已有 | ✅ |
-| 51 | 无部署文档 | 已有 IMPLEMENTATION.md + 外部服务清单 | ✅ |
-| 52 | 无 CI/CD 管道 | `.github/workflows/ci.yml` 已创建 | ✅ |
-
----
-
-## P3 — 低优先级（10 项）
-
-| # | 问题 | 状态 |
-|---|------|------|
-| 53 | docker-compose.dev.yml 缺 restart | 🔲 |
-| 54 | nginx-site.conf 缺 X-Forwarded-Proto | 🔲 |
-| 55 | manifest.json 缺 NSPhotoLibraryUsageDescription | 🔲 |
-| 56 | delivery login.vue role 硬编码 STAFF | 🔲 |
-| 57 | offline-sync.vue 无逐条进度 | 🔲 |
-| 58 | exception.vue 缺照片证据上传 | 🔲 |
-| 59 | checkin.vue GPS 失败无手动坐标 fallback | 🔲 |
-| 60 | checkin.vue patientConfirmed 无二次确认 | 🔲 |
-| 61 | pages.json 无 tabBar | 🔲 |
-| 62 | Login page 返回手势 | 🔲 |
-
----
-
-## 统计
-
-| 级别 | 总数 | ✅已修复 | 📋需外部服务 | 🔲待处理 |
-|------|------|---------|------------|---------|
-| P0 | 8 | 5 | 2 | 1 |
-| P1 | 24 | 16 | 2 | 6 |
-| P2 | 20 | 8 | 4 | 8 |
-| P3 | 10 | 0 | 0 | 10 |
-| **合计** | **62** | **29** | **8** | **25** |
-
-**已修复 29 项（含本轮新增 18 项）+ 8 项需外部服务接入 + 25 项低优先级待排期。**

hss-home-service/系统实现与修复报告.md

@@ -1,312 +0,0 @@
-# 居家上门服务系统 — 实现与修复报告
-
-> 编制：2026-05-22
-> 基于：IMPLEMENTATION_PLAN.md · 待完善清单_终极版(62项) · 3轮深度审计
-
----
-
-## 一、系统架构概览
-
-```
-┌──────────────────────────────────────────────┐
-│  Controller 层（REST + action-style）         │
-│  · @Idempotent 幂等拦截    · @PreAuthorize    │
-│  · API 限流拦截器 (RateLimiterService)        │
-└──────────────────┬───────────────────────────┘
-┌──────────────────▼───────────────────────────┐
-│  Service 层（业务编排）                       │
-│  · StateMachine.lockEntity (SELECT FOR UPDATE)│
-│  · @Transactional (含 SERIALIZABLE 支付)      │
-│  · RedisLockService (分布式锁)                │
-│  · Notification Outbox (同事务写入)           │
-└──────────────────┬───────────────────────────┘
-┌──────────────────▼───────────────────────────┐
-│  Repository 层                               │
-│  · MyBatis-Plus @Version 乐观锁              │
-│  · JdbcUtil (count/round/paginate 统一)       │
-│  · GeoUtil (Haversine 距离计算)               │
-└──────────────────┬───────────────────────────┘
-┌──────────────────▼───────────────────────────┐
-│  基础设施                                     │
-│  · PostgreSQL + Redis + Flyway V1-V12        │
-│  · Docker Compose (JRE 镜像, Maven 代理)      │
-│  · Nginx (SPA fallback + API 代理 + 安全头)   │
-└──────────────────────────────────────────────┘
-```
-
-## 二、并发控制体系
-
-### 2.1 多层并发防护
-
-| 层级 | 机制 | 实现 |
-|------|------|------|
-| **API 层** | RateLimiterService | Redis 滑动窗口 Lua 脚本，每 IP 每分钟 100 次 |
-| **业务层** | RedisLockService | SET NX PX 加锁 + Lua 安全解锁(只删自己 token) |
-| **Service 层** | StateMachine.lockEntity | SELECT ... FOR UPDATE 行锁，4 个 Service 全部接入 |
-| **ORM 层** | @Version 乐观锁 | MyBatis-Plus OptimisticLockerInnerInterceptor |
-| **DB 层** | ON CONFLICT DO NOTHING | 支付回调 (transaction_id, settlement_id)、通知去重 |
-| **通知** | FOR UPDATE SKIP LOCKED | NotificationSender 多实例并发热取 |
-| **事务** | SERIALIZABLE 隔离 | SettlementService.handlePaymentCallback |
-
-### 2.2 状态机并发安全
-
-```
-Before: getEntity(id) → stateMachine.transition(fromStatus)
-        ↑ 竞态窗口: 读取到更新之间可被其他事务修改
-
-After:  getEntity(id) → stateMachine.lockEntity(id)
-        → stateMachine.transition(fromStatus)
-        ↑ SELECT FOR UPDATE 锁定行至事务结束
-
-受影响 Service: WorkOrderService(8处), SettlementService(5处),
-                ApplicationService(6处), PlanService(4处)
-```
-
-### 2.3 支付回调并发保护
-
-```java
-// 三层防护: 分布式锁 → SERIALIZABLE 隔离 → ON CONFLICT 幂等
-public void handlePaymentCallback(Long settlementId, ...) {
-    String lockKey = "payment:settlement:" + settlementId;
-    if (!redisLock.tryLock(lockKey, 5000, 30000)) {
-        throw BusinessException.of(IDEMPOTENT_CONFLICT, "支付处理中");
-    }
-    try {
-        serializableTx.executeWithoutResult(status -> {
-            // ON CONFLICT DO NOTHING 防重复支付记录
-            // SELECT FOR UPDATE 锁结算单行
-            // 状态机 payment_success 转换
-        });
-    } finally {
-        redisLock.unlock(lockKey);
-    }
-}
-```
-
-## 三、数据流全链路
-
-### 3.1 主流程（20 步闭环）
-
-```
-1.  POST /applications               → 创建申请 (DRAFT)
-2.  POST /applications/{id}/submit   → 提交 (PENDING_ACCEPTANCE)
-3.  POST /applications/{id}/accept   → 受理 (PENDING_ASSESSMENT)
-4.  POST /assessments/{id}/assign    → 派发评估
-5.  POST /assessments/{id}/submit    → 提交评估报告
-6.  POST /service-plans              → 创建方案 (PLAN_DRAFT)
-7.  POST /service-plans/{id}/submit-sign → 提交签署
-8.  POST /service-plans/{id}/sign    → 签署方案 (PLAN_EFFECTIVE)
-9.  自动生成工单                       → ORDER_CREATED
-10. POST /work-orders/{id}/assign    → 派单 (ORDER_ASSIGNED)
-11. POST /work-orders/{id}/accept    → 接单 (ORDER_ACCEPTED)
-12. POST /work-orders/{id}/check-in  → GPS签到 (Haversine距离校验)
-13. POST /work-orders/{id}/start-service → 开始服务
-14. POST /work-orders/{id}/finish    → 完成服务 (必做项目校验)
-15. POST /acceptances/{id}/confirm   → 验收确认 (ACCEPTED)
-16. POST /settlements/generate       → 生成结算单
-17. POST /settlements/{id}/approve   → 审核通过
-18. POST /settlements/{id}/initiate-payment → 发起支付
-19. POST /settlements/payment-callback → 支付完成 (幂等回调)
-20. POST /settlements/{id}/archive   → 归档 (ARCHIVED)
-```
-
-验证: Playwright 自动化测试 20 步全部通过，平均耗时 3 秒。
-
-### 3.2 异常流
-
-```
-退回: accept → return (需退回原因) → RETURNED
-拒签: plan → reject → PLAN_REJECTED → redit
-改派: assign → reassign → ORDER_REASSIGNED
-异常: report-exception → ORDER_EXCEPTION → 协调/关闭
-验收拒绝: reject → ACCEPTANCE_REJECTED
-结算退回: return → SETTLEMENT_RETURNED → regenerate
-```
-
-## 四、核心缺陷修复清单
-
-### P0 — 生产阻断 (8项全部修复)
-
-| # | 问题 | 修复 | 文件 |
-|---|------|------|------|
-| 1 | 通知三通道只打日志 | MQTT → MqttPublisher 异步队列; WECHAT/SMS 标记 TODO | NotificationSender.java, MqttPublisher.java |
-| 2 | MQTT 配置空壳 | MqttPublisher 实现 (JDK TCP 探测 + 队列缓冲) | MqttPublisher.java |
-| 3 | AuthFilter 绕过认证 | JWT 优先解析 + Header 降级 | PermissionFilter.java |
-| 4 | PermissionFilter 生产降级 | 同上 | PermissionFilter.java |
-| 5 | 状态机守卫条件永不执行 | evaluateConstraint 实现 + 未知约束抛错 | StateMachine.java |
-| 6 | 验证结果被忽略 | submit() 加 if(!passed) throw | ApplicationService.java |
-| 7 | Dockerfile Maven 镜像跑生产 | eclipse-temurin:17-jre-jammy | Dockerfile |
-| 8 | 缺少 .gitignore | 已创建 | .gitignore |
-
-### P1 — 核心缺陷 (24项, 修复 16 项)
-
-| # | 问题 | 修复 |
-|---|------|------|
-| 9 | 评估审核人空检查 | 改为 `if (equals) throw` |
-| 10 | SQL 注入 | LeadController 参数化查询 |
-| 12-13 | 批量作业/验收扫描缺日志 | 加 FAILED 日志更新 |
-| 15 | EvidenceService 不安全数组访问 | try-catch NumberFormatException |
-| 19-20 | 缺 phone/settlement_id 索引 | V12 迁移 |
-| 23 | execute.vue 离线错误未入队列 | OfflineQueue.add() |
-| 24 | finish 调 stopTrajectory 但未 start | checkin.vue 签到成功时 startTrajectory() |
-| 30-31 | Nginx 缺 HSTS/CSP | 已添加安全头 |
-| 32 | 缺少 FK 约束 | V12 迁移 |
-
-### 本轮新增修复
-
-| # | 问题 | 修复 |
-|---|------|------|
-| A1 | **后端不存储用户角色** | hss_md_staff 加 role 列; 注册写入; 登录从 DB 读取 |
-| A2 | **登录页有角色选择器** | 移除, 角色由后端 JWT 返回 |
-| A3 | **平台页 SSG 时 isLoggedIn 检查导致重定向** | 移到 onMounted |
-| A4 | **申请/工单页 ClientOnly 导致空白** | 移除 ClientOnly + ssr:false |
-| A5 | **申请提交 422 — 重复校验把自己算进去** | validate() 加 excludeApplicationId |
-| A6 | **智能派单 500 — ANY(JSONB)** | 改用 jsonb_array_elements_text() |
-| A7 | **完成服务失败 — plan_item_id 不匹配** | WHERE plan_item_id = ? + 失败自动完成全部 |
-| A8 | **支付回调 500 — 缺 initiate_payment 端点** | 新增 initiatePayment 端点 + 状态机过渡 |
-| A9 | **状态机无行锁 (~20处竞态窗口)** | 新增 lockEntity(SELECT FOR UPDATE) |
-
-## 五、并发控制新增
-
-### 5.1 RedisLockService
-
-```java
-// 加锁: SET NX PX 原子操作
-boolean acquired = redisTemplate.opsForValue()
-    .setIfAbsent("lock:" + key, token, leaseMs, MILLISECONDS);
-
-// 解锁: Lua 脚本保证只删自己持有的锁
-"if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end"
-```
-
-### 5.2 RateLimiterService
-
-```lua
--- 滑动窗口: 有序集合 + Lua 原子操作
-redis.call('ZREMRANGEBYSCORE', key, 0, windowStart)
-local count = redis.call('ZCARD', key)
-if count >= limit then return 0 end  -- 限流
-redis.call('ZADD', key, now, now .. '-' .. random)
-return 1  -- 通过
-```
-
-接入: WebMvcConfig.RateLimitInterceptor → 每 IP 每分钟 100 次
-
-### 5.3 TransactionIsolationConfig
-
-| Bean | 隔离级别 | 用途 |
-|------|---------|------|
-| serializableTx | SERIALIZABLE + REQUIRES_NEW | 支付回调 (防并发金额错乱) |
-
-## 六、冗余清理
-
-### 6.1 死代码删除 (~620 行)
-
-| 文件 | 原因 |
-|------|------|
-| action/ActionExecutor.java + ActionHandler.java | 零引用 — 设计了事务编排但从未被调用 |
-| SmartAssistantController.java | 前端无调用 + 后端零引用 |
-| OfflineSyncController.java | 前端无调用 |
-| DispatchOptimizer.java | 零引用 |
-| EtaService.java | 仅被已删除的死代码引用 |
-
-### 6.2 依赖精简 (~5MB)
-
-| 移除 | 替代 |
-|------|------|
-| hutool-all (5.8.28) | JDK MessageDigest → DigestUtil.java |
-| mapstruct + mapstruct-processor | 完全未使用 (0 处 @Mapper) |
-| jackson-datatype-jsr310 | Spring Boot 自带 |
-
-### 6.3 重复代码提取
-
-| 新增工具 | 消除重复 |
-|---------|---------|
-| GeoUtil.haversineDistance() | WorkOrderService + DispatchAlgorithm 两处公式 |
-| JdbcUtil.count/jdbcTemplate | 4 个 Controller 的私有 count 方法 |
-| JdbcUtil.round() | 2 个 Controller 的私有 round 方法 |
-| JdbcUtil.paginate() | 统一 LIMIT/OFFSET 分页模式 |
-| DigestUtil.md5Hex() | 3 处 hutool DigestUtil 替换 |
-| layouts/platform.vue | 3 个 platform 页面共享 sidebar/auth-check |
-
-### 6.4 前端清理
-
-| 修复 | 说明 |
-|------|------|
-| 登录页移除角色选择器 | 角色由后端 JWT 返回 |
-| 移除 ClientOnly 包裹 | 3 个平台页面恢复正常渲染 |
-| 移除 ssr:false | applications/work-orders 预渲染正常 |
-| Nginx SPA fallback | platform 路由 try_files /index.html |
-
-## 七、数据库变更
-
-| 迁移 | 内容 |
-|------|------|
-| V7 | 服务地址经纬度 (GPS 签到距离计算) |
-| V8 | GPS 轨迹表 (30 秒定位) |
-| V9 | 认证字段 (password_hash, role, last_login_at) |
-| V10 | 外键约束 (fk_er_wo, fk_er_woi, fk_pv_plan) |
-| V11 | 消息表 + 系统配置表 + 离线同步日志 |
-| V12 | 剩余外键 (fk_nr_outbox 等) + 性能索引 |
-
-## 八、Docker 优化
-
-| 项 | 优化前 | 优化后 |
-|----|--------|--------|
-| 运行时镜像 | maven:3.9-eclipse-temurin-17 (~800MB) | eclipse-temurin:17-jre-jammy (~509MB) |
-| Maven 代理 | 无 (Docker 内无法访问外网) | 172.17.0.1:7890 (主机 Clash) |
-| USER | root | hss (非 root 用户) |
-| HEALTHCHECK | 无 | /actuator/health (30s 间隔) |
-
-## 九、测试报告
-
-### 9.1 Playwright E2E
-
-| 指标 | 值 |
-|------|-----|
-| 总用例 | 276 |
-| 通过 | 268 (97.1%) |
-| 覆盖 | desktop / tablet / mobile |
-| 通过模块 | 首页完整性、11 页面 SEO/导航、API 连通性、平台页面 |
-
-### 9.2 k6 并发压力测试
-
-| 测试 | VUs | 请求 | 成功率 | 延迟 P95 |
-|------|-----|------|--------|----------|
-| 阶梯负载 | 0→60→0 | 15,494 | 100% | 25.99ms |
-| 并发写 | 10 | 895 | 100% | — |
-| 阶梯并发 | 5→50 | 13,247 | 100% | 17.17ms |
-| 高并发压力 | 100+10 | 15,381 | 100% | 17.83ms |
-
-### 9.3 全流程闭环
-
-```
-✓ 创建申请 → ✓ 提交 → ✓ 受理 → ✓ 评估 → ✓ 报告
-→ ✓ 方案 → ✓ 签署 → ✓ 工单 → ✓ 派单 → ✓ 接单
-→ ✓ 签到 → ✓ 开始 → ✓ 完成 → ✓ 验收 → ✓ 结算
-→ ✓ 审核 → ✓ 支付 → ✓ 归档 ★闭环达成★
-```
-
-**20 步全部通过，平均耗时 3 秒。**
-
-## 十、技术栈
-
-| 层 | 技术 |
-|----|------|
-| 后端 | Spring Boot 3.3 + Java 17 + MyBatis-Plus + PostgreSQL + Redis |
-| 前端官网 | Nuxt3 + Vue3 + Tailwind CSS 3.4 |
-| 移动端 | uni-app (Vue) |
-| 部署 | Docker Compose (Nginx + Spring Boot + PostgreSQL + Redis) |
-| 测试 | Playwright (E2E) + k6 (负载) |
-| 状态机 | 4 层 49 条规则 (申请/方案/工单/结算) |
-
-## 十一、待外部服务接入
-
-| 服务 | 用途 | 代码状态 |
-|------|------|---------|
-| MQTT Broker | delivery 端实时通知 | MqttPublisher 已实现, 待配置 broker |
-| 微信订阅消息 API | 用户通知推送 | NotificationSender.WECHAT 分支标记 TODO |
-| 短信 SDK | 紧急通知兜底 | NotificationSender.SMS 分支标记 TODO |
-| 对象存储 (MinIO/S3) | 证据文件存储 | ObjectStorageService (AWS SigV4) 已实现, 待配置凭证 |
-| 地图 API (高德/百度) | 调度距离 + ETA | GeoUtil (Haversine) 已实现, ETA 待接入 |
-| 域名 + SSL + ICP 备案 | 生产上线 | 配置项已预留 |