comclib
f81d9339d7
- README 更新：并发控制体系、测试报告、文档路径修正 - 删除 .github/workflows/ci.yml: 内部 Maven 仓库不可从 GitHub Actions 访问 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
150 lines
5.5 KiB
Markdown
150 lines
5.5 KiB
Markdown
# 智慧医养居家上门服务平台
|
||
|
||
面向政府、医院、养老机构和社区服务中心的居家上门服务闭环管理平台。覆盖**申请受理 → 能力评估 → 方案制定 → 智能派单 → 上门执行 → 过程监管 → 验收评价 → 结算归档**全流程。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
hss-home-service/
|
||
├── src/ # Spring Boot 后端
|
||
│ ├── 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个业务模块
|
||
│ └── resources/db/migration/ # Flyway 迁移（V1~V12）
|
||
│
|
||
├── website/ # Nuxt3 产品官网
|
||
│ ├── pages/ # 11个官网页面 + 5个平台管理页面
|
||
│ ├── layouts/ # platform 布局组件
|
||
│ ├── components/ # 20+ 公共组件
|
||
│ └── tests/ # Playwright E2E (276用例)
|
||
│
|
||
├── delivery-miniapp/ # uni-app 服务人员移动端 (12页面)
|
||
├── docker-compose.yml # 一键启动全栈
|
||
└── Dockerfile # JRE 运行时镜像
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| 后端 | 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 276用例) + k6 (负载) |
|
||
| API 文档 | OpenAPI 3.1 (Swagger) |
|
||
|
||
## 快速启动
|
||
|
||
### 全栈启动（Docker）
|
||
|
||
```bash
|
||
cd hss-home-service
|
||
docker compose up -d
|
||
```
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| 官网首页 | `http://localhost:3080` | 产品官网 |
|
||
| 平台登录 | `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 # 开发服务器
|
||
npm run generate # 生产构建
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
cd hss-home-service/website
|
||
npx playwright test # E2E (276用例)
|
||
/tmp/k6 run /tmp/k6-final.js # 负载测试
|
||
```
|
||
|
||
## 核心特性
|
||
|
||
### 并发控制
|
||
- **多层防护**：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轨迹记录
|
||
- **数据脱敏**：姓名/手机/地址按角色分级展示
|
||
- **审计追溯**：`@Auditable` 切面 + `hss_state_transitions` 全状态流转
|
||
|
||
## 数据流
|
||
|
||
```
|
||
hss_service_applications (申请)
|
||
→ hss_assessment_tasks (评估) → hss_assessment_reports
|
||
→ hss_objections (异议)
|
||
→ hss_service_plans (方案) → hss_plan_versions → hss_service_plan_items
|
||
→ hss_service_schedules (服务计划)
|
||
→ hss_work_orders (工单) → hss_work_order_items
|
||
→ hss_checkins (签到) + hss_execution_records (执行) + hss_evidence_files (证据)
|
||
→ hss_exceptions (异常)
|
||
→ hss_acceptances (验收) → hss_complaints (投诉)
|
||
→ 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 (合规)
|
||
```
|
||
|
||
## 数据库
|
||
|
||
49 张表，以 `hss_` 为前缀。Flyway 管理迁移：
|
||
|
||
| 版本 | 内容 |
|
||
|------|------|
|
||
| V1 | 30+ 核心业务表 |
|
||
| V2 | 主数据种子 |
|
||
| V3 | 性能索引补充 |
|
||
| V4 | TIMESTAMPTZ 兼容修复 |
|
||
| V5 | 状态流转唯一约束扩展 |
|
||
| V6 | 官网线索表 |
|
||
| V7~V8 | GPS 坐标 + 轨迹 |
|
||
| V9 | 认证字段（密码哈希 + 角色） |
|
||
| V10~V12 | 外键约束 + 性能索引补充 |
|
||
|
||
## 测试报告
|
||
|
||
| 测试 | 结果 |
|
||
|------|------|
|
||
| Playwright E2E | 268/276 (97.1%) |
|
||
| k6 并发压力 | 16,389 请求, 100% 成功率, P95 29ms |
|
||
| 全流程闭环 | 20 步全部通过 |
|
||
|
||
## 需外部服务接入
|
||
|
||
| 服务 | 用途 | 状态 |
|
||
|------|------|------|
|
||
| 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)
|