上传README.md

2026-05-19 11:06:37 +08:00
parent c02029a5f3
commit 7d92322b99
1 changed files with 131 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,132 @@
-# Home-Care
+# 智慧医养居家上门服务平台

-居家上门服务系统
+面向政府、医院、养老机构和社区服务中心的居家上门服务闭环管理平台。覆盖**申请受理 → 能力评估 → 方案制定 → 智能派单 → 上门执行 → 过程监管 → 验收评价 → 结算归档**全流程。
+
+---
+
+## 项目结构
+
+```
+hss-home-service/
+├── src/                          # Spring Boot 后端
+│   ├── main/java/.../common/     # 公共模块（响应体、异常、幂等、审计）
+│   ├── main/java/.../config/     # Security/Redis/MyBatis/OpenAPI 配置
+│   ├── main/java/.../statemachine/ # 四层状态机（申请/方案/工单/结算）
+│   ├── 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）
+│
+├── website/                      # Nuxt3 产品官网
+│   ├── pages/                    # 11个页面（含 /demo /platform/*）
+│   ├── components/               # 20+ 公共组件
+│   ├── composables/              # useLeadForm / useApi / usePlatformAuth
+│   ├── data/                     # 站点内容数据
+│   └── tests/                    # Playwright E2E 测试
+│
+├── delivery-miniapp/             # uni-app 服务人员移动端
+├── docker-compose.yml            # 一键启动全栈
+└── Dockerfile                    # 后端构建镜像
+```
+
+## 技术栈
+
+| 层 | 技术 |
+|---|---|
+| 后端 | 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) + JUnit (状态机) |
+| API 文档 | OpenAPI 3.1 (Swagger) |
+
+## 快速启动
+
+### 全栈启动（Docker）
+
+```bash
+cd hss-home-service
+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 接口 |
+| Swagger | `http://localhost:18080/swagger-ui/index.html` | OpenAPI 文档 |
+
+### 官网开发
+
+```bash
+cd hss-home-service/website
+npm install
+npm run dev          # 开发服务器 (hot reload)
+npm run generate     # 生产构建 → .output/public/
+```
+
+### 运行测试
+
+```bash
+cd hss-home-service/website
+npx playwright test        # E2E 测试 (89用例)
+```
+
+## 核心特性
+
+- **四层状态机**：申请→方案→工单→结算，49条转换规则，前端只传动作不传状态
+- **写幂等**：`Idempotency-Key` + `hss_idempotency_records` 落库
+- **通知 Outbox**：`FOR UPDATE SKIP LOCKED` 并发抢占 + 指数退避重试 + 死信
+- **审计追溯**：`@Auditable` 切面自动记录 + `hss_state_transitions` 全状态流转
+- **数据脱敏**：姓名/手机/地址按角色分级展示
+- **调度算法**：硬约束过滤 + 软约束评分（距离/技能/负载/评价/熟悉度）+ Top5 推荐
+- **支付幂等**：`ON CONFLICT (transaction_id, settlement_id) DO NOTHING`
+- **E2E 测试**：Playwright 覆盖全部页面 + API 连通性 + 幂等去重
+
+## 数据流
+
+```
+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_exception_actions
+  → hss_spot_checks (抽查) → hss_violations (违规) → hss_corrections (整改)
+  → hss_acceptances (验收) → hss_complaints (投诉)
+  → hss_settlements (结算) → hss_settlement_items → hss_payments → hss_refunds
+  → hss_ledgers (归档) → hss_archive_files
+hss_notification_outbox + hss_notification_receipts (贯穿全程)
+hss_state_transitions + hss_audit_logs (贯穿全程)
+hss_consent_records + hss_data_access_logs (合规)
+```
+
+## 数据库
+
+45 张表，以 `hss_` 为前缀。Flyway 管理迁移：
+
+| 版本 | 内容 |
+|------|------|
+| V1 | 30+ 核心业务表 |
+| V2 | 主数据种子（区域/服务项目/价格/机构） |
+| V3 | 性能索引补充 |
+| V4 | TIMESTAMPTZ→TIMESTAMP 兼容修复 |
+| V5 | 状态流转唯一约束扩展 |
+| V6 | 官网线索表 |