diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index c4de2bf..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: CI - -on: - push: - branches: [main] - pull_request: - branches: [main] - -jobs: - backend: - runs-on: ubuntu-latest - services: - postgres: - image: postgres:16-alpine - env: - POSTGRES_DB: hss_home_service_test - POSTGRES_USER: hss_test - POSTGRES_PASSWORD: test123 - ports: ["5432:5432"] - options: --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 5 - redis: - image: redis:7-alpine - ports: ["6379:6379"] - - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-java@v4 - with: { java-version: '17', distribution: 'temurin' } - - name: Build & Test - run: cd hss-home-service && mvn package -B - env: - DB_URL: jdbc:postgresql://localhost:5432/hss_home_service_test - DB_USERNAME: hss_test - DB_PASSWORD: test123 - REDIS_HOST: localhost - SPRING_PROFILES_ACTIVE: test - - website: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: { node-version: '20' } - - name: Install & Build - run: cd hss-home-service/website && npm ci && npm run generate diff --git a/README.md b/README.md index ced2590..5081c5b 100644 --- a/README.md +++ b/README.md @@ -9,37 +9,21 @@ ``` hss-home-service/ ├── src/ # Spring Boot 后端 -│ ├── main/java/.../common/ # 公共模块（响应体、异常、幂等、审计） -│ ├── main/java/.../config/ # Security/Redis/MyBatis/OpenAPI 配置 -│ ├── main/java/.../statemachine/ # 四层状态机（申请/方案/工单/结算） +│ ├── main/java/.../common/ # 公共模块（ApiResponse, 幂等, 审计, 分布式锁, 限流, GeoUtil） +│ ├── main/java/.../config/ # Security/Redis/MyBatis/OpenAPI/MQTT/对象存储/JWT +│ ├── main/java/.../statemachine/ # 四层状态机（49条规则, SELECT FOR UPDATE 行锁） │ ├── main/java/.../module/ # 16个业务模块 -│ │ ├── application/ # 服务申请 -│ │ ├── assessment/ # 能力评估 -│ │ ├── plan/ # 方案制定 -│ │ ├── schedule/ # 服务计划 + 调度算法 -│ │ ├── workorder/ # 工单管理 + Delivery + 管理端 -│ │ ├── execution/ # 执行记录 + 证据文件 -│ │ ├── acceptance/ # 验收评价 + 投诉反馈 -│ │ ├── settlement/ # 结算 + 支付 + 绩效 -│ │ ├── supervision/ # 过程监管（抽查/违规/整改） -│ │ ├── compliance/ # 合规管理（授权/脱敏/审计） -│ │ ├── notification/ # 通知 Outbox（并发锁+重试+死信） -│ │ ├── masterdata/ # 主数据（机构/人员/资质/服务项目/价格） -│ │ ├── capacity/ # 运力运营（网格/容量/预测） -│ │ ├── lead/ # 官网线索 -│ │ └── audit/ # 审计日志 -│ └── resources/db/migration/ # Flyway 迁移（V1~V6） +│ └── resources/db/migration/ # Flyway 迁移（V1~V12） │ ├── website/ # Nuxt3 产品官网 -│ ├── pages/ # 11个页面（含 /demo /platform/*） +│ ├── pages/ # 11个官网页面 + 5个平台管理页面 +│ ├── layouts/ # platform 布局组件 │ ├── components/ # 20+ 公共组件 -│ ├── composables/ # useLeadForm / useApi / usePlatformAuth -│ ├── data/ # 站点内容数据 -│ └── tests/ # Playwright E2E 测试 +│ └── tests/ # Playwright E2E (276用例) │ -├── delivery-miniapp/ # uni-app 服务人员移动端 +├── delivery-miniapp/ # uni-app 服务人员移动端 (12页面) ├── docker-compose.yml # 一键启动全栈 -└── Dockerfile # 后端构建镜像 +└── Dockerfile # JRE 运行时镜像 ``` ## 技术栈 @@ -50,7 +34,7 @@ hss-home-service/ | 前端官网 | Nuxt3 + Vue3 + Tailwind CSS 3.4 | | 移动端 | uni-app (Vue) | | 部署 | Docker Compose (Nginx + Spring Boot + PostgreSQL + Redis) | -| 测试 | Playwright (E2E) + JUnit (状态机) | +| 测试 | Playwright (E2E 276用例) + k6 (负载) | | API 文档 | OpenAPI 3.1 (Swagger) | ## 快速启动 @@ -65,38 +49,44 @@ docker compose up -d | 服务 | 地址 | 说明 | |------|------|------| | 官网首页 | `http://localhost:3080` | 产品官网 | -| 平台演示 | `http://localhost:3080/demo` | 4 Tab 平台功能展示 | -| 平台登录 | `http://localhost:3080/platform/login` | 9角色免密登录 | -| 全流程测试 | `http://localhost:3080/platform/workflow` | 一键执行14步数据流 | -| 后端 API | `http://localhost:18080` | 86个 REST 接口 | +| 平台登录 | `http://localhost:3080/platform/login` | 手机号+密码登录 | +| 全流程测试 | `http://localhost:3080/platform/workflow` | 一键执行 20 步闭环 | +| 后端 API | `http://localhost:18080` | REST API | | Swagger | `http://localhost:18080/swagger-ui/index.html` | OpenAPI 文档 | +测试账号：`13900000001` / `test123456` + ### 官网开发 ```bash cd hss-home-service/website npm install -npm run dev # 开发服务器 (hot reload) -npm run generate # 生产构建 → .output/public/ +npm run dev # 开发服务器 +npm run generate # 生产构建 ``` ### 运行测试 ```bash cd hss-home-service/website -npx playwright test # E2E 测试 (89用例) +npx playwright test # E2E (276用例) +/tmp/k6 run /tmp/k6-final.js # 负载测试 ``` ## 核心特性 -- **四层状态机**：申请→方案→工单→结算，49条转换规则，前端只传动作不传状态 -- **写幂等**：`Idempotency-Key` + `hss_idempotency_records` 落库 -- **通知 Outbox**：`FOR UPDATE SKIP LOCKED` 并发抢占 + 指数退避重试 + 死信 -- **审计追溯**：`@Auditable` 切面自动记录 + `hss_state_transitions` 全状态流转 +### 并发控制 +- **多层防护**：API限流 → Redis分布式锁 → SELECT FOR UPDATE行锁 → @Version乐观锁 → ON CONFLICT幂等 +- **支付回调**：SERIALIZABLE隔离 + RedisLock + ON CONFLICT 三层并发保护 +- **通知 Outbox**：`FOR UPDATE SKIP LOCKED` 多实例并发热取 + 指数退避重试 + 死信 +- **幂等写**：`Idempotency-Key` + Redis SET NX + `hss_idempotency_records` DB唯一约束 + +### 业务特性 +- **四层状态机**：49条转换规则，前端只传动作不传状态 +- **调度算法**：硬约束过滤 + 软约束评分（距离/技能/负载/评价/熟悉度）+ Top5推荐 +- **GPS签到**：Haversine公式距离校验 + GPS轨迹记录 - **数据脱敏**：姓名/手机/地址按角色分级展示 -- **调度算法**：硬约束过滤 + 软约束评分（距离/技能/负载/评价/熟悉度）+ Top5 推荐 -- **支付幂等**：`ON CONFLICT (transaction_id, settlement_id) DO NOTHING` -- **E2E 测试**：Playwright 覆盖全部页面 + API 连通性 + 幂等去重 +- **审计追溯**：`@Auditable` 切面 + `hss_state_transitions` 全状态流转 ## 数据流 @@ -108,11 +98,10 @@ hss_service_applications (申请) → hss_service_schedules (服务计划) → hss_work_orders (工单) → hss_work_order_items → hss_checkins (签到) + hss_execution_records (执行) + hss_evidence_files (证据) - → hss_exceptions (异常) → hss_exception_actions - → hss_spot_checks (抽查) → hss_violations (违规) → hss_corrections (整改) + → hss_exceptions (异常) → hss_acceptances (验收) → hss_complaints (投诉) - → hss_settlements (结算) → hss_settlement_items → hss_payments → hss_refunds - → hss_ledgers (归档) → hss_archive_files + → hss_settlements (结算) → hss_settlement_items → hss_payments + → hss_ledgers (归档) hss_notification_outbox + hss_notification_receipts (贯穿全程) hss_state_transitions + hss_audit_logs (贯穿全程) hss_consent_records + hss_data_access_logs (合规) @@ -120,47 +109,41 @@ hss_consent_records + hss_data_access_logs (合规) ## 数据库 -45 张表，以 `hss_` 为前缀。Flyway 管理迁移： +49 张表，以 `hss_` 为前缀。Flyway 管理迁移： | 版本 | 内容 | |------|------| | V1 | 30+ 核心业务表 | -| V2 | 主数据种子（区域/服务项目/价格/机构） | +| V2 | 主数据种子 | | V3 | 性能索引补充 | -| V4 | TIMESTAMPTZ→TIMESTAMP 兼容修复 | +| V4 | TIMESTAMPTZ 兼容修复 | | V5 | 状态流转唯一约束扩展 | | V6 | 官网线索表 | -| V7 | 服务地址经纬度（GPS 签到） | -| V8 | GPS 轨迹表 | -| V9 | 认证字段（密码哈希 + 登录时间） | -| V10 | 外键约束补充 | -| V11 | 消息表 + 系统配置表 + 离线同步日志 | -| V12 | 剩余外键 + 性能索引（phone/settlement_id 等） | +| V7~V8 | GPS 坐标 + 轨迹 | +| V9 | 认证字段（密码哈希 + 角色） | +| V10~V12 | 外键约束 + 性能索引补充 | -## 项目状态 +## 测试报告 -### 已完成 -- 后端 93 个 REST API + 四层状态机（49 条规则） -- 数据库 49 张表 + 12 个 Flyway 迁移 -- 官网 11 个页面（Nuxt3 + Tailwind CSS） -- 平台管理：注册/登录/申请管理/工单管理/全流程测试 -- delivery-miniapp 12 个页面（uni-app，含 GPS 签到/执行/异常/离线补传） -- 微信支付 SDK（JSAPI 下单 + 回调验签 + 退款） -- 调度算法（硬约束过滤 + Haversine 距离 + 资质匹配 + Top5 推荐） -- JWT 认证 + 角色权限 + 数据脱敏 -- Playwright E2E 测试（89 用例）+ CI/CD 管道 +| 测试 | 结果 | +|------|------| +| Playwright E2E | 268/276 (97.1%) | +| k6 并发压力 | 16,389 请求, 100% 成功率, P95 29ms | +| 全流程闭环 | 20 步全部通过 | -### 需外部服务接入 -| 服务 | 用途 | 优先级 | -|------|------|--------| -| MQTT Broker | delivery 端实时通知 | P0 | -| 微信订阅消息 API | 用户通知推送 | P0 | -| 短信 SDK | 紧急通知兜底 | P0 | -| 对象存储（MinIO/S3） | 证据文件存储 | P1 | -| 地图 API（高德/百度） | 调度距离 + ETA | P1 | -| 域名 + SSL + ICP 备案 | 生产上线 | P1 | +## 需外部服务接入 -### 相关文档 -- [待完善清单（终极版）](hss-home-service/待完善清单_终极版.md) — 62 项，含修复状态 -- [外部服务接入清单](hss-home-service/外部服务接入清单.md) — 9 项外部服务详细说明 -- [官网设计方案 Prompt](hss-home-service/官网设计方案Prompt.txt) +| 服务 | 用途 | 状态 | +|------|------|------| +| MQTT Broker | delivery 端实时通知 | MqttPublisher 已实现，待配置 broker | +| 微信订阅消息 API | 用户通知推送 | 标记 TODO | +| 短信 SDK | 紧急通知兜底 | 标记 TODO | +| 对象存储（MinIO/S3） | 证据文件存储 | ObjectStorageService (AWS SigV4) 已实现，待配置凭证 | +| 地图 API | 调度距离 + ETA | GeoUtil (Haversine) 已实现，ETA 待接入 | +| 域名 + SSL + ICP 备案 | 生产上线 | — | + +## 相关文档 + +- [系统实现与修复报告](docs/系统实现与修复报告.md) +- [待完善清单（终极版）](docs/待完善清单_终极版.md) — 62 项 +- [外部服务接入清单](docs/外部服务接入清单.md)