# shared/data-model Specification

## Purpose
定义服务机构端 C0 的数据模型字段字典——机构/人员/服务目录四层/字典/属地配置的实体、字段、枚举与多租户键约定，作为前后端字段命名的唯一锚点。

## Requirements

### Requirement: 多租户键约定
服务机构端所有业务实体 MUST 携带 `tenant_code` 字段作为多租户隔离键，其值为机构唯一标识（= 脚手架租户 code）。

#### Scenario: 跨机构隔离
- **WHEN** 业务表写入一条记录
- **THEN** 该记录 MUST 带 `tenant_code`，且读操作按当前租户自动过滤，不返回其他租户数据

### Requirement: 机构实体 org
`org` 表 MUST 存在，主键为机构 code（与 `tenant_code` 同值），承载机构业务字段：org_name、org_type、credit_code、loc_code、loc_name、svc_source、license_no、address、contact_name、contact_phone、bed_count、sign_date。

#### Scenario: 机构唯一标识
- **WHEN** 创建一个机构
- **THEN** 其 code 与脚手架的 tenant code 一致且全局唯一

### Requirement: 人员实体 staff
`staff` 表 MUST 存在，承载人员/资质字段（name、id_card_no、phone、job_type、work_type、employ_status、cert_type/cert_no/cert_level/cert_expire/cert_status、group_leader_id），并 MUST 带 `user_id` 关联脚手架 `user.id`（可空、1:1）。

#### Scenario: 账号关联人员
- **WHEN** 护理员登录并定位本人 staff
- **THEN** 通过 `staff.user_id = user.id` 唯一定位到一条 staff 记录

### Requirement: 软删约定
服务机构端业务实体 MUST 采用脚手架 `deleted_at`（时间戳）软删，不物理删除。

#### Scenario: 软删保留
- **WHEN** 删除一条业务记录
- **THEN** 记录置 `deleted_at`，读操作默认排除，物理数据保留

### Requirement: 主键约定
业务实体主键 MUST 采用脚手架 UUID v7；业务码（机构 code、项目代码）MUST 建唯一索引。

#### Scenario: 主键唯一
- **WHEN** 新增业务记录
- **THEN** 生成 UUID v7 主键，业务码唯一索引防重复

### Requirement: 目录四层实体
`svc_national`(L1)、`svc_local`(L2)、`svc_mapping`(L3)、`svc_org`(L4) 四表 MUST 存在，字段按 PRD §7.2 定义；L3 映射表不提供机构侧接口。

#### Scenario: 目录分层
- **WHEN** 加载某机构属地目录
- **THEN** 按 L1/L2 取目录、L4 取机构勾选与配价、L3 仅内部映射

### Requirement: 字典与属地配置实体
`dict_abnormal_type`、`dict_photo_tier`、`loc_config` 三表 MUST 存在，承载异常分类、拍照分档、属地目录来源与项数规则配置。

#### Scenario: 属地配置驱动目录
- **WHEN** 新增一个州市
- **THEN** 插入一条 `loc_config` + 一批 `svc_local` 即生效，无需改代码

### Requirement: 老人档案实体 elder
`elder` 表 MUST 存在，承载老人档案字段（tenant_code、loc_code、name、gender、birth_date、id_card_no、insur_no/type、assess_level/care_level、assess_date/org、assess_evidence_file、benefit_start/end、treat_status、hosp_start/end、note 等），主键 UUID v7，`tenant_code` 多租户隔离，`tenant_code + id_card_no` 唯一。

#### Scenario: 老人档案归属机构
- **WHEN** 创建一条老人档案
- **THEN** 带 tenant_code，读操作按当前租户自动过滤

#### Scenario: 同机构身份证唯一
- **WHEN** 同机构重复录入同一 id_card_no
- **THEN** 命中唯一约束，提示「已有档案」

### Requirement: 待遇状态日志实体 elder_status_log
`elder_status_log` 表 MUST 存在；每次待遇状态变更 MUST 写一条日志，含 from_status/to_status/change_reason(必填)/operator_id/changed_at。

#### Scenario: 状态变更留痕
- **WHEN** 变更老人待遇状态
- **THEN** 写入一条 elder_status_log，change_reason 非空

### Requirement: 服务计划实体 svc_plan / svc_plan_item
`svc_plan` 表 MUST 存在（plan_period_start/end、care_level、care_mode、item_count、item_count_rule、plan_status、change_from_plan_id 等）；`svc_plan_item` MUST 存在（svc_id 引 L4、svc_name_snapshot、freq_type/value、duration_min、photo_tier、caution_note 等）。计划变更 MUST 新建 + change_from_plan_id 指向旧计划，不原地改。

#### Scenario: 计划变更留旧版
- **WHEN** 变更某老人的服务计划
- **THEN** 生成新计划并指向旧计划，旧计划保留

### Requirement: 工单实体 svc_order
`svc_order` 表 MUST 存在（plan_id、service_date、time_slot_start/end、assignee_id、order_status、item_list(json)、reschedule_log(json)、not_met_reason/at 等）。

#### Scenario: 工单关联计划
- **WHEN** 生成一张工单
- **THEN** 工单带 plan_id，item_list 为计划项目快照

### Requirement: 老人个人项目库实体 ltc_elder_svc
`ltc_elder_svc` 表 MUST 存在（elder_id、svc_id 引 L4、svc_name_snapshot、care_mode、is_active），一人一份；svc_id 必须落在本机构 L4。

#### Scenario: 项目只能从 L4 选
- **WHEN** 保存个人项目库
- **THEN** svc_id 必须在本机构 svc_org 内，否则拒绝

### Requirement: 履约留痕实体 ho_record
`ho_record` 表 MUST 存在（order_id、elder_id、assignee_id、checkin_time、checkout_time、duration_min、checkin_lat/lng、locate_status、record_status、voice_file、offline_flag、client_md5、submit_time、actual_duration_tier、biz_line、is_prepaid、billable、source_prepaid_of）。`record_status` MUST ∈ {serving, submitted}（returned/passed 留 C4）。签到签退时间与时长由系统生成，不接受客户端传入。

#### Scenario: 留痕关联有效工单
- **WHEN** 创建一条留痕
- **THEN** 必须带 order_id 且工单有效（L3 硬锁）

### Requirement: 留痕项目明细 ho_record_item
`ho_record_item` 表 MUST 存在（record_id、svc_id 引 L4、svc_name_snapshot、exec_result、undo_reason、extra_flag、photo_required、is_refused_photo、refuse_reason）。`exec_result` MUST ∈ {done, undo_not_done, undo_refused}。

#### Scenario: 项目只能从 L4 选
- **WHEN** 保存留痕项目
- **THEN** svc_id 必须在本机构 svc_org 内，否则拒绝

### Requirement: 留痕照片 ho_record_photo
`ho_record_photo` 表 MUST 存在（record_id、svc_id、file_path、file_size、visible_to_family、upload_batch、keep_until）。`visible_to_family` 本期恒 0；文件压缩后 ≤500KB。

#### Scenario: 家属端不可见
- **WHEN** 上传留痕照片
- **THEN** visible_to_family = 0

### Requirement: 异常上报 ho_record_abnormal
`ho_record_abnormal` 表 MUST 存在（record_id 可空、order_id 可空、elder_id、reporter_id、abnormal_type、abnormal_desc、voice_file、has_photo、notify_status、handle_status、handle_result、link_plan_change）。`abnormal_type` MUST 必填，其余可选。

#### Scenario: 扑空无留痕
- **WHEN** 登记未遇（扑空）
- **THEN** record_id 为空、order_id 指向工单、abnormal_type 为扑空分类

### Requirement: 二期预留表 settlement / report
`settlement`/`report` 表 MUST 建空表不写业务数据（settlement 含 amount_fund/amount_self_pay 个人自付拆分字段）。

#### Scenario: 预留表空建
- **WHEN** 迁移完成后
- **THEN** settlement/report 表存在且无业务数据