touyun-elderly-care/docs/refs/20261011-数据字典与接口契约（第4步·V1待确认）.md

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

第 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，多业务线二期扩展
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／后台／家属端）共用同一套后端接口。 统一响应结构（所有接口）：

{
  "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 步 · 数据字典与接口契约 · 待确认）