touyun_liuyun/touyun-elderly-care
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 入库需求与范围基线（P0 PRD + 参考文档 + 范围清单）

Browse Source 
- docs/requirements/P0 PRD（交付开发·V1）
- docs/requirements/服务机构端-P0范围清单、评估机构端-待设计清单
- docs/refs/ 数据字典与接口契约、产品介绍

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
liuyun 2026-10-14 10:33:39 +08:00
parent 02091d37cf
commit 87b6a532b4
5 changed files with 3007 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
docs/refs/20261011-投云长护险管理系统-产品介绍（完整版）.md Normal file
View File

@ -0,0 +1,197 @@
# 投云长护险管理系统 · 产品介绍（完整版 · V2）
**云南投云科技有限公司**
> **⚠️ 阅读说明（2026-10-12 加）**：**本文档描述产品的完整形态，不是首期交付承诺。**&#x9996;期实际交付范围以《产品介绍（首期版）》与《P0 PRD》为准；本文中标注"〔二期〕/升级项"的功能，属分期落地。
>
> **📝 版本修订注（2026-10-12，只动以下 5 处，其余逐字保留）**：①"五种状态"→**七种**、"自动拦截"→"状态标为住院后拦截"；②"申报即生成"→**"申报底稿自动汇总"**（讲清"底稿≠最终提交，提交以医保平台为准"）；③第②节"资质校验"补"资质库建成后升级为自动拦截"；④第⑥节"无资质自动拦截派单"→**"无资质派单拦截（升级项）"**；⑤第⑧节新&#x589E;**"身份核验"边界说明**（扫脸/现场核验由官方 APP 承担，我方当前只做实名建档兜底，核验机制待确认，不写成卖点）。**理由**：消除"把二期能力当现有卖点讲"的超载表述（见 `20261012-22条答问返工决议单`）。
>
> **📝 版本修订注（2026-10-12 第二轮，只动以下 5 处，其余逐字保留）**：按机构老板二轮 5 问回填——①第一节新增"会不会变成'录两次'"小节；②第①节"老人建档"补**批量导入**（此前漏讲的卖点，PRD §5.5.1 B1-B 已写定）；③第五节新增"培训与上手""手机与流量"两段；④第八节第 3 条"与医保平台的对接"扩写为**三步走**（补医保办发〔2024〕21 号／〔2025〕19 号依据）；⑤第八节新增第 6 条"责任边界"（只讲原则，赔付数字归合同）。**用户版微调一律保留。**&#x8BE6;见《20261012-机构老板二轮5问应答-大白话版》。
---
## 一、这套系统是做什么的
> **投云长护险管理系统，是帮护理机构把"长护险服务"这件事，做得「省事、合规、能结回钱」的内部运营系统。**
云南省级层面统一建了打卡留痕的官方 APP，护理员签到、留痕都走「云南医保服务平台」APP。但机构自己的那摊子事——**谁服务谁、什么时候去、去了做什么、做得对不对、台账怎么对得上、钱怎么报回来**——官方 APP 管不到，还得靠机构自己拿纸、拿 Excel、拿微信群去撑。
**我们做的，就是官方管不到的这一段：服务计划、派单、台账、质控、对账。**
一句话：**官方管"打卡留痕"，我们管"内部运营"。**
**三个"不做"（边界，从一开始就写清）：**
| 不做 | 原因 |
| -------------- | ------------------------- |
| 不做打卡 APP，不替代官方 | 云南省级统建，护理员统一用官方 APP，这条路不碰 |
| 不做评估、不做诊疗判断 | 医学判断由机构持证人员做，系统不越界 |
| 不做"全能系统" | 功能越多，一线越不用。能砍就砍，砍到一线愿意用为止 |
**那护理员会不会变成"录两次"？（机构问得最多的一条，先答掉）**
不会。官方 APP 的打卡照打——那是给医保的考勤，谁也替代不了；**我们这边她不打字、不填表，说一句"给老人做了什么"、该拍的项目拍张照，就完事**。真实工作量是"打卡照旧＋多说一句话"，不是"同一套东西录两遍"。往后还有两步减法：当地经办若能导出数据，可做文件级对账、不用手工誊；医保接口规范一发布，两套系统直接对接（国家明文路径，详见第八节第 3 条）。
---
## 二、系统全景：三个端 + 一个后台
| 端 | 谁用 | 干什么 |
| ---------------- | ------------- | ---------------------------- |
| **护理员 APP**（安卓） | 一线护理员 | 干活现场的唯一操作面：今天去哪几家、签到、勾项目、报异常 |
| **机构管理后台**（电脑网页） | 组长 / 质控员 / 院长 | 排班派单、查记录、质控放行、对账、看经营 |
| **家属公众号**（微信） | 老人子女 | 只看看：这周谁来过、做了什么，可顺手点个"知道了" |
三个端不是三套系统，是**同一套数据的三个入口**。护理员录一次，后台和家属端都看得到，谁都不用再抄一遍。
> **设计原则一句话**：一线端做减法（功能最少、最好上手），管理端做加法（信息最全、一眼看到该管的事）。
---
## 三、完整功能体系（七大模块，一页看清）
| 模块 | 解决什么 | 主要用户 |
| ----------- | ----------------------------------- | ------ |
| ① 服务对象与待遇管理 | 无有效待遇不得服务；计划有法定时限 | 质控员 |
| ② 派单与工单 | 不漏派、不重派、时间不冲突 | 组长 |
| ③ 履约留痕（核心） | 记录真实、完整、可追溯 | 护理员 |
| ④ 内部质控与风险闸门 | 上报前自检，把问题拦住 | 质控员/院长 |
| ⑤ 结算与对账 | 一次录入、三账同源，**自动汇总申报底稿**（提交以医保平台为准） | 质控员/院长 |
| ⑥ 资质与人员管理 | 资质到期提醒、人岗匹配（**派单校验提示；资质库建成后升级为拦截**） | 质控员 |
| ⑦ 院长看板 | 只看三块：可结算 / 风险 / 人效 | 院长 |
---
## 四、七大模块逐一说明
### ① 服务对象与待遇管理
- **老人建档**：给每位老人建一份电子档案，含待遇信息、护理等级、注意事项。签约后 **1 个月内**须建档，系统**倒计时提醒、超期标红**。
- **档案批量导入**：现有 Excel 台账不用重录——老人档案、护理员档案、服务项目价格**三类均可 Excel 整批导入**；系统提供标准模板，导入前**逐行校验**（身份证 18 位＋校验位、必填非空、参保地合法、项目须在属地目录内），**错误行不写入、单独生成错误清单**（第几行、什么原因），改完再导；每次导入留操作日志。纸质台账建议先建在保老人跑起来，历史档案分批补。
- **待遇状态管理**：待建档、正常享受、住院暂停、死亡、长期异地居住、待遇到期、已终止，**七种状态**一眼分清；**老人状态标为住院后，系统立即拦截派单**（状态由机构维护）。
- **服务计划**：签约后 **5 个工作日内**须制定计划；从属地目录选项目、定频次和时长；**项目数量按属地规则校验，不满足不能提交**；计划需家属或长护专员确认后生效；**变更全程留痕**。
- **目录外服务**：需书面同意的项目，须先上传同意件才能落单。
### ② 派单与工单
- **自动生成工单**：计划生效后，系统按周期和频次自动生成每日工单。
- **排班表**：日视图、周视图切换，每个护理员的负荷一眼可见；空缺、时间冲突自动标出。
- **调单**：护理员临时请假，组长**不超过 3 步**把单转给别人，不比微信群慢。
- **冲突检测**：同一护理员同一时段被派两单，系统**直接拦住不让保存**。
- **派单时资质校验提示**：派单时系统对护理员资质进行校验，资质过期或不匹配的**给予提示**（**资质库建成后升级为自动拦截**）。
### ③ 履约留痕（核心）
护理员上门：签到 → 干活 → 签退，项目照着勾。
- **首屏即任务**：打开 APP 就知道今天去哪几家、几点、做什么。
- **完成一次记录不超过 4 次点击，不打一个字**——全用勾选和语音。
- **签到自动定位取时，签退自动算时长**，不用手工填。
- **没信号也能用**，联网后自动补传。
- **拍照分档**（下面第五节详述）。
- **异常一键上报**：发现压疮、呛咳、跌倒等，选个分类、说句话即可，**即时推给组长和质控员**。
### ④ 内部质控与风险闸门
- **全量审核，不抽检**：护理员交回的每一条记录都进质控队列，有问题退回补正，没问题放行。
- **主动推送，不等人翻**：谁没拍照、谁时长异常、谁住院了还有派单——系统**主动推到质控员面前**。
- **异常联动改计划**：护理员上报压疮 → 质控员判断要加压疮护理 → **直接改计划**，下次派单自动带出该项目。
- **改不了原始证据**：签到时间、定位、照片本身不可改，只能补正、保留原值。
### ⑤ 结算与对账
- **申报底稿自动汇总**：月底系统自动汇总本月可结算数据、生成**申报底稿（可结算清单）**，**数据直接来自服务留痕，不二次手填**。**申报底稿是"拿来申报的底稿"，最终提交与数据以医保平台为准**——系统不代替官方申报口径。
- **三价一致性校验**〔二期〕：机构价、备案价、公示价不一致即拦截。**⚠️ 如实说明：该能力属二期（结算对账模块）**——现阶段库内**仅有"机构价"一个字段**，**备案价/公示价暂无数据来源**，此时三价一致性**以机构台账人工核对为准**（备案价取值口径待核）。**对客不得表述为"系统现已自动校验三价"。**
- **回款看得见**：钱报回来多少、卡在哪一步，一眼清楚（只读展示，不碰资金池）。
- **差异可对账**：结算数据与系统记录有出入时，人工核对、全程留痕。
### ⑥ 资质与人员管理
- **人员库与资质台账**：所有护理员的证书、有效期统一管理。
- **到期自动提醒**：证书快过期，提前推给质控员和护理员本人。
- **无资质派单拦截（升级项）**：资质过期就不能派他做对应项目（**首期先做派单提示，资质库建成后升级为自动拦截**）。
- **实名制动态管理 + 工作质量考核**：入离职、资质变动全程实名可查，考核标准机构可配置。
### ⑦ 院长看板
院长一登录，**只看三块**：本月能报回多少钱、有没有"雷"（资质到期、台账缺失等风险）、同样的人能不能多接单（人效趋势）。**不堆指标，只看结果。**
---
## 五、为什么护理员愿意用（这是本系统的根）
功能堆得再多，一线不用，就是空壳。这套系统的设计，**处处为"一线用不惯"让路**：
- **最多 4 次点击**完成一次服务记录，**不打一个字**；
- **没信号也能用**，联网后自动补传；
- **关键按钮大字号**，不做层层菜单，**打开就是今天要去哪几家**；
- **录错了能撤销**，先提示、不直接扣钱；
- **拍照分档**，不搞一刀切：
- 高风险项目（沐浴、搬抬转移、导管护理、鼻饲喂食）——**必须拍照**，这是机构唯一的免责证据；
- 日常项目（翻身、喂饭、陪伴、剪指甲、整理床铺）——**语音描述即可**，不用逼老人摆拍；
- 中间项目（擦身、更衣、协助如厕）——默认免拍，出现异常才补拍。
**我们做的是"把政策本来就要的事，做成一线干得动的样子"，不是给一线再加一套麻烦。**
**培训与上手**：我们的验收标准是"不教也会用"——找一位从没见过系统的护理员，不给培训、只给手机，**10 分钟内独立完成一次服务记录**，测不过就改设计，不怪护理员。落地配套：不集训全员，**只训组长和质控员（一次约 2 小时）**；护理员侧配一页图文卡＋60 秒短视频＋APP 内首次引导；上线首周建"陪跑群"，客服远程兜底；打字不会的全程可用语音。（上门/远程形式、次数、响应时限属实施条款，写进合同。）
**手机与流量**：APP 按低配安卓机设计，老机型跑得动；照片自动压缩、没信号先存着有网再传，流量目标控制在**每人每月 500MB 以内**（联调期实测后给数）。机构常见做法是给护理员**每人每月 10–20 元通讯补贴**，十几人一年约两三千——对比一笔拒付就回本（发不发属机构内部决定）；个别没有智能机的，可备两三台二手安卓做工作机轮换，系统支持同账号换设备登录。
---
## 六、合规这件事，怎么落在系统里
合规不是贴在墙上的口号，是**干活时自然产生的**。系统里，政策的每一条要求都有对应的落点，其中最关键的是**六条硬锁**（系统强制，点不动、绕不过）：
| 硬锁 | 含义 |
| ----- | --------------------------------- |
| 无有效待遇 | 不能建档、不能服务 |
| 无服务计划 | 不能生成工单 |
| 无有效工单 | 不能录入留痕 |
| 无完整留痕 | 不能进上报池 |
| 无质控放行 | 不能上报结算 |
| 无有效资质 | 不能派该项目的单（**首期为派单提示，资质库建成后升级为硬拦**） |
> **⚠️ 口径纪律（写死）**：**前五条为系统"点不动"的硬锁；第六条（资质）首期为提示级、后续升级为硬锁。**&#x5BF9;外不得把第六条讲成"现已自动禁派"。另："无完整留痕→不能进上报池""无质控放行→不能上报结算"两条，**与"结算对账"同属分期落地**，见首页阅读说明。
其他关键落点：服务项目**只能从国家目录选、不得自创**；护理记录**一次录入、三端同源**；**记录不可无痕修改**，改动留补正痕迹、原值保留；档案**一人一档、随时可导出**，格式对齐国家 2026 版文书。
---
## 七、昆明和州市，目录不一样怎么办
云南实行**州（市）级统筹**，各地服务项目目录并不完全相同：
- **昆明市**（老试点）执行**本地目录 45 项**；
- **新建制州市**（曲靖、玉溪、楚雄、文山、西双版纳、大理、临沧等）执行**国家统一目录 36 项**。
系统**预置了这两套目录**，机构注册时选定参保地，系统**自动加载对应目录**；机构只需**勾选自己开展的项目、填好价格**即可使用，不用自己一条条录，也不用担心录错成"目录外项目"。以后新增一个州市，加一份配置即可，**不改程序、不影响现有机构**。
---
## 八、几点说明
以下几项，需要机构了解（**这也是对机构负责**）：
1. **资质信息由机构维护**：护理员资质信息由机构录入维护，系统据此在派单时**校验提示**；**资质库建成后，对过期资质升级为自动拦截。**
2. **参保人状态由机构维护**：参保人住院、死亡、异地居住等状态，由机构在系统内及时更新，系统据此进行派单拦截和提醒。
3. **与医保平台的对接（三步走，如实说）**：**眼下**，官方 APP 打卡照常，我方侧录入压到"一句话＋必要拍照"，不做重复录入；**过渡**，若当地经办系统支持导出数据，系统提供标准模板做文件级对账，不用手工誊抄（能否导出以当地经办为准，签约前我们协助核实）；**长远**，国家已明文给出"机构自建管理系统并与全国统一的医保信息平台对接"的路径（医保办发〔2024〕21 号第十八条），且国家巡查表中"自建系统并对接"为加分项、值 5 分（医保办发〔2025〕19 号）——系统已按医保部门统一接口规范预留对接口径。**接口规范何时发布由统筹区经办机构定，我们不承诺日期、不表述"已接通"。**
4. **巡查评分**：本系统只做日常留痕与国家文书查阅项的对照，**不预测巡查评分、不承诺合格**；评分判定权在统筹地区医疗保障经办机构。
5. **服务时的身份核验**：国家文书要求"服务前核验参保人有效身份凭证、人证不符不得服务"。**这一步的扫脸/现场核验由官方 APP 承担；我方系统当前只做到"实名制建档＋档案里有这个老人"兜底，"上门的老人是不是档案里那个老人"的核验机制正在与医保/机构确认中。**&#x5BF9;客**不得表述为"我方系统已做身份核验/扫脸"**。
6. **责任边界（出了问题算谁的）**：分三份、写进合同——①**系统该拦没拦住的**（如待遇失效仍放行派单），是我方责任：上文"六条硬锁"将逐条翻译为对客《系统拦截承诺清单》作合同附件，**漏拦即违约**；②**系统看不见的事**（医保侧状态变化、属地口径调整），由机构按本节第 1、2 条承担维护义务，签约时讲透；③**属地化口径**（如拍照分档的当地要求），签约前双方对照《属地核对确认单》逐条核对、签字为界。**赔付上限等具体数字属商务条款，以合同为准。**
---
## 九、这套系统不做什么
| 不做 | 原因 |
| -------------- | ------------------------- |
| 不做打卡 APP，不替代官方 | 云南省级统建，护理员统一用官方 APP，这条路不碰 |
| 不做评估、不做诊疗判断 | 医学判断由机构持证人员做，系统不越界 |
| 不做"全能系统" | 功能越多，一线越不用。能砍就砍，砍到一线愿意用为止 |
---
**云南投云科技有限公司**
（落款日期待确认后填写）

687
docs/refs/20261011-数据字典与接口契约（第4步·V1待确认）.md Normal file
View File

@ -0,0 +1,687 @@
# 投云长护险管理系统 · 数据字典与接口契约
**第 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 步 · 数据字典与接口契约 · 待确认）

2027
docs/requirements/20261011-投云长护险管理系统-P0 PRD（交付开发·V1）.md Normal file
View File

File diff suppressed because it is too large Load Diff

66
docs/requirements/服务机构端-P0范围清单.md Normal file
View File

@ -0,0 +1,66 @@
# 服务机构端 · 本期（P0）范围清单
> 依据：`docs/requirements/20261011-投云长护险管理系统-P0 PRD（交付开发·V1）.md` + `docs/refs/` 数据字典与接口契约。
> 用途：后续拆任务 / 开 openspec change 的**范围基线**。与 PRD 冲突时以 PRD 为准。
## 1. 定位与形态
- 长护险**护理服务机构端**，机构内部运营系统：官方医保 APP 管打卡留痕，本系统管内部运营（计划/派单/台账/质控/对账）。
- **三端共用一套后端**：护理员 APP（安卓）／机构管理后台（Web）／家属公众号（H5 只读）。
- 多租户按 `org_id` 隔离；属地（统筹区）决定服务目录与规则，**走配置不走代码**。
## 2. P0 四块（本期交付）
### ① 待遇档案
- 老人建档：OCR 回填、参保地、参保核验留痕、**等级唯一来源＝评估结论**
- 待遇状态机（**十态**）＋ `elder_status_log` 状态变更留痕
- 老人个人项目库 `elder_svc`（派单带入源）
- 批量导入（老人／护理员／项目配价）
### ② 派单工单
- 服务计划：制定／变更（新建＋指向旧，不原地改）／三方确认／属地项数校验
- 排班派单：日视图、调单 ≤3 步、时间冲突硬拦、批量推荐需人工确认
- 工单状态机（**八态**，含「未遇/扑空」）
- 垫付期台账与「结转」（`is_prepaid`）
### ③ 履约留痕
- 签到/签退：**服务器取时**、定位失败不阻塞、离线可用、`client_md5` 去重
- 项目勾选：默认全勾、`exec_result` 枚举（`done/undo_not_done/undo_refused`）、临时加项
- 拍照分档（必拍/免拍/可拍）＋ 拒拍出路 ＋ 压疮结构化标签
- 异常上报（9 宫格、语音、照片可选）
- 未遇（扑空）专门形态
### ④ 质控闸门
- 全量质控（非抽检）＋ 五类主动推送
- 放行/退回（退回必填原因；**禁止自审自放行 `4001`**）
- 异常联动改计划
## 3. 支撑能力（横切）
- 多属地目录四层 L1–L4（`svc_national/svc_local/svc_mapping/svc_org`）＋ 五条纪律
- RBAC：五角色（`nurse/leader/qc/admin/director`）多值 + 并集判权 + 字段级权限（身份证/手机号/照片）+ 本组界定
- 六条硬锁 L1–L6（L6 本期降级为**提示**，二期改硬拦）
- 统一响应 `{code,message,data,hint}` + 错误码表（`1001`–`4001`）
- 字典（异常分类、拍照分档）、文书导出（合规版式、服务端掩码、访问留痕）
- 离线队列 + 自动补传
## 4. 数据层（23 表）
- **业务主链**：`org` `user` `staff` `elder` `elder_status_log` `elder_svc` `plan` `plan_item` `order` `record` `record_item` `record_photo` `record_abnormal` `qc`
- **目录四层**：`svc_national` `svc_local` `svc_mapping` `svc_org`
- **字典/配置**：`dict_abnormal_type` `dict_photo_tier` `loc_config`
- **预留（建表不写数据）**：`report` `settlement`
## 5. 接口层
6 组 40+：A 待遇档案 / B 服务计划 / C 派单工单 / D 履约留痕 / E 质控闸门 / F 家属端。
## 6. 二期不做（只留字段，本期不实现）
- 结算对账（B5）、人员资质（B6）、院长看板（B0）
- 上报池、医保接口对接、扫脸/身份核验（P-9 待补）
- 多业务线（`biz_line` 恒 `ltci`，只留锚点）
## 7. 验收基线（11 条硬指标）
≤4 击（常态 3 击）、必填自由文本 = 0、离线可用＋自动补传、字号 ≥20pt、首屏即任务、误操作可撤销、调单 ≤3 步、异常主动推送、导出即合规版式、家属端零任务、最小必要留痕。

30
docs/requirements/评估机构端-待设计清单.md Normal file
View File

@ -0,0 +1,30 @@
# 评估机构端 · 待设计清单（后续阶段）
> 状态：**宏观要做，但当前无任何文档定义，是纯缺口**。本文只列「需要设计什么」与「开放问题」，**不含既定需求**。补入正式需求后移出本文。
## 1. 现状（唯一落点）
- 服务机构端 PRD 仅在 `elder` 表记录**外部**评估机构：`assess_org`（评估机构名）、`assess_date`（评估结论日期）、`assess_level`（失能等级）。
- 无评估端产品、门户、接口、角色。
- 政策口径：服务机构端「不做评估、不出评估结论」，评估属评估机构职责（P0 PRD §11.1）。
## 2. 待设计领域（开放）
1. **定位与形态**：评估机构端是独立后台？独立 APP？还是与服务机构端同一平台下的另一类租户？
2. **角色与账号**：评估机构管理员、评估员；与服务机构端 `org`/`user` 的关系（多租户模型如何区分两类机构）。
3. **评估任务生命周期**：受理 → 派评估员 → 上门评估 → 出结论 → 回传。
4. **评估量表与等级判定**：国家/云南失能评估标准、量表结构化、等级计算（`sev_1..3`）。
5. **结论回流**：评估结论如何写入服务机构端 `elder.assess_level`（接口直连 vs 文件导入）。
6. **与医保/官方对接**：评估结论是否来自省平台；接口规范未发布（同服务机构端 R5 预留口径）。
7. **复评/到期重评**：与服务机构端「复评等待期」「待遇到期」状态联动。
## 3. 关键开放问题（待确认）
- 评估机构是否也是「多租户 `org`」？`org.org_type` 是否需要新增评估机构类型？
- 评估结论的**权威来源**：我方系统自产，还是对接官方/医保平台拉取？
- 现有 `elder.assess_*` 三字段是否够用，还是需扩展为独立评估域（如 `assess_task`/`assess_result`）？
## 4. 结构预留建议（本期可做、不改逻辑）
- 保持 `elder.assess_*` 字段现状，未来升级为独立评估域表（任务/结果/量表）。
- 服务机构端 P0 **不阻塞**：评估结论当前以「机构线下确认为准」落 `elder.insur_verify_*` 留痕，字段已留。