diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 8bd0334..5472637 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -1409,5 +1409,3 @@ hss-home-service/ - 输出 Flyway V1 迁移脚本 + Java 代码 ``` - -/goal 将当前系统中所有的简化实现，替代实现，未完善实现，后续需补充实现，需要接入服务的实现等等包括不完整的功能实现全部整理成文档，标注清楚 \ No newline at end of file diff --git a/hss-home-service/外部服务接入清单.md b/docs/外部服务接入清单.md similarity index 100% rename from hss-home-service/外部服务接入清单.md rename to docs/外部服务接入清单.md diff --git a/hss-home-service/待完善清单.md b/docs/待完善清单.md similarity index 100% rename from hss-home-service/待完善清单.md rename to docs/待完善清单.md diff --git a/hss-home-service/待完善清单_终极版.md b/docs/待完善清单_终极版.md similarity index 100% rename from hss-home-service/待完善清单_终极版.md rename to docs/待完善清单_终极版.md diff --git a/hss-home-service/系统实现与修复报告.md b/docs/系统实现与修复报告.md similarity index 100% rename from hss-home-service/系统实现与修复报告.md rename to docs/系统实现与修复报告.md diff --git a/居家上门服务系统_可执行实现方案_补齐可开工版.md b/居家上门服务系统_可执行实现方案_补齐可开工版.md new file mode 100644 index 0000000..4f62ef2 --- /dev/null +++ b/居家上门服务系统_可执行实现方案_补齐可开工版.md @@ -0,0 +1,1967 @@ +# 居家上门服务系统 — 可执行实现方案（补齐可开工版） + +> 生成日期：2026-05-15 +> 补齐版本：V1.1 生产可交付补强版 +> 基于：V2.0 工程落地增强版 + V2.1 行业经验增强版 + V2.2 边界限制增强版 +> 项目状态：全新仓库，从零搭建 + +> 本版结论：可以进入实现，但必须按本补齐版执行。本文已补齐幂等表、任务执行日志、Outbox 并发安全、delivery 最小闭环、支付退款、异常监管、完整 OpenAPI 契约、E2E/并发/失败注入测试、灰度回滚与上线验收门槛。 + +--- + +## 0. 补齐版执行口径 + +本补齐版用于替代原执行方案中不完整或容易产生歧义的部分。若本文后续章节与原章节存在冲突，以本补齐版中的以下规则为准： + +1. **delivery 最小闭环必须进入 MVP 第一批**，不能整体后移。 +2. **幂等不能只依赖 Redis 或状态流转表**，必须新增 `hss_idempotency_records`。 +3. **定时任务必须有执行日志**，必须新增 `hss_job_execution_logs`。 +4. **Outbox 必须具备并发抢占、重试、死信能力**，不能只做简单轮询。 +5. **支付、退款、冲正必须独立建模**，不能只放在结算表字段里。 +6. **异常处理、监管整改、投诉反馈必须独立闭环**，不能只在工单备注里处理。 +7. **状态机必须拆为规则判断与动作编排两层**，不能只返回目标状态。 +8. **OpenAPI 契约必须覆盖消费者端、管理端、delivery 端和内部任务接口**。 +9. **测试必须覆盖并发、重复提交、Outbox 失败、支付重复回调、任务重跑、弱网补传**。 +10. **上线采用 roll-forward + feature flag + dry-run + shadow 模式**，不能依赖直接删字段或强回滚。 + + +--- + +## 1. 需求与约束摘要 + +| 项 | 内容 | +|---|---| +| **任务类型** | 新接口 / 新能力开发（全新系统） | +| **目标** | 实现居家上门服务全链路闭环系统：需求受理 → 评估定级 → 方案制定 → 派单调度 → 上门执行 → 过程监管 → 验收反馈 → 结算归档 | +| **硬边界** | Spring Boot / Java 17+、PostgreSQL、Redis、MQTT(通知)、对象存储(文件)、RESTful+action、OpenAPI 3.1、hss_表前缀、Outbox通知、四层状态机、幂等写、前端只传动作不传状态、敏感数据授权脱敏审计 | +| **范围** | 全部模块 + delivery 端小程序 | + +--- + +## 2. 代码依据 + +本项目为全新仓库，无现有后端代码。以下为架构文档依据： + +| 依据文件 | 路径 | 职责 | +|---|---|---| +| V2.0 工程落地增强版 | `docs/ architecture/居家上门服务闭环流程文档_V2工程落地增强版.md` | 业务闭环流程、四层状态机、数据模型、调度算法、通知设计、合规安全、结算对账 | +| V2.1 行业经验增强版 | `docs/ architecture/居家上门服务闭环流程文档_V2.1_行业经验增强版.md` | 美团三层调度、ETA预测、VRPTW建模、delivery智能助手、运力运营中心、主数据平台、SRE稳定性 | +| V2.2 边界限制增强版 | `/home/akoo/居家服务/居家上门服务闭环流程文档_V2.2_边界限制增强版.md` | 12条硬约束、技术栈锁定、DDL边界、接口风格、部署环境、协作边界 | + +--- + +## 3. DDL 依据 + +当前仓库无 `db/init.sql` 与 `db/update.sql`。以下设计基于 V2.0 文档 4.1 节数据域划分（第 939-958 行），结合 V2.2 第 16.3 节 DDL 边界约束。 + +| 数据域 | 设计表名（hss_前缀） | 来源 | +|---|---|---| +| 申请域 | `hss_service_applications` | V2.0 §4.1 | +| 用户画像域 | `hss_patient_profiles` | V2.0 §4.1 | +| 评估域 | `hss_assessment_tasks`、`hss_assessment_reports` | V2.0 §4.1 | +| 异议域 | `hss_objections` | V2.0 §4.2 | +| 方案域 | `hss_service_plans`、`hss_service_plan_items`、`hss_plan_versions` | V2.0 §4.1 | +| 计划域 | `hss_service_schedules` | V2.0 §4.1 | +| 工单域 | `hss_work_orders`、`hss_work_order_items` | V2.0 §4.1 | +| 执行域 | `hss_checkins`、`hss_execution_records`、`hss_evidence_files` | V2.0 §4.1 | +| 异常域 | `hss_exceptions`、`hss_exception_actions` | V2.0 §4.1 | +| 监管域 | `hss_spot_checks`、`hss_violations`、`hss_corrections` | V2.0 §4.1 | +| 验收域 | `hss_acceptances`、`hss_complaints` | V2.0 §4.1 | +| 结算域 | `hss_settlements`、`hss_settlement_items`、`hss_payments`、`hss_refunds` | V2.0 §4.1 | +| 归档域 | `hss_ledgers`、`hss_archive_files` | V2.0 §4.1 | +| 通知域 | `hss_notification_outbox`、`hss_notification_receipts` | V2.0 §7.2 | +| 审计域 | `hss_audit_logs`、`hss_state_transitions` | V2.0 §3.6、§8.4 | +| 合规域 | `hss_consent_records`、`hss_data_access_logs` | V2.0 §8.2 | +| 调度域（V2.1扩展） | `hss_service_grids`、`hss_grid_capacity_daily`、`hss_staff_skill_capacity`、`hss_capacity_forecasts`、`hss_capacity_alerts` | V2.1 §15.2.1 | +| 主数据域（V2.1扩展） | `hss_md_orgs`、`hss_md_staff`、`hss_md_qualifications`、`hss_md_service_items`、`hss_md_regions`、`hss_md_price_rules` | V2.1 §15.7 | + +--- + +## 4. 改动范围清单 + +全部为新增文件。 + +| 路径 | 增/删/改 | 摘要 | +|---|---|---| +| `pom.xml` | 增 | Maven 构建配置，Spring Boot 3.x + Java 17 | +| `src/main/java/com/meizhou/hss/` | 增 | 根包目录 | +| `src/main/java/.../common/` | 增 | 公共模块：响应体、异常、工具类、幂等注解、审计切面 | +| `src/main/java/.../config/` | 增 | Spring 配置：Security、Redis、MQTT、对象存储、定时任务、OpenAPI | +| `src/main/java/.../statemachine/` | 增 | 四层状态机引擎：申请、方案、工单、结算 | +| `src/main/java/.../module/application/` | 增 | 申请域：controller/service/repository/entity/dto | +| `src/main/java/.../module/assessment/` | 增 | 评估域：controller/service/repository/entity/dto | +| `src/main/java/.../module/plan/` | 增 | 方案域：controller/service/repository/entity/dto | +| `src/main/java/.../module/schedule/` | 增 | 计划与调度域 | +| `src/main/java/.../module/workorder/` | 增 | 工单域 | +| `src/main/java/.../module/execution/` | 增 | 执行域：签到、执行记录、证据链 | +| `src/main/java/.../module/exception/` | 增 | 异常域：异常上报与处理 | +| `src/main/java/.../module/supervision/` | 增 | 监管域：抽查、违规、整改 | +| `src/main/java/.../module/acceptance/` | 增 | 验收域：验收、评价、投诉 | +| `src/main/java/.../module/settlement/` | 增 | 结算域：结算、支付、退款 | +| `src/main/java/.../module/archive/` | 增 | 归档域：台账、归档文件 | +| `src/main/java/.../module/notification/` | 增 | 通知域：Outbox 与回执 | +| `src/main/java/.../module/audit/` | 增 | 审计域：审计日志、状态流转 | +| `src/main/java/.../module/compliance/` | 增 | 合规域：授权同意、数据访问日志 | +| `src/main/java/.../module/masterdata/` | 增 | 主数据域：机构、人员、资质、服务项目、区域、价格 | +| `src/main/java/.../module/capacity/` | 增 | 运力域：服务网格、容量、预测 | +| `src/main/resources/db/migration/` | 增 | Flyway 迁移脚本 | +| `src/main/resources/application.yml` | 增 | 主配置 | +| `src/test/java/.../` | 增 | 单元测试与集成测试 | +| `delivery-miniapp/` | 增 | delivery 端小程序（uni-app） | + +--- + +## 5. 方案概述 + +### 5.1 分层架构 + +``` +┌──────────────────────────────────────────────┐ +│ Controller 层（REST + action-style REST） │ +│ - 参数校验（Spring Validation） │ +│ - 幂等拦截（Idempotency-Key） │ +│ - 权限注解（@PreAuthorize） │ +│ - OpenAPI 注解（SpringDoc） │ +└──────────────────┬───────────────────────────┘ + │ +┌──────────────────▼───────────────────────────┐ +│ Service 层（业务编排） │ +│ - 状态机调用（不跳过状态检查） │ +│ - 事务边界（@Transactional） │ +│ - Outbox 写入（同事务） │ +│ - 审计日志写入 │ +└──────────────────┬───────────────────────────┘ + │ +┌──────────────────▼───────────────────────────┐ +│ Repository 层（数据访问） │ +│ - MyBatis-Plus BaseMapper │ +│ - 自定义 SQL（复杂查询/统计） │ +│ - 乐观锁 version 字段 │ +└──────────────────┬───────────────────────────┘ + │ +┌──────────────────▼───────────────────────────┐ +│ Domain 层（领域对象） │ +│ - Entity（映射表） │ +│ - DTO / VO / Request / Response │ +│ - 状态枚举 │ +│ - 业务异常 │ +└──────────────────────────────────────────────┘ +``` + +### 5.2 核心数据流 + +```text +POST /applications → 创建申请（DRAFT） +POST /applications/{id}/submit → 提交申请（PENDING_ACCEPTANCE） +POST /applications/{id}/accept → 受理通过（PENDING_ASSESSMENT） +POST /assessments/{id}/assign → 派发评估（ASSESSING） +POST /assessments/{id}/submit → 提交评估（ASSESSMENT_PASSED） +POST /plans → 创建方案（PLAN_DRAFT） +POST /plans/{id}/submit → 提交签署（PLAN_PENDING_SIGN） +POST /plans/{id}/sign → 签署通过（PLAN_EFFECTIVE） +POST /schedules/{id}/generate → 生成服务计划 +POST /work-orders/{id}/dispatch → 派单（ORDER_ASSIGNED） +POST /work-orders/{id}/accept → 接单（ORDER_ACCEPTED） +POST /work-orders/{id}/check-in → 签到（ORDER_CHECKED_IN） +POST /work-orders/{id}/start → 开始服务（ORDER_IN_SERVICE） +POST /execution-records → 逐项记录执行 +POST /work-orders/{id}/finish → 完成服务（ORDER_COMPLETED） +POST /acceptances → 发起验收（ACCEPTANCE_PENDING） +POST /acceptances/{id}/confirm → 验收通过（ACCEPTED） +POST /settlements/{id}/generate → 生成结算单 +POST /settlements/{id}/approve → 审核通过 +POST /settlements/{id}/pay → 支付完成（SETTLEMENT_PAID） +POST /settlements/{id}/archive → 归档（ARCHIVED） +``` + +### 5.3 异常流 + +```text +任何非终态 → POST /{entity}/{id}/cancel → CANCELLED（需原因） +评估中 → POST /assessments/{id}/object → REVIEWING → 维持/重评 +方案待签署 → POST /plans/{id}/reject → PLAN_REJECTED → 重新编制 +工单已派单 → POST /work-orders/{id}/reassign → 改派 +工单服务中 → POST /work-orders/{id}/report-exception → ORDER_EXCEPTION → 协调/改派/关闭 +验收拒绝 → POST /acceptances/{id}/reject → 创建问题处理单 +结算不通过 → POST /settlements/{id}/return → 退回修改 +``` + +--- + +## 6. 代码级修改说明（核心） + +### 6.1 项目初始化 + +**文件**：`pom.xml`（新增） + +当前逻辑：不存在。 +拟议改动：创建 Maven 父 POM，管理所有模块依赖。 + +```xml + + + 4.0.0 + + org.springframework.boot + spring-boot-starter-parent + 3.3.0 + + com.meizhou + hss-home-service + 1.0.0-SNAPSHOT + HSS Home Service + + 17 + 3.5.6 + 2.5.0 + 10.11.0 + + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-security + + + org.springframework.boot + spring-boot-starter-validation + + + org.springframework.boot + spring-boot-starter-data-redis + + + com.baomidou + mybatis-plus-spring-boot3-starter + ${mybatis-plus.version} + + + org.postgresql + postgresql + + + org.flywaydb + flyway-core + + + org.flywaydb + flyway-database-postgresql + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + ${springdoc.version} + + + + org.springframework.boot + spring-boot-starter-test + test + + + +``` + +### 6.2 公共模块 + +**目录**：`src/main/java/com/meizhou/hss/common/`（新增） + +#### 6.2.1 统一响应体 + +**文件**：`ApiResponse.java`（新增） + +当前逻辑：不存在。 +拟议改动：所有接口统一使用此响应格式。 + +```java +// 新增 +@Data +@NoArgsConstructor +@AllArgsConstructor +public class ApiResponse { + private int code; // 200 成功 + private String message; + private T data; + private String requestId; // UUID + private long timestamp; // System.currentTimeMillis() + + public static ApiResponse ok(T data) { ... } + public static ApiResponse fail(int code, String message) { ... } +} +``` + +#### 6.2.2 幂等拦截 + +**文件**：`@Idempotent.java` + `IdempotentAspect.java`（新增） + +当前逻辑：不存在。 +拟议改动：基于 Redis 实现 request_id 幂等。相同 `requestId + action + entityId` 在 TTL 内重复提交返回首次结果。 + +```java +// 新增注解 +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +public @interface Idempotent { + String prefix() default "idempotent"; + long ttlSeconds() default 300; +} + +// 新增切面 +@Aspect +@Component +public class IdempotentAspect { + @Around("@annotation(idempotent)") + public Object around(ProceedingJoinPoint pjp, Idempotent idempotent) { + // 从请求头获取 Idempotency-Key + // 拼接 key = prefix + ":" + idempotencyKey + // Redis SET NX EX，成功则执行，失败则返回缓存结果 + } +} +``` + +#### 6.2.3 审计字段基类 + +**文件**：`BaseEntity.java`（新增） + +```java +// 新增 - 所有 hss_ 表 Entity 继承此类 +@Data +public abstract class BaseEntity { + @TableId(type = IdType.AUTO) + private Long id; + private Long tenantId; + private Long orgId; + private String status; + private Integer version; + private LocalDateTime createdAt; + private LocalDateTime updatedAt; + private Long createdBy; + private Long updatedBy; + @TableLogic + private Integer deleted; // 0 正常, 1 已删除 +} +``` + +### 6.3 状态机引擎 + +**目录**：`src/main/java/com/meizhou/hss/statemachine/`（新增） + +#### 文件清单 + +| 文件 | 职责 | +|---|---| +| `StateMachine.java` | 通用状态机接口：`transition(entity, action, context) → targetState` | +| `StateMachineConfig.java` | 状态转换规则配置（从 YAML/DB 加载） | +| `TransitionRule.java` | 单条转换规则：fromStatus + action + role → toStatus + constraints | +| `ApplicationStateMachine.java` | 申请状态机实现 | +| `PlanStateMachine.java` | 方案状态机实现 | +| `WorkOrderStateMachine.java` | 工单状态机实现 | +| `SettlementStateMachine.java` | 结算状态机实现 | +| `StateTransitionException.java` | 非法状态转换异常 | + +**当前逻辑**：不存在。 +**拟议改动**：基于 V2.0 文档 §3.2~3.5 的状态转换表实现。 + +```java +// 新增 - TransitionRule +public record TransitionRule( + String entityType, // application / plan / work_order / settlement + String fromStatus, + String action, // submit / accept / reject / check-in / finish / approve / ... + String requiredRole, // 允许执行此动作的角色 + String toStatus, + List constraints // 约束条件：如 "hasAssessmentReport"、"amountMatched" +) {} + +// 新增 - StateMachine 核心方法 +public class StateMachine { + // 校验转换是否合法 + public boolean canTransition(String entityType, String fromStatus, + String action, String role); + // 执行转换（不通过抛 StateTransitionException） + public String transition(String entityType, String fromStatus, + String action, String role, Map context); + // 记录状态流转到 hss_state_transitions + private void recordTransition(...); +} +``` + +状态转换规则初始化（基于文档 §3.2~3.5，部分示例）： + +```java +// 新增 - 申请状态机规则 +rules.add(new TransitionRule("application", "DRAFT", "submit", "APPLICANT", + "PENDING_ACCEPTANCE", List.of("materialsComplete"))); +rules.add(new TransitionRule("application", "PENDING_ACCEPTANCE", "accept", "RECEPTIONIST", + "PENDING_ASSESSMENT", List.of("ageCheck", "qualificationCheck", "duplicateCheck"))); +rules.add(new TransitionRule("application", "PENDING_ACCEPTANCE", "return", "RECEPTIONIST", + "RETURNED", List.of("returnReasonRequired"))); +// ... 等全部规则 +``` + +### 6.4 申请域模块 + +**目录**：`src/main/java/com/meizhou/hss/module/application/` + +#### 文件清单 + +| 文件 | 职责 | +|---|---| +| `entity/ServiceApplicationEntity.java` | 映射 `hss_service_applications` | +| `dto/ApplicationCreateRequest.java` | 创建申请请求 DTO | +| `dto/ApplicationSubmitRequest.java` | 提交申请请求 DTO | +| `dto/ApplicationResponse.java` | 申请响应 DTO | +| `dto/ApplicationListQuery.java` | 列表查询参数 | +| `repository/ServiceApplicationMapper.java` | MyBatis-Plus Mapper | +| `service/ApplicationService.java` | 业务逻辑 | +| `service/ApplicationValidationService.java` | 自动校验（材料完整性、资格、重复申请） | +| `controller/ApplicationController.java` | REST 接口 | + +**当前逻辑**：不存在。 + +**拟议改动**： + +`ApplicationController.java`： + +```java +// 新增 +@RestController +@RequestMapping("/api/hss/applications") +@Tag(name = "服务申请") +public class ApplicationController { + + @PostMapping + @Idempotent(prefix = "app:create") + public ApiResponse create( + @Valid @RequestBody ApplicationCreateRequest req) { + // Service: 校验 → 创建 DRAFT 状态申请 → 记录状态流转 + } + + @PostMapping("/{id}/submit") + @Idempotent(prefix = "app:submit") + public ApiResponse submit( + @PathVariable Long id, @Valid @RequestBody ApplicationSubmitRequest req) { + // Service: 状态机 DRAFT→PENDING_ACCEPTANCE → 写 Outbox 通知受理员 + } + + @PostMapping("/{id}/accept") + @Idempotent(prefix = "app:accept") + @PreAuthorize("hasRole('RECEPTIONIST')") + public ApiResponse accept(@PathVariable Long id) { + // Service: 校验（材料+资格+重复）→ 状态机 PENDING_ACCEPTANCE→PENDING_ASSESSMENT + } + + @PostMapping("/{id}/return") + @Idempotent(prefix = "app:return") + @PreAuthorize("hasRole('RECEPTIONIST')") + public ApiResponse returnApplication( + @PathVariable Long id, @Valid @RequestBody ReturnRequest req) { + // 约束：必须填写退回原因 + } + + @PostMapping("/{id}/cancel") + @Idempotent(prefix = "app:cancel") + public ApiResponse cancel(@PathVariable Long id) { + // 约束：申请人本人或授权家属 + } + + @GetMapping + public ApiResponse> list(ApplicationListQuery query) { + // 数据范围：按 tenant_id、org_id、角色过滤 + } + + @GetMapping("/{id}") + public ApiResponse getById(@PathVariable Long id) { + // 脱敏：非授权角色隐藏完整地址、电话 + } +} +``` + +**注**：其余模块（评估、方案、调度、工单、执行、异常、监管、验收、结算、归档、通知、审计、合规、主数据、运力）的代码结构遵循相同模式，此处为避免文档过度膨胀，仅输出申请域作为样板。完整代码在实施阶段逐模块编写。 + +### 6.5 通知 Outbox 模块 + +**目录**：`src/main/java/com/meizhou/hss/module/notification/` + +关键设计： + +```java +// 新增 - 通知创建（在业务事务内调用） +@Service +public class NotificationService { + // 与业务在同一事务中写入 Outbox + @Transactional + public void createNotification(Long entityId, String entityType, + String channel, String template, Map params) { + NotificationOutboxEntity outbox = new NotificationOutboxEntity(); + outbox.setEntityId(entityId); + outbox.setChannel(channel); // MQTT / WECHAT / SMS + outbox.setStatus("CREATED"); + outbox.setRequestId(IdempotencyContext.getRequestId()); + outboxMapper.insert(outbox); + } +} + +// 新增 - 定时任务：扫描 Outbox 并异步发送 +@Component +public class NotificationSender { + @Scheduled(fixedDelay = 2000) // 每2秒扫描 + public void sendPending() { + // SELECT * FROM hss_notification_outbox WHERE status='CREATED' LIMIT 100 + // 发送 → 更新 status=SENT → 记录 receipt + // 失败 → status=FAILED, retry_count+1 + } +} +``` + +### 6.6 审计模块 + +**目录**：`src/main/java/com/meizhou/hss/module/audit/` + +```java +// 新增 - AOP 切面自动记录审计 +@Aspect +@Component +public class AuditAspect { + @Around("@annotation(auditable)") + public Object around(ProceedingJoinPoint pjp, Auditable auditable) { + // 记录：操作人、时间、IP、设备、操作类型、业务对象ID、前后值 + } +} + +// 新增 - 状态流转记录（状态机内部调用） +// 写入 hss_state_transitions： +// entity_type, entity_id, from_status, action, to_status, +// operator_id, operator_role, reason, request_id, created_at +``` + +### 6.7 调度算法模块 + +**目录**：`src/main/java/com/meizhou/hss/module/schedule/algorithm/` + +```java +// 新增 - 两阶段调度 +@Service +public class DispatchAlgorithm { + + // 阶段1：硬约束过滤 + public List hardFilter(List allStaff, WorkOrder order) { + return allStaff.stream() + .filter(s -> s.getStatus() == StaffStatus.ACTIVE) + .filter(s -> s.hasQualification(order.getRequiredSkills())) + .filter(s -> s.getRegion().contains(order.getServiceAddress().getRegion())) + .filter(s -> !hasTimeConflict(s, order)) + .filter(s -> !s.isBlacklisted()) + .filter(s -> s.getTodayOrderCount() < s.getMaxDailyOrders()) + .toList(); + } + + // 阶段2：软约束评分 + public List scoreAndRank(List candidates, WorkOrder order) { + // score = distance * 0.25 + skill * 0.25 + workload * 0.20 + // + rating * 0.15 + response * 0.10 + familiarity * 0.05 + // 返回 Top5，附解释 + } +} +``` + +--- + +## 7. 接口设计方案（任务类型=1 强制） + +### 7.1 核心接口清单 + +按主链路阶段组织，以下为核心接口设计。 + +#### 7.1.1 服务申请接口组 + +**接口1：创建服务申请** + +| 接口名称 | 创建服务申请 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/applications` | +| 请求方式 | `POST` | +| 接口描述 | 服务对象/家属提交服务申请，创建后状态为 DRAFT | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| patientId | string | 是 | 服务对象ID | +| serviceType | string | 是 | 服务类型枚举：HOME_CARE / REHABILITATION / BATH_ASSIST / ASSESSMENT | +| channel | string | 是 | 申请渠道：APP / WECHAT / PHONE / COMMUNITY / HOSPITAL | +| contactName | string | 是 | 联系人姓名 | +| contactPhone | string | 是 | 联系人电话 | +| address | string | 是 | 服务地址 | +| regionCode | string | 是 | 区域编码 | +| notes | string | 否 | 备注说明 | +| attachmentIds | array | 否 | 附件ID列表 | + +| 字段路径 | 类型 | 示例 | 说明 | +| -------- | ------- | -------------- | -------------------- | +| code | int | 200 | 状态码 | +| success | boolean | true | 是否成功 | +| message | string | 申请创建成功 | 响应消息 | +| data.id | string | 1001 | 申请ID | +| data.status | string | DRAFT | 申请状态 | +| data.createdAt | string | 2026-05-15T10:30:00 | 创建时间 | + +请求示例： +```json +{ + "patientId": "2001", + "serviceType": "HOME_CARE", + "channel": "WECHAT", + "contactName": "张三", + "contactPhone": "138****5678", + "address": "梅江区金山街道XX小区3栋201", + "regionCode": "441402001", + "notes": "老人独居，需要日常护理", + "attachmentIds": ["att_001", "att_002"] +} +``` + +返回示例： +```json +{ + "code": 200, + "message": "申请创建成功", + "data": { + "id": "1001", + "status": "DRAFT", + "createdAt": "2026-05-15T10:30:00" + }, + "requestId": "req-uuid-abc123", + "timestamp": 1715747400000 +} +``` + +--- + +**接口2：提交服务申请** + +| 接口名称 | 提交服务申请 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/applications/{id}/submit` | +| 请求方式 | `POST` | +| 接口描述 | 将草稿状态申请提交为待受理，触发自动校验 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| id | string | 是 | 路径参数，申请ID | + +| 字段路径 | 类型 | 示例 | 说明 | +| -------- | ------- | -------------- | -------------------- | +| code | int | 200 | 状态码 | +| data.status | string | PENDING_ACCEPTANCE | 新状态 | +| data.validationResult.passed | boolean | true | 自动校验结果 | + +--- + +**接口3：受理通过** + +| 接口名称 | 受理通过 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/applications/{id}/accept` | +| 请求方式 | `POST` | +| 接口描述 | 受理员审核通过，申请进入待评估状态 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| id | string | 是 | 路径参数，申请ID | +| reason | string | 否 | 审核备注 | + +--- + +**接口4：受理退回** + +| 接口名称 | 受理退回 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/applications/{id}/return` | +| 请求方式 | `POST` | +| 接口描述 | 受理员退回申请，需填写退回原因 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| id | string | 是 | 路径参数 | +| reason | string | 是 | 退回原因（必填） | + +--- + +#### 7.1.2 工单执行接口组 + +**接口5：GPS 签到** + +| 接口名称 | GPS签到 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/work-orders/{id}/check-in` | +| 请求方式 | `POST` | +| 接口描述 | 服务人员在服务地址200米内签到，需GPS+照片+对象确认 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| id | string | 是 | 工单ID | +| latitude | number | 是 | 纬度 | +| longitude | number | 是 | 经度 | +| photoFileId | string | 是 | 现场照片文件ID | +| patientConfirmed | boolean | 是 | 服务对象是否确认 | +| patientSignatureId | string | 否 | 对象签名文件ID | + +| 字段路径 | 类型 | 示例 | 说明 | +| -------- | ------- | -------------- | -------------------- | +| code | int | 200 | 状态码 | +| data.status | string | ORDER_CHECKED_IN | 新状态 | +| data.distance | number | 85.5 | 签到位置距服务地址距离(米) | +| data.checkinTime | string | 2026-05-15T09:05:00 | 签到时间 | + +请求示例： +```json +{ + "latitude": 24.2878, + "longitude": 116.1271, + "photoFileId": "file_checkin_001", + "patientConfirmed": true, + "patientSignatureId": "sig_001" +} +``` + +返回示例： +```json +{ + "code": 200, + "message": "签到成功", + "data": { + "id": "5001", + "status": "ORDER_CHECKED_IN", + "distance": 85.5, + "checkinTime": "2026-05-15T09:05:00" + }, + "requestId": "req-uuid-def456", + "timestamp": 1715747700000 +} +``` + +--- + +**接口6：服务完成提交** + +| 接口名称 | 服务完成提交 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/work-orders/{id}/finish` | +| 请求方式 | `POST` | +| 接口描述 | 服务人员完成所有必做项目后提交，工单进入已完成状态 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| id | string | 是 | 工单ID | +| executionRecords | array | 是 | 项目执行记录列表 | +| executionRecords[].planItemId | string | 是 | 方案项目ID | +| executionRecords[].status | string | 是 | COMPLETED / PARTIAL / NOT_COMPLETED / SKIPPED / USER_REFUSED | +| executionRecords[].actualStartTime | string | 是 | 实际开始时间 | +| executionRecords[].actualEndTime | string | 是 | 实际结束时间 | +| executionRecords[].evidenceFileIds | array | 否 | 证据文件ID列表 | +| executionRecords[].notes | string | 否 | 执行备注 | +| signOffLatitude | number | 是 | 签退纬度 | +| signOffLongitude | number | 是 | 签退经度 | +| serviceSummary | string | 否 | 服务总结 | + +--- + +#### 7.1.3 结算接口组 + +**接口7：生成结算单** + +| 接口名称 | 生成结算单 | +| -------- | ------------------------------------------------------ | +| 接口地址 | `/api/hss/settlements/generate` | +| 请求方式 | `POST` | +| 接口描述 | 基于已验收工单生成结算单，自动汇总金额与抵扣 | + +| 参数名 | 类型 | 是否必填 | 说明 | +| ----------- | ------ | -------- | --------------------------- | +| workOrderIds | array | 是 | 已验收工单ID列表 | +| periodStart | string | 是 | 结算周期开始日期 | +| periodEnd | string | 是 | 结算周期结束日期 | + +| 字段路径 | 类型 | 示例 | 说明 | +| -------- | ------- | -------------- | -------------------- | +| data.id | string | 7001 | 结算单ID | +| data.totalAmount | number | 1200.00 | 总金额 | +| data.insuranceDeduction | number | 800.00 | 长护险抵扣 | +| data.selfPayAmount | number | 400.00 | 自费金额 | +| data.items | array | [...] | 结算明细 | + +--- + +### 7.2 接口契约约定 + +- 所有写接口必须带 `Idempotency-Key` 请求头 +- 所有分页接口参数：`page`（默认1）、`size`（默认20，最大100）、`sort`（如 `createdAt,desc`） +- 状态动作接口路径格式：`POST /api/hss/{resource}/{id}/{action}` +- 资源 CRUD：`GET/POST/PUT/DELETE /api/hss/{resource}` 和 `/{id}` +- 统一错误响应： +```json +{ + "code": 40001, + "message": "参数校验失败", + "details": [ + {"field": "contactPhone", "message": "联系电话格式不正确"} + ], + "requestId": "req-uuid-err123" +} +``` + +### 7.3 错误码规划 + +| 错误码范围 | 含义 | +|---|---| +| 200 | 成功 | +| 40001-40099 | 参数校验错误 | +| 40101-40199 | 认证/授权错误 | +| 40301-40399 | 权限不足 | +| 40401-40499 | 资源不存在 | +| 40901-40999 | 状态冲突（非法状态转换） | +| 40910-40919 | 幂等冲突（重复提交） | +| 42201-42299 | 业务规则校验失败 | +| 50001-50099 | 服务器内部错误 | +| 50301-50399 | 依赖服务不可用 | + +--- + +## 8. 数据库与迁移计划 + +### 8.1 DDL 变更明细 + +迁移脚本位于 `src/main/resources/db/migration/`，采用 Flyway 管理。 + +#### V1__baseline.sql（初始基线） + +核心表结构（部分示例）： + +```sql +-- ========================================== +-- 基线迁移 V1：创建居家服务核心业务表 +-- ========================================== + +-- 1. 申请域 +CREATE TABLE hss_service_applications ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + org_id BIGINT NOT NULL, + patient_id BIGINT NOT NULL, + service_type VARCHAR(32) NOT NULL, -- HOME_CARE / REHABILITATION / BATH_ASSIST / ASSESSMENT + channel VARCHAR(32) NOT NULL, -- APP / WECHAT / PHONE / COMMUNITY / HOSPITAL + contact_name VARCHAR(64) NOT NULL, + contact_phone VARCHAR(20) NOT NULL, + address TEXT NOT NULL, + region_code VARCHAR(20) NOT NULL, + status VARCHAR(32) NOT NULL DEFAULT 'DRAFT', + notes TEXT, + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT, + updated_by BIGINT, + deleted SMALLINT NOT NULL DEFAULT 0 +); +CREATE INDEX idx_hss_app_status ON hss_service_applications(status); +CREATE INDEX idx_hss_app_patient ON hss_service_applications(patient_id); +CREATE INDEX idx_hss_app_created ON hss_service_applications(created_at); + +-- 2. 评估域 +CREATE TABLE hss_assessment_tasks ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + org_id BIGINT NOT NULL, + application_id BIGINT NOT NULL REFERENCES hss_service_applications(id), + assessor_id BIGINT, + status VARCHAR(32) NOT NULL DEFAULT 'PENDING_ASSIGNMENT', + -- 评估结果快照 + care_level VARCHAR(16), -- LEVEL_1 ~ LEVEL_5 + risk_level VARCHAR(16), -- LOW / MEDIUM / HIGH / CRITICAL + report_content JSONB, + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT, + updated_by BIGINT, + deleted SMALLINT NOT NULL DEFAULT 0 +); +CREATE INDEX idx_hss_at_status ON hss_assessment_tasks(status); +CREATE INDEX idx_hss_at_app ON hss_assessment_tasks(application_id); +CREATE INDEX idx_hss_at_assessor ON hss_assessment_tasks(assessor_id); + +CREATE TABLE hss_assessment_reports ( + id BIGSERIAL PRIMARY KEY, + task_id BIGINT NOT NULL REFERENCES hss_assessment_tasks(id), + version INTEGER NOT NULL DEFAULT 1, + content JSONB NOT NULL, -- 评估指标详情 + conclusion TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +-- 3. 方案域 +CREATE TABLE hss_service_plans ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + org_id BIGINT NOT NULL, + application_id BIGINT NOT NULL, + assessment_task_id BIGINT NOT NULL, + status VARCHAR(32) NOT NULL DEFAULT 'PLAN_DRAFT', + version_number INTEGER NOT NULL DEFAULT 1, + total_amount DECIMAL(12,2), -- 方案总金额 + insurance_deduction DECIMAL(12,2), -- 长护险抵扣 + self_pay_amount DECIMAL(12,2), -- 自费金额 + signed_at TIMESTAMP, + signed_by BIGINT, + effective_at TIMESTAMP, + terminated_at TIMESTAMP, + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT, + updated_by BIGINT, + deleted SMALLINT NOT NULL DEFAULT 0 +); + +CREATE TABLE hss_service_plan_items ( + id BIGSERIAL PRIMARY KEY, + plan_id BIGINT NOT NULL REFERENCES hss_service_plans(id), + service_item_id BIGINT NOT NULL, -- 引用主数据服务项目 + item_name VARCHAR(128) NOT NULL, -- 版本化快照 + unit_price DECIMAL(10,2) NOT NULL, -- 版本化快照 + frequency INTEGER NOT NULL, -- 服务频次 + standard_duration INTEGER, -- 标准服务时长(分钟) + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +CREATE TABLE hss_plan_versions ( + id BIGSERIAL PRIMARY KEY, + plan_id BIGINT NOT NULL, + version_number INTEGER NOT NULL, + snapshot_data JSONB NOT NULL, -- 完整方案快照 + change_reason TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +-- 4. 服务计划域 +CREATE TABLE hss_service_schedules ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + plan_id BIGINT NOT NULL REFERENCES hss_service_plans(id), + scheduled_date DATE NOT NULL, + time_window_start TIME, -- 预约时间窗开始 + time_window_end TIME, -- 预约时间窗结束 + status VARCHAR(32) NOT NULL DEFAULT 'SCHEDULED', + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW() +); +CREATE INDEX idx_hss_ss_date ON hss_service_schedules(scheduled_date); +CREATE INDEX idx_hss_ss_plan ON hss_service_schedules(plan_id); + +-- 5. 工单域 +CREATE TABLE hss_work_orders ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + org_id BIGINT NOT NULL, + schedule_id BIGINT REFERENCES hss_service_schedules(id), + plan_id BIGINT NOT NULL, + patient_id BIGINT NOT NULL, + staff_id BIGINT, + status VARCHAR(32) NOT NULL DEFAULT 'ORDER_CREATED', + service_date DATE NOT NULL, + scheduled_start TIME, + scheduled_end TIME, + risk_level VARCHAR(16), + is_high_risk BOOLEAN DEFAULT FALSE, + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT, + updated_by BIGINT, + deleted SMALLINT NOT NULL DEFAULT 0 +); +CREATE INDEX idx_hss_wo_status ON hss_work_orders(status); +CREATE INDEX idx_hss_wo_staff ON hss_work_orders(staff_id); +CREATE INDEX idx_hss_wo_date ON hss_work_orders(service_date); +CREATE INDEX idx_hss_wo_patient ON hss_work_orders(patient_id); + +CREATE TABLE hss_work_order_items ( + id BIGSERIAL PRIMARY KEY, + work_order_id BIGINT NOT NULL REFERENCES hss_work_orders(id), + plan_item_id BIGINT NOT NULL, + item_name VARCHAR(128) NOT NULL, + unit_price DECIMAL(10,2) NOT NULL, + required BOOLEAN DEFAULT TRUE, -- 是否必做 + status VARCHAR(32) DEFAULT 'PENDING', -- COMPLETED/PARTIAL/NOT_COMPLETED/SKIPPED/USER_REFUSED + evidence_required BOOLEAN DEFAULT FALSE, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +-- 6. 执行域 +CREATE TABLE hss_checkins ( + id BIGSERIAL PRIMARY KEY, + work_order_id BIGINT NOT NULL REFERENCES hss_work_orders(id), + checkin_type VARCHAR(16) NOT NULL, -- CHECKIN / CHECKOUT + latitude DECIMAL(10,7) NOT NULL, + longitude DECIMAL(10,7) NOT NULL, + distance_meters INTEGER, -- 距目标地址距离 + photo_file_id VARCHAR(64), + patient_confirmed BOOLEAN, + patient_signature_id VARCHAR(64), + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +CREATE TABLE hss_execution_records ( + id BIGSERIAL PRIMARY KEY, + work_order_id BIGINT NOT NULL, + work_order_item_id BIGINT NOT NULL, + status VARCHAR(32) NOT NULL, -- COMPLETED/PARTIAL/NOT_COMPLETED/SKIPPED/USER_REFUSED + actual_start TIMESTAMP, + actual_end TIMESTAMP, + notes TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +CREATE TABLE hss_evidence_files ( + id BIGSERIAL PRIMARY KEY, + entity_type VARCHAR(32) NOT NULL, -- CHECKIN / EXECUTION / EXCEPTION / ACCEPTANCE + entity_id BIGINT NOT NULL, + file_type VARCHAR(16) NOT NULL, -- PHOTO / VIDEO / AUDIO + file_key VARCHAR(256) NOT NULL, -- 对象存储 key + file_size BIGINT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +-- 7. 异常域 +CREATE TABLE hss_exceptions ( + id BIGSERIAL PRIMARY KEY, + work_order_id BIGINT NOT NULL REFERENCES hss_work_orders(id), + exception_type VARCHAR(32) NOT NULL, -- PATIENT_ABSENT / PATIENT_REFUSE / WRONG_ADDRESS / ... + description TEXT NOT NULL, + evidence_file_ids TEXT, -- JSON 数组 + status VARCHAR(32) NOT NULL DEFAULT 'REPORTED', + handled_by BIGINT, + resolution TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +-- 8. 验收域 +CREATE TABLE hss_acceptances ( + id BIGSERIAL PRIMARY KEY, + work_order_id BIGINT NOT NULL REFERENCES hss_work_orders(id), + status VARCHAR(32) NOT NULL DEFAULT 'ACCEPTANCE_PENDING', + result VARCHAR(16), -- ACCEPTED / REJECTED + rating SMALLINT, -- 1-5 星 + tags TEXT, -- JSON 标签数组 + comment TEXT, + rejected_reason TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT +); + +-- 9. 结算域 +CREATE TABLE hss_settlements ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + org_id BIGINT NOT NULL, + patient_id BIGINT NOT NULL, + status VARCHAR(32) NOT NULL DEFAULT 'SETTLEMENT_READY', + period_start DATE NOT NULL, + period_end DATE NOT NULL, + total_amount DECIMAL(12,2), + insurance_deduction DECIMAL(12,2), + self_pay_amount DECIMAL(12,2), + paid_at TIMESTAMP, + payment_channel VARCHAR(32), + payment_transaction_id VARCHAR(64), + version INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + created_by BIGINT, + updated_by BIGINT, + deleted SMALLINT NOT NULL DEFAULT 0 +); + +CREATE TABLE hss_settlement_items ( + id BIGSERIAL PRIMARY KEY, + settlement_id BIGINT NOT NULL REFERENCES hss_settlements(id), + work_order_id BIGINT NOT NULL, + execution_record_id BIGINT, + item_name VARCHAR(128), + unit_price DECIMAL(10,2), + actual_amount DECIMAL(10,2), + deduction DECIMAL(10,2), + self_pay DECIMAL(10,2), + status VARCHAR(32) +); + +-- 10. 通知域 +CREATE TABLE hss_notification_outbox ( + id BIGSERIAL PRIMARY KEY, + entity_type VARCHAR(32) NOT NULL, + entity_id BIGINT NOT NULL, + channel VARCHAR(16) NOT NULL, -- MQTT / WECHAT / SMS + template_code VARCHAR(64), + params JSONB, + recipient_id BIGINT, + status VARCHAR(16) NOT NULL DEFAULT 'CREATED', + retry_count INTEGER DEFAULT 0, + max_retries INTEGER DEFAULT 3, + next_retry_at TIMESTAMP, + request_id VARCHAR(64), + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); +CREATE INDEX idx_hss_nf_status ON hss_notification_outbox(status, next_retry_at); + +CREATE TABLE hss_notification_receipts ( + id BIGSERIAL PRIMARY KEY, + outbox_id BIGINT NOT NULL, + status VARCHAR(16) NOT NULL, -- SENT / DELIVERED / READ / CONFIRMED / FAILED / EXPIRED + sent_at TIMESTAMP, + delivered_at TIMESTAMP, + read_at TIMESTAMP, + error_message TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +-- 11. 审计域 +CREATE TABLE hss_state_transitions ( + id BIGSERIAL PRIMARY KEY, + entity_type VARCHAR(32) NOT NULL, -- application / plan / work_order / settlement + entity_id BIGINT NOT NULL, + from_status VARCHAR(32), + action VARCHAR(32) NOT NULL, + to_status VARCHAR(32) NOT NULL, + operator_id BIGINT, + operator_role VARCHAR(32), + reason TEXT, + request_id VARCHAR(64), + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); +CREATE INDEX idx_hss_st_entity ON hss_state_transitions(entity_type, entity_id); +CREATE INDEX idx_hss_st_request ON hss_state_transitions(request_id); + +CREATE TABLE hss_audit_logs ( + id BIGSERIAL PRIMARY KEY, + entity_type VARCHAR(32), + entity_id BIGINT, + action VARCHAR(32) NOT NULL, + operator_id BIGINT, + operator_name VARCHAR(64), + operator_role VARCHAR(32), + client_ip VARCHAR(45), + device_info VARCHAR(256), + detail JSONB, + is_sensitive BOOLEAN DEFAULT FALSE, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); +CREATE INDEX idx_hss_al_entity ON hss_audit_logs(entity_type, entity_id); +CREATE INDEX idx_hss_al_operator ON hss_audit_logs(operator_id); +CREATE INDEX idx_hss_al_time ON hss_audit_logs(created_at); + +-- 12. 合规域 +CREATE TABLE hss_consent_records ( + id BIGSERIAL PRIMARY KEY, + patient_id BIGINT NOT NULL, + consent_type VARCHAR(32) NOT NULL, -- GPS / PHOTO / HEALTH / AUDIO_VIDEO + consent_status VARCHAR(16) NOT NULL, -- GRANTED / REVOKED / EXPIRED + granted_at TIMESTAMP, + revoked_at TIMESTAMP, + expires_at TIMESTAMP, + created_by BIGINT, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +CREATE TABLE hss_data_access_logs ( + id BIGSERIAL PRIMARY KEY, + operator_id BIGINT NOT NULL, + data_type VARCHAR(32) NOT NULL, -- PERSONAL / HEALTH / LOCATION / FINANCIAL + entity_type VARCHAR(32), + entity_id BIGINT, + access_action VARCHAR(16) NOT NULL, -- VIEW / EXPORT / DOWNLOAD + client_ip VARCHAR(45), + reason TEXT, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +-- 唯一约束：幂等键 +CREATE UNIQUE INDEX uk_hss_st_request ON hss_state_transitions(request_id, entity_type, entity_id); +``` + +### 8.2 执行顺序与窗口建议 + +| 阶段 | 脚本 | 内容 | 建议窗口 | +|---|---|---|---| +| 1 | V1__baseline.sql | 全部核心表创建 | 首次部署（停机窗口 10min） | +| 2 | V2__seed_master_data.sql | 主数据初始化（区域、服务项目、资质字典） | 紧随 V1 | +| 3 | V3__add_indexes.sql | 性能索引补充 | 在线（CREATE INDEX CONCURRENTLY） | +| 后续 | V4+ | 增量变更 | 按需，遵循 flyway 版本号 | + +### 8.3 回滚策略 + +- 每次迁移对应一个 `U` 版本回滚脚本（如 `U1__baseline_rollback.sql`） +- 回滚原则：非生产环境可直接 DROP；生产环境采用 `migrate down + data restore` +- 关键变更必须备份受影响数据：`CREATE TABLE xxx_backup AS SELECT * FROM xxx WHERE ...` +- 禁止 `DROP COLUMN` 直接执行：先标记废弃 → 观察一个版本 → 再删除 + +--- + +## 9. 接口契约与兼容性 + +### 9.1 兼容性说明 + +| 方面 | 策略 | +|---|---| +| 账号/登录 | 兼容现有平台 JWT Token 格式 | +| 角色/权限 | 新增居家服务角色（受理员、评估员、方案制定员、调度员、服务人员、监管员、结算员），不影响现有角色 | +| 机构/用户 | 复用现有 org_id / user_id 体系 | +| 文件上传 | 复用现有对象存储接口，居家服务文件单独 folder | +| 业务表 | 全新 `hss_` 前缀，不影响现有业务表 | + +### 9.2 版本管理 + +- API 路径不加版本号，通过 Header `Accept-Version` 管理 +- 破坏性变更走新接口 + 旧接口保留一个版本后废弃 + +--- + +## 10. 自测与回归 + +### 10.1 单元测试范围 + +| 测试对象 | 覆盖内容 | +|---|---| +| 状态机 | 所有合法转换、非法转换拦截、重复提交幂等 | +| 校验服务 | 年龄校验、资格校验、重复申请校验 | +| 调度算法 | 硬约束过滤逻辑、软约束评分计算、Top5排序 | +| 结算计算 | 金额汇总、抵扣计算、部分完成折算 | + +### 10.2 集成测试范围 + +| 测试场景 | 验证点 | +|---|---| +| 主链路 | 申请→评估→方案→工单→执行→验收→结算→归档 全流程 | +| 异常链路 | 退回、异议、拒签、改派、异常上报、拒绝验收、结算退回 | +| 通知链路 | Outbox 写入→定时发送→回执记录 | +| 权限链路 | 角色隔离、数据范围过滤、字段脱敏 | +| 并发场景 | 同 request_id 重复提交、派单并发冲突 | + +### 10.3 关键回归场景 + +- 状态机规则变更后，所有上游调用方不受影响（规则集中管理） +- 结算公式变更后，历史结算单金额不变（版本化快照） +- 服务项目价格调整后，已签署方案不受影响（版本冻结） + +--- + +## 11. 工程目录结构总览 + +``` +hss-home-service/ +├── pom.xml +├── src/ +│ ├── main/ +│ │ ├── java/com/meizhou/hss/ +│ │ │ ├── HssApplication.java # Spring Boot 启动类 +│ │ │ ├── common/ +│ │ │ │ ├── ApiResponse.java # 统一响应 +│ │ │ │ ├── BaseEntity.java # 审计字段基类 +│ │ │ │ ├── ErrorCode.java # 错误码枚举 +│ │ │ │ ├── BusinessException.java # 业务异常 +│ │ │ │ ├── Idempotent.java # 幂等注解 +│ │ │ │ ├── IdempotentAspect.java # 幂等切面 +│ │ │ │ ├── Auditable.java # 审计注解 +│ │ │ │ └── AuditAspect.java # 审计切面 +│ │ │ ├── config/ +│ │ │ │ ├── SecurityConfig.java +│ │ │ │ ├── RedisConfig.java +│ │ │ │ ├── MqttConfig.java +│ │ │ │ ├── ObjectStorageConfig.java +│ │ │ │ ├── SchedulerConfig.java +│ │ │ │ ├── OpenApiConfig.java +│ │ │ │ └── MyBatisPlusConfig.java +│ │ │ ├── statemachine/ +│ │ │ │ ├── StateMachine.java +│ │ │ │ ├── TransitionRule.java +│ │ │ │ ├── StateTransitionException.java +│ │ │ │ ├── ApplicationStateMachine.java +│ │ │ │ ├── PlanStateMachine.java +│ │ │ │ ├── WorkOrderStateMachine.java +│ │ │ │ └── SettlementStateMachine.java +│ │ │ └── module/ +│ │ │ ├── application/ +│ │ │ │ ├── controller/ApplicationController.java +│ │ │ │ ├── service/ApplicationService.java +│ │ │ │ ├── service/ApplicationValidationService.java +│ │ │ │ ├── repository/ServiceApplicationMapper.java +│ │ │ │ ├── entity/ServiceApplicationEntity.java +│ │ │ │ └── dto/{CreateRequest,SubmitRequest,Response,ListQuery}.java +│ │ │ ├── assessment/ +│ │ │ │ ├── controller/AssessmentController.java +│ │ │ │ ├── service/AssessmentService.java +│ │ │ │ ├── repository/{AssessmentTaskMapper,AssessmentReportMapper}.java +│ │ │ │ ├── entity/{AssessmentTaskEntity,AssessmentReportEntity}.java +│ │ │ │ └── dto/{...}.java +│ │ │ ├── plan/ +│ │ │ │ └── ... (同模式) +│ │ │ ├── schedule/ +│ │ │ │ ├── controller/ScheduleController.java +│ │ │ │ ├── service/ScheduleService.java +│ │ │ │ ├── service/DispatchService.java +│ │ │ │ ├── algorithm/DispatchAlgorithm.java +│ │ │ │ ├── algorithm/HardConstraintFilter.java +│ │ │ │ ├── algorithm/SoftScoringRanker.java +│ │ │ │ └── ... +│ │ │ ├── workorder/ +│ │ │ ├── execution/ +│ │ │ ├── exception/ +│ │ │ ├── supervision/ +│ │ │ ├── acceptance/ +│ │ │ ├── settlement/ +│ │ │ ├── archive/ +│ │ │ ├── notification/ +│ │ │ │ ├── service/NotificationService.java +│ │ │ │ ├── sender/NotificationSender.java +│ │ │ │ ├── sender/MqttSender.java +│ │ │ │ ├── sender/WechatSender.java +│ │ │ │ └── sender/SmsSender.java +│ │ │ ├── audit/ +│ │ │ ├── compliance/ +│ │ │ ├── masterdata/ +│ │ │ └── capacity/ +│ │ └── resources/ +│ │ ├── application.yml +│ │ ├── application-dev.yml +│ │ ├── application-test.yml +│ │ ├── application-prod.yml +│ │ └── db/migration/ +│ │ ├── V1__baseline.sql +│ │ ├── V2__seed_master_data.sql +│ │ └── V3__add_indexes.sql +│ └── test/java/com/meizhou/hss/ +│ ├── statemachine/ +│ │ ├── ApplicationStateMachineTest.java +│ │ ├── PlanStateMachineTest.java +│ │ ├── WorkOrderStateMachineTest.java +│ │ └── SettlementStateMachineTest.java +│ ├── module/ +│ │ ├── application/ApplicationControllerTest.java +│ │ ├── workorder/WorkOrderIntegrationTest.java +│ │ └── settlement/SettlementCalculationTest.java +│ └── algorithm/DispatchAlgorithmTest.java +└── delivery-miniapp/ + ├── pages/delivery/ + │ ├── login/ + │ ├── index/ # 工作台 + │ ├── orders/ # 工单列表 + │ ├── order-detail/ # 工单详情 + │ ├── accept/ # 接单确认 + │ ├── checkin/ # GPS签到 + │ ├── execute/ # 服务执行 + │ ├── exception/ # 异常上报 + │ ├── finish/ # 签退完成 + │ ├── offline-sync/ # 离线补传 + │ ├── messages/ # 通知消息 + │ └── profile/ # 我的资质 + └── ... +``` + +--- + +## 12. 实施优先级与分批计划（补齐版） + +### 12.1 第一批（MVP 可验收闭环）- 预计 4~6 周 + +第一批目标不是做全量美化和智能化，而是完成一条真实可验收的居家上门服务闭环： + +```text +申请 → 评估 → 方案 → 签署 → 服务计划 → 工单 → 派单 → delivery 接单 → 签到 → 项目执行 → 完成 → 验收 → 结算 → 归档 +``` + +必须包含： + +1. 项目初始化：`pom.xml`、`application.yml`、启动类、环境配置。 +2. 公共模块：`ApiResponse`、`BaseEntity`、统一异常、错误码、分页、租户上下文。 +3. 数据库基线：Flyway migration，包含 P0/P1 核心表。 +4. 状态机：申请、方案、工单、结算四层状态机。 +5. 状态动作编排：`ActionHandler`，完成状态流转 + 副作用写入。 +6. 幂等模块：`hss_idempotency_records` + `Idempotency-Key` 拦截器。 +7. Outbox 模块：写入、并发抢占、重试、死信、回执。 +8. 审计模块：状态流转、敏感数据访问、高风险操作审计。 +9. 申请域：创建、提交、受理通过、退回、取消。 +10. 评估域：派发、签到、提交报告、异议。 +11. 方案域：创建、编辑、提交签署、签署、拒签、版本管理。 +12. 计划域：方案生效后生成服务计划。 +13. 工单域：工单创建、派单、接单、拒单、改派。 +14. 执行域：GPS 签到、项目级执行记录、证据元数据、完成。 +15. 异常域：异常上报、异常处理动作、紧急事件基础流程。 +16. 验收域：验收确认、拒绝验收、评价。 +17. 结算域：结算单、结算明细、审核、支付确认、归档。 +18. 支付退款域：支付流水、重复回调幂等、退款/冲正基础表。 +19. 定时任务：Outbox 重试、派单超时扫描、方案待签提醒、验收超时扫描。 +20. delivery 最小闭环页面：登录、工作台、今日工单、详情、接单、签到、执行、异常、完成、证据上传、消息。 +21. OpenAPI 契约：覆盖 MVP 全部接口。 +22. E2E 测试：完成至少 1 条从申请到归档的完整链路。 + +### 12.2 第二批（增强能力）- 预计 3~4 周 + +1. 调度算法：硬约束过滤 + 软约束评分 + Top5 推荐解释。 +2. 监管域：抽查计划、违规记录、整改跟踪。 +3. 合规域：授权同意、敏感数据访问审计、脱敏策略完善。 +4. 主数据域：机构、人员、资质、服务项目、区域、价格、规则版本。 +5. 文件证据增强：断点/失败补传、文件 hash、签名 URL、下载审计。 +6. 定时任务增强：未来 1~7 天工单生成、次日排班预计算、批量结算。 +7. delivery 离线能力：本地缓存、失败补传、重复提交防护。 +8. 管理端调度台：改派、撤单、异常处理、超时预警。 +9. 权限矩阵落地：接口级权限、字段级脱敏、数据范围过滤。 +10. Testcontainers 集成测试：PostgreSQL、Redis、MQTT/Mock、对象存储。 + +### 12.3 第三批（智能化与运营）- 后续迭代 + +1. 运力域：服务网格、容量预测、网格容量看板。 +2. ETA 预测：到达时间、完成时间、风险缓冲。 +3. 调度优化：局部搜索、插入成本、OR-Tools 批量预排。 +4. 数据看板：质量分析、异常热力图、服务连续性、人员负载。 +5. 人员绩效结算：服务质量、完成率、投诉率、违规率、评分。 +6. 智能助手：delivery 端风险提醒、证据缺失提醒、异常处理建议。 + +--- + +## 13. 开始实现 Prompt（补齐版） + +### 13.1 第一阶段开工 Prompt + +```txt +你现在作为资深 Spring Boot 后端工程师，在全新仓库中实现“居家上门服务系统”的 MVP 第一批。 + +必须遵守： +1. 技术栈：Spring Boot 3.x + Java 17 + PostgreSQL + MyBatis-Plus/Spring Data JDBC + Flyway + Redis + MQTT + 对象存储。 +2. 架构：模块化单体，不拆微服务，但按 domain/module 分包。 +3. 表规范：所有业务表使用 hss_ 前缀，必须包含 tenant_id、org_id、status、created_by、updated_by、created_at、updated_at、deleted_at、version。 +4. 状态机：申请、方案、工单、结算四层状态机；前端只传 action，不传目标状态。 +5. 状态动作：状态机只判断合法性，ActionHandler 负责编排副作用，例如写业务表、状态流转、Outbox、审计。 +6. 幂等：所有写接口支持 Idempotency-Key，并落库 hss_idempotency_records。 +7. 通知：所有通知必须先写 hss_notification_outbox，异步发送；Outbox 必须支持并发锁、重试、dead-letter。 +8. 结算：结算金额由后端基于方案快照和执行记录计算，禁止使用前端传入金额作为最终金额。 +9. 文件：证据文件进入对象存储，数据库只保存元数据、hash、storage_key、访问审计。 +10. delivery 端：MVP 必须包含登录、今日工单、详情、接单、签到、执行、异常、完成、证据上传、消息。 +11. 测试：必须包含状态机单测、金额计算单测、幂等测试、Outbox 失败重试测试、支付重复回调测试、定时任务重复执行测试。 +12. 输出：Flyway DDL、Java 代码、OpenAPI 契约、状态机文档、数据字典、测试用例。 + +第一阶段只做 MVP 可验收闭环，不做复杂 ETA、OR-Tools、智能推荐、完整数据看板。 +先生成工程目录、pom.xml、application.yml、Flyway V1~V10 migration、BaseEntity、ApiResponse、错误码、幂等拦截器、状态机骨架、Outbox 骨架，然后再实现申请域、评估域、方案域、计划域、工单域、执行域、验收域、结算域。 +``` + +--- + + + +## 14. 生产可交付补强清单 + +### 14.1 P0 必须补齐项 + +| 编号 | 补齐项 | 必须完成的内容 | 不完成的风险 | +|---|---|---|---| +| P0-01 | 幂等落库 | 新增 `hss_idempotency_records`，所有写接口接入 | 重复提交、重复支付、重复生成工单 | +| P0-02 | 定时任务日志 | 新增 `hss_job_execution_logs` | 定时任务失败不可追溯、不可重跑 | +| P0-03 | Outbox 并发安全 | `locked_by`、`locked_until`、`next_retry_at`、`dead-letter` | 多实例重复发送、通知堆积 | +| P0-04 | delivery MVP | 登录、今日工单、详情、接单、签到、执行、异常、完成、证据上传 | 无法验证真实上门履约 | +| P0-05 | 方案签署事务 | 签署记录、方案生效、服务计划生成、状态流转、Outbox 同事务 | 方案已生效但没有计划 | +| P0-06 | 证据元数据 | `hss_evidence_files` 完整字段、对象存储、hash、签名访问 | 服务执行证据链不可信 | +| P0-07 | 支付幂等 | 支付流水号 + 结算单号幂等 | 重复支付回调导致账务错误 | +| P0-08 | 状态动作编排 | StateMachine + ActionHandler 双层结构 | service 逻辑膨胀，状态副作用失控 | + +### 14.2 P1 必须补齐项 + +| 编号 | 补齐项 | 必须完成的内容 | +|---|---|---| +| P1-01 | 异议闭环 | `hss_objections`，评估异议、方案异议、复核记录 | +| P1-02 | 异常动作 | `hss_exception_actions`，每一次处理动作留痕 | +| P1-03 | 监管整改 | `hss_spot_checks`、`hss_violations`、`hss_corrections` | +| P1-04 | 投诉反馈 | `hss_complaints`，与验收拒绝区分 | +| P1-05 | 支付退款 | `hss_payments`、`hss_refunds`、冲正记录 | +| P1-06 | 归档台账 | `hss_ledgers`、`hss_archive_files` | +| P1-07 | 主数据 | 服务项目、资质、区域、价格、机构、人员 | +| P1-08 | OpenAPI 完整契约 | 消费者端、管理端、delivery 端、定时任务管理接口 | + +--- + +## 15. 完整 DDL 补齐范围 + +### 15.1 必须进入 baseline 的核心表 + +第一版 Flyway 不建议只建少量表再频繁补核心表。MVP 可以不实现全部业务逻辑，但核心表结构应尽量一次性建立，避免后续状态和数据迁移困难。 + +| 数据域 | 表名 | +|---|---| +| 申请 | `hss_service_applications` | +| 画像 | `hss_patient_profiles` | +| 评估 | `hss_assessment_tasks`、`hss_assessment_reports` | +| 异议 | `hss_objections` | +| 方案 | `hss_service_plans`、`hss_service_plan_items`、`hss_plan_versions` | +| 计划 | `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_idempotency_records` | +| 任务 | `hss_job_execution_logs` | +| 审计 | `hss_state_transitions`、`hss_audit_logs`、`hss_data_access_logs` | +| 合规 | `hss_consent_records` | +| 主数据 | `hss_md_organizations`、`hss_md_staff`、`hss_md_staff_qualifications`、`hss_md_service_items`、`hss_md_price_rules`、`hss_md_regions` | +| 运力 | `hss_service_grids`、`hss_grid_capacity_daily`、`hss_staff_skill_capacity` | + +### 15.2 新增关键表字段建议 + +#### hss_idempotency_records + +```sql +CREATE TABLE hss_idempotency_records ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + idempotency_key VARCHAR(128) NOT NULL, + business_key VARCHAR(256) NOT NULL, + request_hash VARCHAR(128) NOT NULL, + response_code VARCHAR(64), + response_body TEXT, + status VARCHAR(32) NOT NULL, + locked_until TIMESTAMPTZ, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), + UNIQUE (tenant_id, idempotency_key, business_key) +); +``` + +#### hss_notification_outbox + +```sql +CREATE TABLE hss_notification_outbox ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + business_type VARCHAR(64) NOT NULL, + business_id BIGINT NOT NULL, + event_type VARCHAR(64) NOT NULL, + receiver_id BIGINT NOT NULL, + channel VARCHAR(32) NOT NULL, + payload JSONB NOT NULL, + status VARCHAR(32) NOT NULL, + retry_count INT NOT NULL DEFAULT 0, + max_retry_count INT NOT NULL DEFAULT 5, + next_retry_at TIMESTAMPTZ, + locked_by VARCHAR(128), + locked_until TIMESTAMPTZ, + sent_at TIMESTAMPTZ, + last_error TEXT, + dedupe_key VARCHAR(256) NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), + UNIQUE (tenant_id, dedupe_key) +); +``` + +#### hss_job_execution_logs + +```sql +CREATE TABLE hss_job_execution_logs ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + job_name VARCHAR(128) NOT NULL, + biz_date DATE NOT NULL, + shard_key VARCHAR(128) NOT NULL DEFAULT 'default', + status VARCHAR(32) NOT NULL, + started_at TIMESTAMPTZ NOT NULL, + finished_at TIMESTAMPTZ, + success_count INT NOT NULL DEFAULT 0, + failure_count INT NOT NULL DEFAULT 0, + error_message TEXT, + idempotency_key VARCHAR(256) NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), + UNIQUE (tenant_id, job_name, biz_date, shard_key) +); +``` + +--- + +## 16. 状态机与动作编排补齐设计 + +### 16.1 为什么不能只有 transition 方法 + +状态机不能只做： + +```text +from_status + action = to_status +``` + +因为每个动作都有副作用。例如“方案签署”必须同时完成： + +1. 校验方案版本。 +2. 校验签署人。 +3. 写签署记录。 +4. 冻结方案快照。 +5. 生成服务计划。 +6. 写状态流转。 +7. 写 Outbox。 +8. 写审计日志。 + +### 16.2 推荐双层结构 + +```text +StateMachine：判断动作是否合法 +ActionHandler：执行业务副作用 +``` + +目录建议： + +```text +statemachine/ + StateMachine.java + TransitionRule.java + TransitionContext.java + TransitionResult.java + ApplicationStateMachine.java + PlanStateMachine.java + WorkOrderStateMachine.java + SettlementStateMachine.java + +action/ + ApplicationSubmitHandler.java + ApplicationAcceptHandler.java + AssessmentSubmitHandler.java + PlanSubmitSignHandler.java + PlanSignHandler.java + WorkOrderAssignHandler.java + WorkOrderAcceptHandler.java + WorkOrderCheckInHandler.java + WorkOrderFinishHandler.java + WorkOrderExceptionHandler.java + AcceptanceConfirmHandler.java + SettlementApproveHandler.java + PaymentCallbackHandler.java +``` + +### 16.3 ActionHandler 标准流程 + +```text +1. 加载业务对象 +2. 校验租户、机构、角色、数据范围 +3. 校验 Idempotency-Key +4. 调用 StateMachine 校验动作合法性 +5. 执行业务副作用 +6. 更新业务状态 +7. 写 hss_state_transitions +8. 写 hss_audit_logs +9. 写 hss_notification_outbox +10. 提交事务 +11. 返回动作结果 +``` + +--- + +## 17. Outbox 并发安全与补偿机制 + +### 17.1 Outbox 发送状态 + +| 状态 | 含义 | +|---|---| +| CREATED | 已创建，待发送 | +| LOCKED | 已被某个实例抢占 | +| SENT | 已发送成功 | +| FAILED | 本次发送失败，等待重试 | +| DEAD | 超过最大重试次数，进入死信 | + +### 17.2 多实例抢占策略 + +PostgreSQL 推荐使用 `FOR UPDATE SKIP LOCKED`： + +```sql +SELECT * +FROM hss_notification_outbox +WHERE status IN ('CREATED', 'FAILED') + AND (next_retry_at IS NULL OR next_retry_at <= now()) +ORDER BY created_at +LIMIT 100 +FOR UPDATE SKIP LOCKED; +``` + +发送任务拿到记录后更新为 `LOCKED`，设置 `locked_by` 和 `locked_until`。发送成功后更新为 `SENT`，失败则增加 `retry_count` 并设置 `next_retry_at`。超过最大重试次数进入 `DEAD`。 + +### 17.3 失败补偿 + +1. `FAILED` 可自动重试。 +2. `DEAD` 必须进入运营或技术告警。 +3. 支持按业务 ID 手动重发。 +4. 支持按时间区间批量重发。 +5. 通知通道失败不能回滚业务主状态。 +6. 消费者端和 delivery 端必须能通过主动查询拿到真实业务状态。 + +--- + +## 18. delivery 端 MVP 最小闭环 + +### 18.1 MVP 页面范围 + +| 页面 | 是否 MVP 必须 | 说明 | +|---|---|---| +| 登录页 | 是 | 校验服务人员角色、机构、状态 | +| 工作台 | 是 | 今日任务、待接单、待签到、服务中、异常 | +| 今日工单 | 是 | 查询本人任务 | +| 工单详情 | 是 | 地址、对象脱敏信息、服务项目、风险提示 | +| 接单/拒单 | 是 | 触发工单状态机 | +| 签到 | 是 | GPS、拍照、对象确认 | +| 执行 | 是 | 项目级执行记录 | +| 异常 | 是 | 对象不在家、拒绝服务、身体异常、地址错误等 | +| 完成 | 是 | 提交服务总结、证据校验 | +| 证据上传 | 是 | 文件上传、hash、元数据 | +| 消息页 | 是 | 派单、改派、异常处理、验收反馈 | +| 离线补传 | 第二批 | MVP 可先做失败重试，不做完整离线队列 | +| 智能助手 | 第三批 | 风险提醒、路径建议、语音输入 | + +### 18.2 delivery 聚合接口 + +```text +GET /api/hss/delivery/workbench +GET /api/hss/delivery/work-orders/today +GET /api/hss/delivery/work-orders/{id}/detail +POST /api/hss/delivery/work-orders/{id}/accept +POST /api/hss/delivery/work-orders/{id}/reject +POST /api/hss/delivery/work-orders/{id}/check-in +POST /api/hss/delivery/work-orders/{id}/start-service +POST /api/hss/delivery/work-orders/{id}/execution-records +POST /api/hss/delivery/work-orders/{id}/finish +POST /api/hss/delivery/work-orders/{id}/exception +POST /api/hss/delivery/evidence/upload +GET /api/hss/delivery/messages +POST /api/hss/delivery/messages/{id}/read +``` + +--- + +## 19. 完整 OpenAPI 接口补齐范围 + +### 19.1 消费者端接口 + +```text +POST /api/hss/applications +POST /api/hss/applications/{id}/submit +POST /api/hss/applications/{id}/cancel +GET /api/hss/applications/{id} +GET /api/hss/service-plans/{id}/for-sign +POST /api/hss/service-plans/{id}/sign +POST /api/hss/service-plans/{id}/reject +GET /api/hss/work-orders/{id}/acceptance +POST /api/hss/work-orders/{id}/acceptance/confirm +POST /api/hss/work-orders/{id}/acceptance/reject +POST /api/hss/work-orders/{id}/rating +GET /api/hss/settlements/{id} +POST /api/hss/settlements/{id}/pay +``` + +### 19.2 管理端接口 + +```text +GET /api/hss/admin/applications +POST /api/hss/admin/applications/{id}/accept +POST /api/hss/admin/applications/{id}/return +POST /api/hss/admin/assessment-tasks/{id}/assign +POST /api/hss/admin/service-plans +PUT /api/hss/admin/service-plans/{id} +POST /api/hss/admin/service-plans/{id}/submit-sign +POST /api/hss/admin/service-plans/{id}/generate-schedule +POST /api/hss/admin/work-orders/{id}/assign +POST /api/hss/admin/work-orders/{id}/reassign +POST /api/hss/admin/work-orders/{id}/cancel +POST /api/hss/admin/exceptions/{id}/handle +POST /api/hss/admin/settlements/generate +POST /api/hss/admin/settlements/{id}/approve +POST /api/hss/admin/settlements/{id}/reject +GET /api/hss/admin/audit-logs +``` + +### 19.3 文件与证据接口 + +```text +POST /api/hss/files/presign-upload +POST /api/hss/files/commit +GET /api/hss/files/{id}/signed-url +GET /api/hss/evidence-files/by-work-order/{workOrderId} +``` + +### 19.4 主数据接口 + +```text +GET /api/hss/master/service-items +GET /api/hss/master/price-rules +GET /api/hss/master/regions +GET /api/hss/master/staff +GET /api/hss/master/staff/{id}/qualifications +``` + +--- + +## 20. 定时任务补齐设计 + +### 20.1 必须实现的 MVP 任务 + +| 任务 | 频率 | MVP 是否必须 | +|---|---|---| +| Outbox 重试 | 每 1 分钟 | 是 | +| 派单超时扫描 | 每 5 分钟 | 是 | +| 方案待签提醒 | 每 30 分钟 | 是 | +| 服务开始前提醒 | 每 10 分钟 | 是 | +| 验收超时扫描 | 每小时 | 是 | +| 未来工单生成 | 每晚 00:30 | 第二批也可，但表和接口先预留 | +| 次日排班预计算 | 每晚 01:00 | 第二批 | +| 批量结算生成 | 每日/每月 | 第二批 | +| 审计日志归档 | 每月 | 第二批 | + +### 20.2 任务执行规则 + +1. 所有任务写 `hss_job_execution_logs`。 +2. 所有任务按 `job_name + biz_date + shard_key` 幂等。 +3. 所有任务支持 dry-run。 +4. 所有任务支持手动重跑。 +5. 所有任务不得绕过状态机直接改状态。 +6. 多实例部署必须使用分布式锁或数据库唯一键防重复。 + +--- + +## 21. 测试与验收补齐 + +### 21.1 新增必测用例 + +| 类型 | 用例 | +|---|---| +| 幂等 | 同一 Idempotency-Key 重复提交返回同一结果 | +| 幂等冲突 | 同一 Idempotency-Key 不同 body 返回冲突 | +| 并发派单 | 两个调度员同时派同一工单，只能成功一次 | +| 并发接单 | 服务人员重复点击接单，只生成一次接单记录 | +| 并发完成 | 重复完成提交不生成重复执行记录 | +| Outbox 失败 | MQTT 失败后 Outbox 进入 FAILED 并可重试 | +| Outbox 死信 | 超过最大次数进入 DEAD | +| 支付回调 | 同一支付流水重复回调只入账一次 | +| 事务回滚 | 服务计划生成失败时方案签署整体回滚 | +| 文件补传 | 文件上传成功但业务提交失败，可重新绑定 | +| 权限 | 服务人员不能查看非本人工单 | +| 脱敏 | 非授权角色看不到完整手机号、地址、健康信息 | +| 任务重跑 | 同一天重复生成工单不产生重复数据 | +| 弱网 | delivery 端重复点击、网络失败、恢复补传 | + +### 21.2 MVP 验收门槛 + +1. 状态机核心分支单测覆盖率 ≥ 90%。 +2. 结算金额计算单测覆盖率 ≥ 90%。 +3. 所有写接口必须有幂等测试。 +4. 所有状态动作必须有非法状态测试。 +5. delivery 端完成 5 条 E2E：接单、签到、执行、异常、完成。 +6. Outbox 完成失败重试和死信测试。 +7. 支付回调完成重复回调测试。 +8. 定时任务完成重复执行测试。 +9. 权限和脱敏至少覆盖服务人员、调度员、结算员、监管员四类角色。 +10. OpenAPI 与实际接口保持一致。 + +--- + +## 22. 灰度发布与回滚补齐 + +### 22.1 发布策略 + +| 能力 | 发布方式 | +|---|---| +| 状态机 | 测试环境全量验证后上线，不做灰度状态 | +| 调度算法 | shadow 模式 → 人工确认 → 小范围自动 | +| 自动验收 | 默认关闭，试点机构开启 | +| 批量结算 | dry-run → 人工审核 → 自动生成 | +| delivery 新页面 | 按机构/角色灰度 | +| 定时任务 | 小范围 biz_date dry-run 后开启 | +| Outbox | 先发送测试通道，再切真实通道 | + +### 22.2 回滚原则 + +1. 数据库以 roll-forward 为主，不依赖直接 down migration。 +2. 已上线的 migration 不修改，新增 migration 修正。 +3. 删除字段必须两阶段：先停用，后删除。 +4. 新状态上线前必须确认旧代码能兼容或不会读取。 +5. 功能必须有 feature flag。 +6. 回滚后不能产生孤儿状态。 +7. 任务必须可暂停、可恢复、可重跑。 + +--- + +## 23. 最终开工检查清单 + +开始实现前，必须确认以下事项： + +| 检查项 | 是否必须 | +|---|---| +| 已确认 Spring Boot / Java 17 / PostgreSQL / Redis / MQTT / 对象存储 | 是 | +| 已确认 hss_ 表前缀、统一审计字段、软删除、乐观锁 | 是 | +| 已确认方案、计划、工单分离 | 是 | +| 已确认工单项目级执行记录 | 是 | +| 已确认所有写接口 Idempotency-Key | 是 | +| 已确认新增 `hss_idempotency_records` | 是 | +| 已确认新增 `hss_job_execution_logs` | 是 | +| 已确认 Outbox 支持锁、重试、死信 | 是 | +| 已确认 delivery MVP 进入第一批 | 是 | +| 已确认支付、退款独立表 | 是 | +| 已确认异常、监管、投诉独立闭环 | 是 | +| 已确认 OpenAPI 全契约先行 | 是 | +| 已确认 Testcontainers/真实依赖集成测试 | 是 | +| 已确认灰度开关和 roll-forward 回滚策略 | 是 | + +--- + +## 24. 最终结论 + +这份补齐版已经可以作为正式开工文档使用。实现时不要再扩大需求范围，第一阶段只围绕“真实可验收闭环”推进： + +```text +后端状态机可信 +数据库链路完整 +通知可靠可补偿 +delivery 可真实履约 +结算可追溯 +异常可兜底 +权限与审计可验收 +测试能证明系统可靠 +``` + +第一阶段完成后，系统应能真实跑通： + +```text +家属提交申请 +→ 受理员受理 +→ 评估员评估 +→ 管理端生成方案 +→ 家属签署方案 +→ 系统生成服务计划和工单 +→ 调度员派单 +→ delivery 服务人员接单 +→ GPS 签到 +→ 项目级执行 +→ 上传证据 +→ 完成服务 +→ 家属验收 +→ 系统生成结算 +→ 支付确认 +→ 归档 +``` + +只要严格按本补齐版执行，就可以开始实现。