# 投云长护险管理系统 · 数据字典与接口契约

**第 4 步 · 交付物（V1 · 待确认）**

> **本文档是什么**：把第 3 步四份 PRD 里"用中文描述的对象、字段、状态"，落成**开发能直接照着建库、照着写接口的技术契约**。这是 PRD 与代码之间的那一层——**PRD 说"要什么"，本文档说"怎么存、怎么传"**。
> **前置文档**：第 1 步产品大纲（已确认）→ 第 2 步总体方案与信息架构（V2 锁定 P0）→ 第 3 步四份 PRD（PRD-00 全局规范 / 01 护理员 APP / 02 机构后台 / 03 家属端）→ **本文档**。
> **本期范围（写死）**：**P0 四块**（①待遇档案／②派单工单／③履约留痕／④质控闸门）。二期三块（⑤结算对账／⑥资质人员／⑦院长看板）**只落结构，不落功能**。
> **恒定总纲**：**既满足长护险政策要求，又让机构用得方便、不复杂。**
> **编制**：滇小构｜2026-10-11

---

## 〇、读法说明（先看这三条，否则容易误用）

1. **本文档的字段一律用英文键名**（`snake_case`），中文名只在"说明"列。
   - **理由**：字段名要在数据库、接口、代码里统一；中文只在界面文案层出现。**界面文案与字段名解耦**，改名不改库。
2. **每个字段标注【本期】/【预留】/【系统】三种标记**：
   - **【本期】**＝本期必须落库、必须进界面；
   - **【预留】**＝本期只建字段、界面不出现（对应 PRD-00 §8 的 R1–R6）；
   - **【系统】**＝系统自动生成，人不填（如 ID、时间戳、MD5）。
3. **本文档不含**：接口的**具体传输协议**（HTTP/HTTPS 皆可）、服务器部署、加密算法选型——这些属于技术方案，不属产品文档。

---

## 一、术语与技术口径对齐（防开发歧义）

| PRD 里的中文 | 技术口径 | 说明 |
|---|---|---|
| 老人档案 | `elder` 表 | 主键 `elder_id` |
| 服务计划 | `plan` / `plan_item` 两张表 | 计划头 ＋ 计划项目明细 |
| 工单 | `order` 表 | 一次服务＝一条工单 |
| 服务留痕 | `record` 表（主记录）＋ `record_photo`（照片）＋ `record_abnormal`（异常） | 一对多 |
| 质控记录 | `qc` 表 | 一条留痕对应一条质控（可多次退回补正，留历史） |
| 服务项目 | `svc_national`（L1）／`svc_local`（L2）／`svc_mapping`（L3）／`svc_org`（L4） | **四层四表，对应 PRD-00 §2.2** |
| 人员与资质 | `staff` 表 | 【预留】R2 |
| 上报 | `report` 表 | 【预留】R4 |
| 结算 | `settlement` 表 | 【预留】R1 |

> **⚠️ 命名纪律**：**不得使用 `checkin`／`clockin`／`punch` 作为留痕表名**——术语表明确"打卡记录"是禁用说法，留痕＝`record`。**这是合规口径在代码层的落地**（对应"不做打卡工具"的产品定性）。

---

## 二、数据库表总览

### 2.1 本期建表清单（12 张）

| # | 表名 | 中文 | 对应对象 | 本期用途 |
|:---:|---|---|---|---|
| 1 | `org` | 机构 | — | 机构信息、属地、账号根 |
| 2 | `user` | 账号 | — | 登录账号（后台三端角色） |
| 3 | `staff` | 人员 | ⑥〔预留〕 | 护理员/医护基础信息＋**资质字段预留** |
| 4 | `elder` | 老人档案 | ① | 待遇状态、等级、参保地（**含 `biz_line` 多业务线预留 R8**） |
| 5 | `elder_status_log` | 待遇状态变更日志 | ① | **状态变更留痕（不可无痕修改）** |
| 6 | `plan` | 服务计划（头） | ② | 周期、等级、护理方式、确认信息 |
| 7 | `plan_item` | 服务计划（项） | ② | 计划内含哪些服务项目、频次、时长 |
| 8 | `svc_national` | 国家基准库 | L1 | 国家 36 项＋官方代码（**17 字符，字段 varchar(20) 留余量**） |
| 9 | `svc_local` | 属地目录库 | L2 | 昆明 45 项；州市引用 L1 |
| 10 | `svc_mapping` | 属地↔国家映射 | L3 | **机构不可见** |
| 11 | `svc_org` | 机构项目库 | L4 | 机构勾选＋配价 |
| 12 | `order` | 工单 | ③ | 一次服务任务（**含 `biz_line` 多业务线预留 R8**） |

### 2.2 本期建表清单（续，6 张）

| # | 表名 | 中文 | 对应对象 | 本期用途 |
|:---:|---|---|---|---|
| 13 | `record` | 服务留痕（主） | ③ | 签到签退、时长、语音、状态 |
| 14 | `record_item` | 留痕项目明细 | ③ | 每个项目的"做了/没做/免拍" |
| 15 | `record_photo` | 留痕照片 | ③ | 照片存储引用 |
| 16 | `record_abnormal` | 异常上报 | ③ | 9 宫格分类＋语音＋照片 |
| 17 | `qc` | 质控记录 | ④ | 放行/退回、异常处理 |
| 18 | `report` | 上报池 | R4〔预留〕 | 建表，本期不写业务数据 |
| 19 | `settlement` | 结算 | R1〔预留〕 | 建表，本期不写业务数据 |

> **另有 3 张"字典/配置表"**：`dict_abnormal_type`（异常分类 9 宫格）／`dict_photo_tier`（拍照分档）／`loc_config`（统筹区配置，含目录来源）。合计 **22 张**。

---

## 三、核心表字段定义

> **通用字段**（每张表都有，下文不再重复）：`created_at`（创建时间）／`created_by`（创建人）／`updated_at`（更新时间）／`updated_by`（更新人）／`is_deleted`（软删除标志，**本期一律软删除，不物理删**）。

### 3.1 `org` 机构表

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `org_id` | varchar(32) | ✅ | 机构 ID（主键） | 【系统】 |
| `org_name` | varchar(100) | ✅ | 机构全称（**须与备案名称一致**） | 【本期】 |
| `org_type` | varchar(20) | ✅ | 机构类型：`medical_care`（医养结合）／`nursing_home`（养老机构）／`home_care`（居家上门）／`home_individual`（居家个体） | 【本期】 |
| `credit_code` | varchar(18) | ✅ | 统一社会信用代码 | 【本期】 |
| `loc_code` | varchar(12) | ✅ | **参保地／统筹区代码**（决定加载哪套目录） | 【本期】 |
| `loc_name` | varchar(50) | ✅ | 统筹区名称（冗余，便于展示） | 【本期】 |
| `svc_source` | varchar(10) | ✅ | 本机构目录来源：`national`（引用国家36）／`local`（昆明本地45） | 【本期】 |
| `license_no` | varchar(50) | ○ | 定点服务机构编号 | 【本期】 |
| `address` | varchar(200) | ✅ | 机构地址 | 【本期】 |
| `contact_name` / `contact_phone` | varchar | ✅ | 联系人／电话 | 【本期】 |
| `bed_count` | int | ○ | **床位备案数**（机构护理类必填） | 【本期】 |
| `sign_date` | date | ○ | 定点服务协议签订日（建档倒计时基准） | 【本期】 |

### 3.2 `user` 账号表

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `user_id` | varchar(32) | ✅ | 账号 ID | 【系统】 |
| `org_id` | varchar(32) | ✅ | 所属机构 | 【本期】 |
| `login_name` | varchar(50) | ✅ | 登录名（手机号） | 【本期】 |
| `real_name` | varchar(30) | ✅ | 真实姓名 | 【本期】 |
| `role` | varchar(50) | ✅ | **角色（可多值，逗号分隔）**：`nurse`（护理员）／`leader`（组长）／`qc`（质控员）／`admin`（机构管理员）／`director`（院长）；如 `director,admin`、`leader,qc` | 【本期】 |
| `staff_id` | varchar(32) | ○ | 关联 `staff` 表（护理员角色必填） | 【本期】 |
| `status` | varchar(10) | ✅ | `active`／`disabled` | 【本期】 |

> **⚠️ 权限落地纪律**：**角色不写在界面里做开关，写在后端权限校验**。**判权＝角色并集**（一人可兼多角色，见 PRD-00 §6.4 补充 2）。**"院长不改数据"修正为"仅当账号只持 `director` 时，写接口返回 403"**——若同时持 `qc`／`admin`（院长兼质控/兼管理员是常态），**按并集放行**。
> **⚠️ 唯一例外**：**禁止"自审自放行"**——同一账号录入的记录不得由自己质控放行（校验 `record.created_by ≠ qc.operator_id`），否则返回 `4001`。

### 3.3 `staff` 人员表（含 R2 预留）

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `staff_id` | varchar(32) | ✅ | 人员 ID | 【系统】 |
| `org_id` | varchar(32) | ✅ | 所属机构 | 【本期】 |
| `name` | varchar(30) | ✅ | 姓名 | 【本期】 |
| `id_card_no` | varchar(18) | ✅ | 身份证号（**实名制**，加密存储） | 【本期】 |
| `person_code` | varchar(20) | ○ | **医保人员编码**（按国家编码规范：`LN`+6位区划+6位顺序＝14 位；**字段留余量 varchar(20)**） | 【预留】R4 |
| `phone` | varchar(15) | ✅ | 手机号（APP 登录用） | 【本期】 |
| `job_type` | varchar(20) | ✅ | `nurse`（护理员）／`nurse_medical`（医护）／`manager` | 【本期】 |
| `work_type` | varchar(10) | ✅ | `fulltime`／`parttime` | 【本期】 |
| `entry_date` / `leave_date` | date | ○ | 入职／离职日（**离职自动移出可派列表**） | 【本期】 |
| `employ_status` | varchar(10) | ✅ | `on_job`／`leave`（离职）／`transfer` | 【本期】 |
| `cert_type` | varchar(30) | ○ | 证书类型（长期照护师/养老护理员/护士执业证/医师执业证） | **【预留】R2** |
| `cert_no` | varchar(50) | ○ | 证书编号 | **【预留】R2** |
| `cert_level` | varchar(20) | ○ | 等级（五级/四级/三级） | **【预留】R2** |
| `cert_expire` | date | ○ | 有效期至 | **【预留】R2** |
| `cert_status` | varchar(20) | ○ | `valid`／`expiring`／`expired`／`none`（本期人工填） | **【预留】R2** |
| `cert_verify_url` | varchar(200) | ○ | 联网查验结果留痕（如 osta.org.cn 截图路径） | **【预留】R2** |
| **`group_leader_id`** | varchar(32) | ○ | **归属组长**（＝该护理员所在"组"的组长 `staff_id`；**本组界定的唯一依据**，见 PRD-00 §6.4 补充 4）。**可为空＝机构未分组**，由 `admin` 在人员管理指定 | 【本期】 |

> **⚠️ 本期数据不空转纪律**（PRD-00 §8.1 第 2 条）：**`cert_*` 五字段本期就要人工录入**——签约机构手上都有证书信息，**先录进去，二期直接可用**，不浪费这一期的录入工作。
> **⚠️ 界面纪律**：本期 `cert_*` 字段**只在"人员管理（精简版）"里可填可看**，**不做到期提醒、不做禁派拦截**（那是二期）。

### 3.4 `elder` 老人档案表（① 待遇档案）

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `elder_id` | varchar(32) | ✅ | 老人 ID | 【系统】 |
| `org_id` | varchar(32) | ✅ | 所属机构 | 【本期】 |
| **`loc_code`** | varchar(12) | ✅ | **参保地／统筹区**（→ 数据铁律 3，全链路取目录依据） | 【本期】 |
| `name` | varchar(30) | ✅ | 姓名 | 【本期】 |
| `gender` | char(1) | ✅ | `M`／`F` | 【本期】 |
| `birth_date` | date | ✅ | 出生日期（系统算年龄） | 【本期】 |
| `id_card_no` | varchar(18) | ✅ | 身份证号（加密） | 【本期】 |
| `phone` | varchar(15) | ○ | 联系电话 | 【本期】 |
| `address` | varchar(200) | ✅ | 居住地址（服务上门用） | 【本期】 |
| `guardian_name` / `guardian_phone` | varchar | ○ | 紧急联系人 | 【本期】 |
| `insur_no` | varchar(30) | ✅ | **医保参保号** | 【本期】 |
| `insur_type` | varchar(10) | ✅ | `employee`（职工）／`resident`（居民） | 【本期】 |
| `biz_line` | varchar(20) | ✅ | **业务线**：`ltci`（长护险）／`self_pay`（自费）／`residence`（居养）／`civil_subsidy`（民政补贴）——**本期恒 `ltci`，多业务线二期扩展** | **【预留】R8** |
| `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) | ○ | 评估机构名称 | 【本期】 |
| `benefit_start` / `benefit_end` | date | ✅ | **待遇有效期起止** | 【本期】 |
| `treat_status` | varchar(20) | ✅ | **待遇状态**（见 §3.5 状态机） | 【本期】 |
| `status_source` | varchar(10) | ✅ | 状态来源：`manual`（人工）／`api`（接口）——**本期恒 `manual`** | **【预留】R5** |
| `status_change_date` | date | ○ | 状态最后变更日 | 【本期】 |
| `hosp_start` / `hosp_end` | date | ○ | **住院起止日**（`treat_status = 住院暂停` 时必填） | 【本期】 |
| `photo_tier_override` | json | ○ | 机构对本老人拍照分档的**加严覆盖**（**只能加严，不能放宽**） | 【本期】 |
| `note` | text | ○ | 备注（**含"注意事项"区块内容**，如吞咽障碍提示） | 【本期】 |

> **⚠️ 等级显示纪律**：`assess_level`／`care_level` 在界面上**必须带"最高级"字样**——`sev_1` 显示为"**重度失能一级（最高级）**"，`care_1` 显示为"**一级护理（最高级）**"。**这是 PRD-00 §2.5 写死的，不允许前端省略。**
> **⚠️ 认知衰退边界**：`assess_level` 只反映**日常活动 6 项**自评＋正式评估结论；**认知/感知觉 7 项须上门评估，系统不筛**。此口径须出现在任何展示等级的页面注脚。

### 3.5 `elder_status_log` 待遇状态变更日志（数据铁律 2 落地）

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `log_id` | varchar(32) | ✅ | 主键 |
| `elder_id` | varchar(32) | ✅ | 老人 ID |
| `from_status` / `to_status` | varchar(20) | ✅ | 变更前后状态 |
| `change_reason` | varchar(200) | ✅ | **变更原因（必填，不允许空）** |
| `source` | varchar(10) | ✅ | `manual`／`api` |
| `operator_id` | varchar(32) | ✅ | 操作人 |
| `evidence_file` | varchar(200) | ○ | 佐证材料（如出院小结照片路径） |
| `changed_at` | datetime | ✅ | 变更时间 |

> **⚠️ 关键设计**：**待遇状态的每一次变更都必须写一条日志，且 `change_reason` 强制必填**。
> **理由**：`treat_status` 直接决定"能不能服务、能不能计费"。**如果不留痕，"住院期间照做"这类问题将无法追溯**——而官渡区公示的高频事由正是"账账不符、记录不详"。**这条日志是机构自己的护身符。**

### 3.6 `plan` 服务计划表（② 服务计划）

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `plan_id` | varchar(32) | ✅ | 计划 ID | 【系统】 |
| `elder_id` | varchar(32) | ✅ | 老人 ID | 【本期】 |
| `org_id` | varchar(32) | ✅ | 机构 ID | 【本期】 |
| `plan_period_start` / `plan_period_end` | date | ✅ | **计划周期**（月度/周期） | 【本期】 |
| `care_level` | varchar(20) | ✅ | 计划对应的护理等级（**改等级须重新制定计划**） | 【本期】 |
| `care_mode` | varchar(20) | ✅ | 护理方式：`inst_medical`／`inst_nursing`／`home_org`／`home_individual` | 【本期】 |
| `item_count` | int | ✅ | **计划项目数**（系统按属地规则校验） | 【本期】 |
| `item_count_rule` | varchar(100) | ○ | 校验依据快照（如"昆明·医养结合·一级护理 ≥18 项"） | 【本期】 |
| `extra_item_count` | int | ○ | 附加项数（**≤5**） | 【本期】 |
| `week_freq` / `month_hours` | int | ○ | 居家类的**每周次数／每月小时数**（昆明居家必填） | 【本期】 |
| `plan_status` | varchar(20) | ✅ | `draft`（草稿）／`active`（执行中）／`changed`（已变更）／`ended`（已结束） | 【本期】 |
| `confirm_elder` | tinyint | ○ | 老人/家属确认（0/1） | 【本期】 |
| `confirm_guardian` | tinyint | ○ | 家属确认（0/1，**可选，不强制**） | 【本期】 |
| `confirm_time` | datetime | ○ | 确认时间 | 【本期】 |
| `change_from_plan_id` | varchar(32) | ○ | **变更来源计划**（改计划时新建一条，指向旧计划，**旧计划不删**） | 【本期】 |

> **⚠️ 计划变更纪律**：**改计划＝新建一条计划 + 指向旧计划**，**绝不原地改**。
> **理由**：政策要求"服务与计划相吻合"。若原地改，历史工单会突然"对上"一个当时不存在的计划——**这恰恰是"篡改数据"的典型形态**。**留旧版＝留证据。**

### 3.7 `plan_item` 计划项目明细表

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `plan_item_id` | varchar(32) | ✅ | 主键 | 【系统】 |
| `plan_id` | varchar(32) | ✅ | 计划 ID | 【本期】 |
| `svc_id` | varchar(32) | ✅ | **引用 `svc_local` 或 `svc_national` 的 ID**（按机构属地取） | 【本期】 |
| `svc_name_snapshot` | varchar(100) | ✅ | **项目名快照**（防目录改名后历史计划显示错乱） | 【本期】 |
| `svc_code_snapshot` | varchar(20) | ○ | **国家代码快照**（上报基准，二期用） | 【预留】R4 |
| `freq_type` | varchar(20) | ○ | 频次类型：`daily`／`weekly_n`／`monthly_n`／`as_needed` | 【本期】 |
| `freq_value` | int | ○ | 频次值（如每周 3 次填 3） | 【本期】 |
| `duration_min` | int | ○ | **单次时长（分钟）** | 【本期】 |
| `photo_tier` | varchar(10) | ✅ | **拍照档位**：`must`（必拍）／`optional`（可拍）／`free`（免拍） | 【本期】 |
| `caution_note` | text | ○ | **注意事项**（显示在护理员 APP M4，如"进食慢、小口、坐起90度"） | 【本期】 |
| `is_medical` | tinyint | ✅ | 是否医疗护理类（**决定是否需医护资质**） | 【本期】 |
| `need_cert` | tinyint | ✅ | 是否要求持证（医疗类＝1） | 【本期】 |

> **⚠️ `svc_name_snapshot` 不是冗余，是必需**：目录会更新（国家曾"合并同类项"、昆明可能改版）。**快照保证历史计划与历史留痕永远显示当时的项目名**，否则三年前的服务记录会突然"变成"另一个项目名——**这在稽核中是致命的**。

### 3.8 服务项目四层表（L1–L4）

**`svc_national`（L1 国家基准库 · 36 项）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `nat_id` | varchar(32) | ✅ | 主键（`NAT_` 前缀） |
| `nat_code` | varchar(20) | ✅ | **国家项目代码**（经复核定型为 **17 字符**：`L`+`0000`+大类(1生活照护/2医疗护理)+类别2位+项目序号2位+`0`+`010000`；字段留余量） |
| `nat_name` | varchar(100) | ✅ | 项目名称 |
| `nat_category` | varchar(20) | ✅ | 大类：`life`／`medical` |
| `nat_sub_category` | varchar(50) | ○ | 类别 |
| `recommend_staff` | varchar(50) | ○ | 推荐服务人员 |
| `recommend_duration` | int | ○ | 推荐时长（分钟） |
| `is_medical` | tinyint | ✅ | 是否医疗护理类 |
| `version` | varchar(20) | ✅ | 版本（如 `2025-24号`） |

**`svc_local`（L2 属地目录库）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `loc_id` | varchar(32) | ✅ | 主键（`LOC_` 前缀） |
| `loc_code` | varchar(12) | ✅ | **适用统筹区代码**（`530100`＝昆明等） |
| `local_item_name` | varchar(100) | ✅ | 本地项目名（**昆明 45 项实际名称**） |
| `local_category` | varchar(50) | ○ | 本地分类（昆明四大类：基础生活照料/非治疗性护理/功能维护/医疗护理） |
| `svc_time` | varchar(50) | ○ | 服务时间要求（昆明原文） |
| `min_freq` | varchar(50) | ○ | 最低服务频次（昆明原文） |
| `staff_qual` | varchar(100) | ○ | 护理人员资质要求（**昆明医疗类：仅限医疗机构/医养结合机构及持证医护人员**） |
| `is_medical` | tinyint | ✅ | 是否医疗护理类 |
| `source_doc` | varchar(100) | ✅ | 来源文件（如 `昆医保2021-45项`） |
| `map_status` | varchar(20) | ✅ | **映射状态**：`mapped`（可映射国家）／`local_only`（**仅属地执行**） |

**`svc_mapping`（L3 属地↔国家映射 · 机构不可见）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `map_id` | varchar(32) | ✅ | 主键（`MAP_` 前缀） |
| `loc_id` | varchar(32) | ✅ | 属地项目 ID |
| `nat_id` | varchar(32) | ○ | 对应国家项目 ID（**可空＝无法映射**） |
| `map_type` | varchar(20) | ✅ | **五值（与《逐项映射表》§0.2 一致）**：`one_to_one`（完全对应）／`many_to_one`（被合并，多个昆明项→国家 1 项，如头面清洁等→擦浴）／`partial`（近似对应，内涵不完全重合）／`local_only`（仅属地，国家目录无此项）／`national_only`（国家新增，昆明无、国家有） |
| `map_note` | varchar(200) | ○ | 映射说明（**我方内部技术资产**） |
| `status` | varchar(20) | ✅ | `confirmed`（人工核定）／`pending`（待核） |

**`svc_org`（L4 机构项目库）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `org_svc_id` | varchar(32) | ✅ | 主键（`ORG_` 前缀） |
| `org_id` | varchar(32) | ✅ | 机构 ID |
| `src_type` | varchar(10) | ✅ | 来源层级：`local`（从昆明45选）／`national`（从国家36选） |
| `src_id` | varchar(32) | ✅ | 来源项目 ID |
| `is_enabled` | tinyint | ✅ | 是否开展（**机构只能开关，不能删**） |
| `biz_line` | varchar(20) | ✅ | **业务线**：`ltci`／`self_pay`／`residence`／`civil_subsidy`——**本期恒 `ltci`，多业务线二期扩展** | **【预留】R8** |
| `price` | decimal(10,2) | **【预留】R1** | 服务价格（**本期可填可看，不参与结算**） |
| `price_effective` | date | **【预留】R1** | 价格生效日 |
| `is_new_national` | tinyint | ○ | **是否"国家新增项"**（昆明目录没有、国家有：吞咽功能训练等 5 项 → **必须显式提示**） |

> **⚠️ 五条多属地纪律在表结构上的落地**（对应 PRD-00 §2.4）：
> 1. **走配置不走代码** → 新增州市＝插一行 `loc_config` + 一批 `svc_local`，**代码零改动**；
> 2. **必须可映射** → `svc_mapping` 保证每项可追；`map_status = local_only` 的项**上报时自动排除**；
> 3. **机构不可改目录** → `svc_org` **只有 `is_enabled` 和 `price` 可改**，其余字段只读；
> 4. **国家新增项显式提示** → `is_new_national = 1` 的项在机构勾选页**独立区块显示**，不隐藏；
> 5. **映射表不对外** → `svc_mapping` 表**不提供任何机构侧接口**。

### 3.9 `order` 工单表（③ 派单工单）

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `order_id` | varchar(32) | ✅ | 工单 ID | 【系统】 |
| `elder_id` | varchar(32) | ✅ | 老人 ID | 【本期】 |
| `biz_line` | varchar(20) | ✅ | **业务线**：`ltci`／`self_pay`／`residence`／`civil_subsidy`——**本期恒 `ltci`，多业务线二期扩展** | **【预留】R8** |
| `plan_id` | varchar(32) | ✅ | **来源计划**（L2 硬锁落地） | 【本期】 |
| `org_id` | varchar(32) | ✅ | 机构 ID | 【本期】 |
| `service_date` | date | ✅ | **服务日期** | 【本期】 |
| `time_slot_start` / `time_slot_end` | datetime | ✅ | **服务时段**（用于冲突检测） | 【本期】 |
| `assignee_id` | varchar(32) | ○ | 派给谁（`staff_id`） | 【本期】 |
| `assign_time` | datetime | ○ | 派单时间 | 【本期】 |
| `assign_mode` | varchar(20) | ○ | 派单方式：`manual`／`batch_recommend`（**批量必须人工确认**） | 【本期】 |
| `order_status` | varchar(20) | ✅ | **工单状态**（见 PRD-00 §4.2 七态） | 【本期】 |
| `item_list` | json | ✅ | 本次工单项目的快照（来自 `plan_item`） | 【本期】 |
| `need_photo` | tinyint | ✅ | 本次是否含必拍项（**含则签退前强制拍照**） | 【本期】 |
| `cancel_reason` | varchar(200) | ○ | 取消原因（`order_status = 已取消` 必填） | 【本期】 |
| `reschedule_log` | json | ○ | **调单记录**（调过几次、谁调的、为什么） | 【本期】 |
| `qualification_check` | varchar(20) | **【预留】R2** | 资质校验结果（**本期恒 `unchecked`**） | **【预留】R2** |
| **`billable`** | tinyint | **【预留】R1** | 可计费标志（**本期恒 1**，不做结算判断） | **【预留】R1** |
| **`price_snapshot`** | decimal(10,2) | **【预留】R1** | 服务时点价 | **【预留】R1** |
| **`settle_period`** | varchar(20) | **【预留】R1** | 结算周期（如 `2026-10`） | **【预留】R1** |
| `exception_flag` | tinyint | **【预留】R6** | 是否异常费用 | **【预留】R6** |

> **⚠️ 一种硬冲突、其余软提示（PRD-02 §B2 落地）**：派单/调单时，**只对"同一 `assignee_id` 且 `time_slot` 重叠"返回硬错误（拒绝保存）**；其余情况（跨区距离远、项目不擅长、当日已排满）**一律只返回提示、不拦**。
> **理由**：**拦截要准，不能把便利性拦掉。** 组长宁愿微信群说一句就改了，也不会忍受系统处处拦住。

### 3.10 `record` 服务留痕表（③ 履约留痕）

| 字段 | 类型 | 必填 | 说明 | 标记 |
|---|---|:---:|---|---|
| `record_id` | varchar(32) | ✅ | 留痕 ID | 【系统】 |
| `order_id` | varchar(32) | ✅ | **来源工单**（L3 硬锁落地） | 【本期】 |
| `elder_id` / `assignee_id` | varchar(32) | ✅ | 老人／护理员 | 【本期】 |
| `checkin_time` | datetime | ✅ | **签到时间（系统自动取，不允许手工改）** | 【本期】 |
| `checkout_time` | datetime | ○ | **签退时间（同上）** | 【本期】 |
| `duration_min` | int | ○ | 实际时长（＝签退-签到，**系统算，人不能改**） | 【本期】 |
| `checkin_lat` / `checkin_lng` | decimal(10,6) | ○ | 签到定位（**定位失败不阻塞**，允许空） | 【本期】 |
| `locate_status` | varchar(20) | ✅ | `ok`／`failed`／`denied`（**失败照常可提交**） | 【本期】 |
| `record_status` | varchar(20) | ✅ | **留痕状态**：`draft`／`submitted`／`pending_qc`／`passed`／`returned`／`reported` | 【本期】 |
| `voice_file` | varchar(200) | ○ | 语音备注（免拍档留痕四要素之一） | 【本期】 |
| `offline_flag` | tinyint | ✅ | 是否离线创建（补传标记） | 【本期】 |
| `client_md5` | varchar(32) | ✅ | **客户端指纹**（防重复上传、防篡改） | 【系统】 |
| `submit_time` | datetime | ○ | 提交时间 | 【系统】 |
| `actual_duration_tier` | varchar(10) | ○ | 时长档位（**<5 分钟标黄**，供质控参考） | 【系统】 |

> **⚠️ 三条硬设计（都是合规点）**：
> 1. **签到签退时间、时长一律系统取，接口不接受客户端传入的这两个值**——防"补录时间"（对应"不得伪造/变造数据"）；
> 2. **定位失败不阻塞提交**（`locate_status = failed` 照常落库）——老人家里弱网是常态，**不能因为定位不到就不让干活**；
> 3. **时长不设"最低时长硬拦"**，只记 `actual_duration_tier`，**由质控看，不由系统罚**（对应 PRD-01 §4.7）。

### 3.11 `record_item` 留痕项目明细表

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `record_item_id` | varchar(32) | ✅ | 主键 |
| `record_id` | varchar(32) | ✅ | 留痕 ID |
| `svc_id` | varchar(32) | ✅ | 项目（来自 `plan_item`） |
| `exec_result` | varchar(20) | ✅ | **执行结果**：`done`（做了）／`undo_not_done`（**本次未执行**）／`undo_refused`（老人拒绝） |
| `undo_reason` | varchar(100) | ○ | 未执行原因（**选择项，非自由文本**） |
| `extra_flag` | tinyint | ○ | 是否临时加项（APP M2 §4.6） |
| `photo_required` | tinyint | ✅ | 本次是否需拍照（由 `photo_tier` 推导） |

> **⚠️ 措辞纪律落到数据层**：`exec_result` 的枚举值**必须是 `undo_not_done`（本次未执行）而不是 `not_done`（未做）**。
> **理由**：家属端与导出文书都要显示这个状态。**"未做"含指责意味，"本次未执行"是事实陈述**——这条在字段命名层就要卡住，不让前端有机会写"未做"。

### 3.12 `record_photo` 留痕照片表

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `photo_id` | varchar(32) | ✅ | 主键 |
| `record_id` | varchar(32) | ✅ | 留痕 ID |
| `svc_id` | varchar(32) | ○ | 关联项目（必拍项时） |
| `file_path` | varchar(300) | ✅ | 存储路径（**压缩后 ≤500KB**） |
| `file_size` | int | ✅ | 字节数（校验压缩是否生效） |
| `visible_to_family` | tinyint | ✅ | **是否对家属可见（本期默认 0）** |
| `upload_batch` | varchar(32) | ○ | 补传批次号（离线补传用） |
| `keep_until` | date | ✅ | **保留至（补传后至少 7 天）** |

> **⚠️ `visible_to_family` 本期恒为 0**（PRD-03 §4.2 决策）。**字段先建好**——等用户定了"是否给机构开关"，**只改默认值或加一个开关，不改结构**。

### 3.13 `record_abnormal` 异常上报表

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `abnormal_id` | varchar(32) | ✅ | 主键 |
| `record_id` | varchar(32) | ✅ | 留痕 ID |
| `elder_id` / `reporter_id` | varchar(32) | ✅ | 老人／上报人 |
| `abnormal_type` | varchar(30) | ✅ | **分类（9 宫格，必选）**：皮肤异常/跌倒/呛咳进食/意识精神/发热感染/管路异常/疼痛/排泄异常/其他 |
| `abnormal_desc` | text | ○ | 描述（**可选**，语音转写或手填） |
| `voice_file` | varchar(200) | ○ | 语音（可选） |
| `has_photo` | tinyint | ○ | 是否附照片（可选） |
| `notify_status` | varchar(20) | ✅ | 通知状态：`pending`／`notified`（**上报后即时推送机构**） |
| `handle_status` | varchar(20) | ✅ | 处理状态：`new`／`processing`／`handled` |
| `handle_result` | varchar(200) | ○ | 处理结论 |
| `link_plan_change` | varchar(32) | ○ | **是否联动变更计划**（指向新 `plan_id`） |

> **⚠️ "一切可选、分类必选"的落地**：**只有 `abnormal_type` 是必填，其余全可选**（PRD-01 §M3）。
> **理由**：需填会导致"不报"，而"发现了没进系统"是最严重的断链。**宁要一条没人名没照片的异常，也不要一条没报上来的压疮。**

### 3.14 `qc` 质控记录表（④ 质控闸门）

| 字段 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `qc_id` | varchar(32) | ✅ | 主键 |
| `record_id` | varchar(32) | ✅ | 被质控的留痕 |
| `qc_type` | varchar(20) | ✅ | `normal`（常规）／`auto_push`（系统主动推送）／`recheck`（退回后复检） |
| `push_reason` | varchar(100) | ○ | **推送原因（五类）**：必拍未拍／时长异常／异常上报未处理／住院状态仍有派单／项目数与计划不符 |
| `qc_result` | varchar(20) | ○ | `passed`（放行）／`returned`（退回） |
| `qc_note` | varchar(200) | ○ | 质控意见（**退回时必填**） |
| `qc_staff_id` | varchar(32) | ✅ | 质控员 |
| `qc_time` | datetime | ✅ | 质控时间 |
| `pass_time` | datetime | ○ | 放行时间（→ 进上报池，二期） |
| `first_qc_id` | varchar(32) | ○ | **首次质控 ID**（退回补正后重提，形成链） |

> **⚠️ 全量非抽检（落库层面保证）**：**每一条 `record_status = submitted` 的留痕，都必须生成一条 `qc` 记录**（由定时任务扫描生成，`qc_type = normal`）。
> **理由**：抽检＝总有漏的；而**"先质控再上报"是国家明文**（PRD-00 hard lock L5）。**全量生成 qc 记录，是把"不抽检"从人工承诺变成数据结构。**

---

## 四、状态机 ↔ 字段值对照（一份表说清"什么状态能干什么"）

### 4.1 待遇状态 `elder.treat_status`（十态）

> **⚠️ 2026-10-12 修订（与 `P0 PRD §3.2／§7.4` 对齐）**：七态 → **十态**，新增 `waiting_period`／`review_waiting`／`transferring`。**本表为分册同源表，改合稿必改此处**（防"合稿改了、分册没改"）。

| 值 | 中文 | 可否新建计划 | 可否派单 | 可否服务 | 可否计费 |
|---|---|:---:|:---:|:---:|:---:|
| `pending_file` | 待建档 | ✅ | ❌ | ❌ | ❌ |
| `waiting_period` | **待起付（等待期/垫付期）** | ✅ | ✅ | ✅（**仅垫付台账**） | ❌ |
| `active` | 正常享受 | ✅ | ✅ | ✅ | ✅ |
| `hosp_pause` | 住院暂停 | ❌ | ❌ | ❌ | ❌ |
| `review_waiting` | **复评等待期** | ❌ | ❌ | ❌ | ❌ |
| `transferring` | **跨统筹区转移中** | ❌ | ❌ | ❌ | ❌ |
| `dead` | 死亡 | ❌ | ❌ | ❌ | ❌ |
| `long_away` | 长期异地居住 | ❌ | ❌ | ❌ | ❌ |
| `benefit_expired` | 待遇到期 | ❌ | ❌ | ❌ | ❌ |
| `terminated` | 已终止 | ❌ | ❌ | ❌ | ❌ |

> **接口层强制**：任何创建 `order` 的请求，**先校验 `elder.treat_status ∈ {active, waiting_period}`**，不满足**直接拒绝**（不是警告）。**这就是 L1 的代码落地。** **⚠️ `waiting_period` 是 L1 唯一例外**：允许建 `order`，但其 `record` 打 `is_prepaid=1`、`billable=0`（不进结算池）。

### 4.2 工单状态 `order.order_status`（八态）

| 值 | 中文 | 后续可流转到 |
|---|---|---|
| `to_assign` | 待派单 | `assigned` / `cancelled` |
| `assigned` | 已派单 | `serving` / `cancelled` / `**to_assign**`（调单） |
| `serving` | 服务中 | `done` / `abnormal` |
| `done` | 已完成 | —（仅补正留痕） |
| `abnormal` | 异常 | `done` / `cancelled` |
| `cancelled` | 已取消 | — |
| `overdue` | 逾期未做 | → 风险预警 |
| `not_met` | **未遇（扑空）** | 已到访未服务；到访时间＋定位＋原因必留 → 推组长决策 |

### 4.3 留痕状态 `record.record_status`（六态）

| 值 | 中文 | 说明 |
|---|---|---|
| `draft` | 草稿 | 服务中；**离线也在此状态** |
| `submitted` | 已提交 | 护理员签退提交 |
| `pending_qc` | 待质控 | 进入质控队列（自动生成 `qc` 记录） |
| `passed` | 已放行 | 质控通过 → 进上报池〔二期〕 |
| `returned` | 已退回 | 可补正后重提 |
| `reported` | 已上报 | 〔二期〕 |

---

## 五、接口契约

> **说明**：本节定义**接口的语义契约**（谁调、传什么、返什么、什么情况拒），**不定义传输协议细节**。三端（APP／后台／家属端）共用同一套后端接口。
> **统一响应结构**（所有接口）：

```json
{
  "code": 0,              // 0=成功；非0=失败（见 5.1 错误码）
  "message": "成功",       // 面向开发；错误时给可读原因
  "data": { },            // 业务数据
  "hint": ""              // ⚠️ 面向用户的"怎么解"提示（硬锁拒绝时必须返回）
}
```

### 5.1 统一错误码表（硬锁与业务规则）

| code | 含义 | 前端处置 |
|:---:|---|---|
| `0` | 成功 | — |
| `1001` | **无有效待遇，不可服务**（L1） | 显示 `hint`，禁止进入服务页 |
| `1002` | **无有效计划，不可派单**（L2） | 引导"先制定计划" |
| `1003` | **无有效工单，不可录痕**（L3） | 拒绝提交 |
| `1004` | **留痕不完整，不可进上报池**（L4） | 列出缺什么 |
| `1005` | **未质控放行，不可上报**（L5） | 提示先质控 |
| `1006` | **资质不匹配（本期仅提示，不拦截）**（L6） | **仅提示，允许继续** |
| `2001` | 派单时间冲突（同人同时段重叠） | **硬拒**，提示换人或改时 |
| `2002` | 计划项目数不满足属地规则 | **仅提示**，可保存 |
| `3001` | 必拍项未拍照，不可签退 | 硬拒，引导拍照 |
| `3002` | 定位失败（**非错误，仅标记**） | 允许提交 |
| `4001` | 越权：非本机构/非本人数据 | 403 |

> **⚠️ `1006` 的设计是刻意的**：**资质校验本期返回一个"提示级"错误码而不是"拒绝级"**。
> 这样**二期只需把 `1006` 从"提示"改成"硬拒"**，前端代码基本不用动——**这就是"预留位"在接口层的价值**。

### 5.2 本期接口清单（按 P0 四块）

**A · 待遇档案（①）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/elder/create` | POST | 新建老人档案 | 建档时限倒计时；`loc_code` 必填 |
| `/elder/detail` | GET | 档案详情 | 权限：本机构 |
| `/elder/status/change` | POST | **变更待遇状态** | **`change_reason` 必填**；写 `elder_status_log` |
| `/elder/status/log` | GET | 状态变更历史 | 只读 |
| `/elder/list` | GET | 老人列表（后台 B1） | 支持按待遇状态/护理等级筛 |

**B · 服务计划（②）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/plan/create` | POST | 制定计划 | **项目数按属地规则校验**（`2002` 提示级） |
| `/plan/change` | POST | **变更计划（新建＋指向旧）** | **不原地改**；旧计划转 `changed` |
| `/plan/detail` | GET | 计划详情 | 含 `item_list` |
| `/plan/confirm` | POST | 老人/家属确认 | 可选 |
| `/svc/local/list` | GET | **按参保地加载属地目录** | 昆明→45项；州市→36项 |
| `/svc/org/list` | GET | 机构项目库 | — |
| `/svc/org/config` | POST | 勾选＋配价 | **只允许改 `is_enabled`/`price`** |
| `/svc/org/new-national` | GET | **国家新增项列表** | 昆明机构**必须显式展示** |

**C · 派单工单（③）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/order/generate` | POST | 由计划生成工单 | **L2**：无计划拒绝 |
| `/order/assign` | POST | 派单 | **L1**：待遇非 `active` 拒绝；`2001` 时间冲突硬拒；`1006` 资质提示 |
| `/order/reassign` | POST | 调单 | 记 `reschedule_log`；**≤3 步** |
| `/order/batch-recommend` | GET | 批量推荐 | **仅返回推荐，必须人工确认后逐个 assign** |
| `/order/today` | GET | 护理员今日任务（M1） | 仅本人 |
| `/order/cancel` | POST | 取消工单 | `cancel_reason` 必填 |
| `/order/detail` | GET | 工单详情（M4） | 含**注意事项区块** |

**D · 履约留痕（③）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/record/checkin` | POST | 签到 | **服务器取时间**；定位失败不阻塞（`3002`） |
| `/record/item/save` | POST | 保存项目执行 | `exec_result` 枚举 |
| `/record/photo/upload` | POST | 上传照片 | **压缩校验 ≤500KB**；返回 `photo_id` |
| `/record/checkout` | POST | 签退提交 | **必拍未拍拒绝**（`3001`）；计算时长 |
| `/record/offline/sync` | POST | **离线补传** | `client_md5` 去重；**静默不弹窗** |
| `/record/detail` | GET | 留痕详情 | — |
| `/abnormal/report` | POST | **异常上报** | 仅 `abnormal_type` 必填 |
| `/abnormal/list` | GET | 异常列表（后台 B4） | 主动推送来源 |

**E · 质控闸门（④）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/qc/pending/list` | GET | 待质控列表（含主动推送） | **全量**，非抽检 |
| `/qc/detail` | GET | 质控详情 | 含留痕全文与照片 |
| `/qc/pass` | POST | 放行 | 写 `qc_result=passed`、`pass_time` |
| `/qc/return` | POST | 退回 | **`qc_note` 必填** |
| `/qc/exception/link` | POST | **异常联动改计划** | 生成新 `plan_id` 并回填 `link_plan_change` |

**F · 家属端（③）**

| 接口 | 方法 | 说明 | 关键校验 |
|---|---|---|---|
| `/family/bind` | POST | 绑定（姓名＋手机号后4位） | **只看自家** |
| `/family/elder` | GET | 我家老人信息 | 过滤 `visible_to_family` |
| `/family/records` | GET | 服务记录列表 | **不返回价格字段** |
| `/family/ack` | POST | **可选确认** | **非必做，不记录"未确认"为异常** |
| `/family/feedback` | POST | 反馈 | — |

### 5.3 硬锁在接口层的落点总表（L1–L6）

| 锁 | 接口 | 触发条件 | 结果 |
|---|---|---|---|
| **L1** | `/order/assign`、`/record/checkin` | `elder.treat_status ∉ {active, waiting_period}` | `1001` **拒绝**；**`waiting_period` 放行但打 `is_prepaid=1`、不计费** |
| **L2** | `/order/generate` | 无 `plan_status=active` 的计划 | `1002` **拒绝** |
| **L3** | `/record/*` | 无有效 `order` | `1003` **拒绝** |
| **L4** | `/qc/pass` | 留痕缺必填要素 | `1004` **拒绝** |
| **L5** | `/report/*`〔二期〕 | 无 `qc_result=passed` | `1005` **拒绝** |
| **L6** | `/order/assign` | `staff.cert_status ≠ valid` | `1006` **仅提示，不拒绝**（**二期改硬拒**） |

---

## 六、⭐ 二期预留位落地对照（R1–R6，逐项核对）

> 对应 PRD-00 §8。**本节证明"只加不改"是可验证的**——二期每项功能，都能在本期表结构里找到它要用的字段。

| # | 二期功能 | 本期已建的字段/表 | 二期要新增的 | **要改的** |
|:---:|---|---|---|---|
| **R1** | 结算对账 | `order.billable`／`price_snapshot`／`settle_period`；`svc_org.price` | `settlement` 表（**字段已预定义，见 §6.1**）、申报页、导出格式 | **无** |
| **R2** | 资质人员 | `staff.cert_*` 五字段；`order.qualification_check` | 到期提醒任务、禁派逻辑、资质管理页 | **无**（`1006` 改硬拒属逻辑开关） |
| **R3** | 院长看板 | 数据层可直接聚合现有表 | 聚合视图、图表页 | **无** |
| **R4** | 上报池与接口 | `report` 表；`order`/`plan_item` 的 `official_no`/`loc_code`/代码快照 | 适配层实现、上报页 | **无** |
| **R5** | 医保状态同步 | `elder.status_source`（人工/接口） | 接口实现 | **无**（只改字段值来源） |
| **R6** | 异常费用 | `order.exception_flag`／`exception_reason`／`handle_deadline` | 异常处理页、超时提醒 | **无** |

### 6.1 `report` 上报表（本期建表，不写入业务数据）

| 字段 | 类型 | 说明 | 标记 |
|---|---|---|---|
| `report_id` | varchar(32) | 主键 | 【系统】 |
| `record_id` / `order_id` | varchar(32) | 来源 | 【预留】 |
| `report_status` | varchar(20) | `to_report`／`reported`／`rejected`／`corrected` | **【预留】R4** |
| `report_time` | datetime | 上报时间 | **【预留】R4** |
| `official_no` | varchar(50) | **官方受理号** | **【预留】R4** |
| `loc_code` | varchar(12) | 上报归属统筹区 | **【预留】R4** |
| `nat_code_snapshot` | varchar(20) | 上报时使用的**国家代码** | **【预留】R4** |
| `adapter_result` | json | 适配层返回（A/B/C 档） | **【预留】R4** |

### 6.2 `settlement` 结算表（本期建表，不写入业务数据）

| 字段 | 类型 | 说明 | 标记 |
|---|---|---|---|
| `settle_id` | varchar(32) | 主键 | 【系统】 |
| `org_id` / `settle_period` | varchar | 机构／结算周期 | **【预留】R1** |
| `amount_total` | decimal(12,2) | 申报总额 | **【预留】R1** |
| `amount_passed` | decimal(12,2) | 审核通过额 | **【预留】R1** |
| `amount_rejected` | decimal(12,2) | 拒付额 | **【预留】R1** |
| `submit_date` / `pay_date` | date | 申报日／拨付日 | **【预留】R1** |
| `exception_reason` | varchar(200) | 差异说明 | **【预留】R6** |
| `handle_deadline` | date | **说明超时（3 工作日）** | **【预留】R6** |

> **⭐ 这就是"一次设计到位、免得返工"的验证**：二期要做结算，**`settlement` 表的字段今天就定好了**，二期只写页面和申报逻辑，**不碰任何已上线的表**。

### 6.3 接口契约层预留

| 预留项 | 本期定义（写死） | 二期 |
|---|---|---|
| **适配层输入输出格式** | **按国家编码规范定稿**（机构编码 13 位 `LH`+区划+序号、人员编码 14 位 `LN`+区划+序号、**项目代码 17 字符**：`L`+`0000`+大类+类别2位+序号2位+`0`+`010000`） | 直接实现 |
| **A/B/C 三档** | A 人工登记／B 文件导入导出【本期】／C 专线前置机【预留】 | 实现 C 档 |
| **错误码 `1006`** | **提示级**（不拦） | 改**拒绝级** |

> **⚠️ 项目代码位数说明**：原写"14 位"系归纳有误。**经专项复核定型为 17 字符**，且**仅内部逻辑推演、未与官方原件对照** ⇒ **正式上报前必须以官方电子版核对**。详见《20261011-国家36项代码复核报告（位数问题解构）》。**字段长度一律按 `varchar(20)` 设计，留余量。**

---

## 七、⭐ 数据安全与留痕（合规条款的工程落地）

> 这一节不是"技术选型"，是**政策明文要求在本系统的落地方式**。巡查表"信息管理 15 分"里的实名制、动态管理、材料调取，全都落在这一节。

| 要求（政策） | 工程实现 | 对应巡查点 |
|---|---|---|
| **一人一档** | `elder` 表 ＋ 全链路 `elder_id` 外键，`order`/`record`/`qc` 均可回溯到人 | 信息管理 |
| **实名制管理** | `staff.id_card_no` 加密存储、唯一约束；`user` 绑定 `staff_id` | 信息管理第 1 条 |
| **不可伪造/变造** | ①`checkin/checkout` 服务器取时；②`elder_status_log` 必填原因；③`record` 软删除不物理删；④`client_md5` 防重复提交 | 巡查高频扣分项 |
| **记录与计划/数据/考勤相吻合** | `plan_item` → `order.item_list` → `record_item` **三级快照一致**（同一 `svc_id`） | 服务管理 |
| **材料调取（巡查时能取证）** | 全表导出接口，按老人/时间段/项目导出，**导出即合规版式** | 档案管理 6 分 |
| **数据保留** | 照片 `keep_until`（补传后 ≥7 天），业务数据软删除保留 | 档案管理 |
| **隐私号／不展示真实号码** | 家属端接口**一律不返回护理员真实手机号**（扫码端走隐私号，与 C 端口径一致） | 合规红线 |

> **⚠️ 一条容易忽略的工程纪律**：**`record` 与 `qc` 表一律软删除**——`is_deleted` 置 1，**原始记录永久保留**。
> **理由**：长护险数据是**基金支付凭证**。若允许物理删除，"事后删记录"就变成可能，那就丧失了留痕的意义。**软删除＋软删除也要留操作日志，是"不可无痕修改"的最后一道工程防线。**

---

## 八、⚠️ 与文档/规范的差异与待确认（不阻塞开发）

| # | 事项 | 影响 | 处置 |
|:---:|---|---|---|
| 1 | **45↔36 完整逐项映射表**（`svc_mapping` 全量数据） | 昆明机构上报准确性 | ✅ **已完成**，见《20261011-昆明45项↔国家36项-逐项映射表（L3数据·可入库）》（45 行逐项数据）。**遗留风险已转移至下方第 2 项（代码位数）** |
| 2 | **国家项目代码复核** | 上报字段准确性 | ✅ **已完成内部复核**（位数问题已解构，规则定型 17 字符，3 项短形态已补正）——见《20261011-国家36项代码复核报告（位数问题解构）》。⚠️ **仍须官方电子版最终确认**（复核为逻辑推演，非原件对照）；字段按 `varchar(20)` 设计 |
| 3 | 各州市 `loc_config` 是否另有自建目录 | 属地目录库内容 | 签约前逐一核实（推定＝36 项） |
| 4 | 昆明 45 项是否已更新 | 属地目录库内容 | 建议 0871-65919196 核实 |
| 5 | 照片**保留期限**（政策要求 vs 机构成本） | 存储策略 | 有地方要求"保存 10 年"；建议按属地要求配置化，**不当统一硬编码** |

> **⚠️ 处置原则**：**这 5 项都不阻塞开发启动**——前 4 项是"数据内容"和"配置值"，不是"结构"；**唯第 2 项须在真正对接上报前收口**（因上报字段错＝功能不可用），但**不影响 P0 四块的开发**（P0 不含上报）。

---

## 九、本份交付说明

### 9.1 本文档定义了什么

- 22 张表清单与用途
- **6 张核心表的完整字段定义**（老人档案／计划／工单／留痕／质控／机构）
- **服务项目四层表（L1–L4）字段结构**
- 状态机 ↔ 字段值对照（待遇／工单／留痕）
- **统一响应结构与错误码表**（含 L1–L6 落点）
- **本期接口清单 6 组 40+ 接口**
- **R1–R6 二期预留位的逐项落地对照**
- 数据安全与留痕的工程实现（政策条款 → 代码）

### 9.2 下一步可做

| 序 | 文档 | 内容 |
|:---:|---|---|
| 1 | **45↔36 完整映射表**（数据表） | 补 §8 第 1 项，昆明每一项对应到国家项目 |
| 2 | 界面线框稿 | 把 PRD 页面画成可看的样子 |
| 3 | 开发排期与模块拆分 | 按 P0 四块拆开发任务 |

---

**云南投云科技有限公司**
编制：滇小构｜2026-10-11（第 4 步 · 数据字典与接口契约 · 待确认）