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