Home-Care/README.md

智慧医养居家上门服务平台

面向政府、医院、养老机构和社区服务中心的居家上门服务闭环管理平台。覆盖申请受理 → 能力评估 → 方案制定 → 智能派单 → 上门执行 → 过程监管 → 验收评价 → 结算归档全流程。

---

项目结构

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）

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

官网开发

cd hss-home-service/website
npm install
npm run dev          # 开发服务器
npm run generate     # 生产构建

运行测试

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 备案	生产上线	—

相关文档

• 系统实现与修复报告
• 待完善清单（终极版） — 62 项
• 外部服务接入清单