docs: 服务机构端 C1 待遇档案设计文档

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/specs/2026-10-14-服务机构端-C1待遇档案-design.md

@@ -0,0 +1,129 @@
+# 服务机构端 · C1 待遇档案 · 设计文档
+
+> 日期：2026-10-14
+> 范围：待遇档案域——老人档案（elder）+ 十态待遇状态机 + 状态变更留痕（elder_status_log）+ 评估结论副本上传。
+> 依据：P0 PRD §3.2/§5.2/§5.5.1/§7.2/§7.4/§8.2；C0 设计 `2026-10-14-服务机构端-C0基础骨架-design.md`。
+> 后续：C2 派单工单（含 `elder_svc` 老人个人项目库 + 服务计划）。
+
+## 1. 背景与目标
+
+在 C0 基础骨架（机构=租户、RBAC、目录四层、菜单、多租户过滤）之上，落地「待遇档案」域。C1 只做：老人档案建档、十态待遇状态机与变更留痕、评估结论副本上传。承接 C2 的状态机消费（L1 硬锁）与 `elder_svc`。
+
+## 2. 已定决策（用户 2026-10-14 拍板）
+
+- 评估结论承载＝**上传副本 + 存字段**（等级唯一来源=评估结论，禁止建档人自行填写）。
+- OCR 后置（C1 手工录入身份证 + 18 位校验位校验）。
+- 批量导入后置（C1 先单条建档）。
+- `elder_svc` 放 C2（与「制定计划时带入」一起做）。
+- 文件存 MinIO（`http://localhost:9000`，bucket `carelink`，S3 兼容，后续切腾讯云 COS 只换配置）。
+
+## 3. 数据模型（新增 2 张表）
+
+通用字段：`created_at`/`created_by`/`updated_at`/`deleted_at`。主键 UUID v7。
+
+**`elder` 老人档案表**（`@@map("sys_elder")`）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | uuid | 主键 |
+| tenant_code | varchar(64) | 机构（多租户隔离） |
+| loc_code | varchar(12) | 参保地/统筹区（取目录依据） |
+| prev_loc_code | varchar(12)? | 跨统筹区转移前参保地 |
+| transfer_confirm_at | datetime? | 转移确认时间 |
+| name | varchar(30) | 姓名 |
+| gender | char(1) | M/F |
+| birth_date | date | 出生日期（系统算年龄） |
+| id_card_no | varchar(255) | 身份证号（加密预留；本期明文+TODO，掩码见 §7） |
+| phone | varchar(15)? | 联系电话 |
+| address | varchar(200) | 居住地址 |
+| guardian_name | varchar(30)? | 紧急联系人 |
+| guardian_phone | varchar(15)? | 紧急联系人电话 |
+| insur_no | varchar(30) | 医保参保号 |
+| insur_type | varchar(10) | employee/resident |
+| insur_years | int? | 缴费年限 |
+| insur_verify_status | varchar(20)? | verified/unverified（本期线下确认） |
+| insur_verify_date | date? | 参保核验日期 |
+| assess_level | varchar(20) | 失能等级 sev_1(重度一级·最高级)/sev_2/sev_3 |
+| care_level | varchar(20) | 护理等级 care_1(一级·最高级)/care_2/care_3 |
+| assess_date | date | 评估结论日期 |
+| assess_org | varchar(100)? | 评估机构名称 |
+| assess_evidence_file | varchar(255)? | 评估结论副本（MinIO key）【补】 |
+| benefit_start | date | 待遇有效期起 |
+| benefit_end | date | 待遇有效期止 |
+| treat_status | varchar(20) | 待遇状态（§4） |
+| status_source | varchar(10) | manual（恒）/api 预留 |
+| status_change_date | date? | 状态最后变更日 |
+| hosp_start / hosp_end | date? | 住院起止 |
+| photo_tier_override | json? | 拍照分档加严覆盖 |
+| need_assess | json? | 上门需求评估五块信息（建表留结构，采集交互后置 C2） |
+| note | text? | 备注（含「注意事项」区块） |
+| biz_line | varchar(20) | 恒 ltci |
+
+索引：`tenant_code`、`tenant_code+id_card_no`（唯一，身份证防重）。
+
+**`elder_status_log` 待遇状态变更日志**（`@@map("sys_elder_status_log")`）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | uuid | 主键 |
+| elder_id | varchar(36) | 老人 |
+| from_status / to_status | varchar(20) | 变更前后 |
+| change_reason | varchar(200) | 变更原因（必填） |
+| source | varchar(10) | manual |
+| operator_id | varchar(36) | 操作人 |
+| evidence_file | varchar(255)? | 佐证材料 |
+| changed_at | datetime | 变更时间 |
+
+## 4. 十态待遇状态机
+
+`treat_status` 十态与语义（可否派单/计费/恢复，PRD §7.4）：
+
+| 状态 | 值 | 可否派单 | 可否计费 | 恢复 |
+|---|---|:---:|:---:|---|
+| 待建档 | pending_file | ❌ | ❌ | 建档完成→active |
+| 待起付(等待期/垫付期) | waiting_period | ✅(垫付台账) | ❌ | 待遇生效→结转 active |
+| 正常享受 | active | ✅ | ✅ | — |
+| 住院暂停 | hosp_pause | ❌ | ❌ | 出院人工确认→active |
+| 复评等待期 | review_waiting | ❌ | ❌ | 复评结论出 |
+| 跨统筹区转移中 | transferring | ❌ | ❌ | 新参保地确认 |
+| 死亡 | dead | ❌ | ❌ | 不可恢复 |
+| 长期异地居住 | long_away | ❌ | ❌ | 回迁确认 |
+| 待遇到期 | benefit_expired | ❌ | ❌ | 续评通过 |
+| 已终止 | terminated | ❌ | ❌ | 不可恢复 |
+
+- 变更接口 `/elder/status/change`：`to_status` + `change_reason`(必填) + 可选 `evidence_file`；写 `elder_status_log` + 审计。
+- 建档初始状态：待遇有效期覆盖今天 → `active`；否则 → `waiting_period`。
+- L1 硬锁（无有效待遇不可服务）在 C2 派单时消费；C1 只实现状态机数据层与变更语义。
+
+## 5. 接口（A 组 + 上传）
+
+| 接口 | 方法 | 权限 | 说明 |
+|---|---|---|---|
+| `/elder/list` | GET | elder:list | 状态/等级/姓名筛选；身份证服务端掩码 |
+| `/elder/create` | POST | elder:create | 建档；18 位校验、防重、等级来自评估结论 |
+| `/elder/detail` | GET | elder:detail | 详情；admin/qc 可看身份证明文+留痕 |
+| `/elder/status/change` | POST | elder:status-change | 变更状态，change_reason 必填 |
+| `/elder/status/log` | GET | elder:detail | 状态变更历史 |
+| `/elder/assess-evidence/upload` | POST | elder:create | 上传评估结论副本到 MinIO，返回 file key |
+
+统一响应沿用 `{code,message,data,hint}`（hint 为硬锁提示，本期多数接口不触发）。
+
+## 6. 前端
+
+- 服务对象列表页（`ltc/elder`）：状态筛选（全部/正常享受/住院暂停/待建档/待遇到期）、列表（姓名/护理等级带「（最高级）」/状态/计划/下次服务/操作）。
+- 建档表单：必填校验（身份证 18 位+校验位、出生日期自动带出、参保地默认取机构属地、待遇止>起）、身份证防重提示、参保核验（线下确认字段）、**等级区块＝上传评估结论副本（必做，禁止手填等级）**。
+- 档案详情：完整信息 + 状态变更（下拉十态 + 原因必填）+ 状态日志时间线 + 身份证明文查看（admin/qc，留痕）。
+
+## 7. 横切
+
+- **身份证防重**：同机构 `id_card_no` 唯一；命中已有档案提示「已有档案，是否查看」。
+- **掩码在服务端**：列表返回 `5301**********1234`；前端不做掩码。
+- **明文查看留痕**：`/elder/detail` 请求明文身份证时落审计（谁/何时/看了谁的）。
+- **等级唯一来源**：`/elder/create` 不接受前端传 `assess_level/care_level`；等级由「上传评估结论副本」后由机构/质控录入（走 `assess_*` 字段），或由后续官方接口带出。禁止建档表单直接填等级。
+- **id_card_no 存储层加密后置**：C1 存明文 + TODO（与 staff 一起走统一 security change）；掩码 + 明文查看留痕 C1 做。
+- **审计**：建档、改状态、明文查看身份证落审计（复用脚手架 audit-log）。
+- **MinIO 配置**：`.env` 新增 `MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY/MINIO_BUCKET`（默认 carelink），S3 兼容，后续切 COS 只换配置。
+
+## 8. 非目标（本期不做）
+
+OCR 回填、Excel 批量导入、`elder_svc`、评估结论打水印、`id_card_no` 存储层加密、官方接口拉取评估结论（B 路径）、`need_assess` 采集交互。