# 服务机构端 · 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` 采集交互。