2.7 KiB
Context
C2 已有 order 八态、plan/plan_item、staff、MinIO StorageService。C3 新增履约留痕域，纯新增、不侵入脚手架。设计背景见 docs/superpowers/specs/2026-10-15-服务机构端-C3履约留痕-design.md。
Goals / Non-Goals
Goals: ho_record/ho_record_item/ho_record_photo/ho_record_abnormal 四表 + 录入 API + 垫付台账与结转 + admin 工单留痕/异常列表 + settlement/report 预留空表。
Non-Goals: 质控放行/退回（qc 表 + 4001，C4）、补正（C4）、离线队列+自动补传（APP 期）、家属端、结算对账（二期）。
Decisions
- 表命名：
ho_record/ho_record_item/ho_record_photo/ho_record_abnormal（前缀 ho，禁用 checkin/clockin/punch）；settlement/report无前缀预留。 - 模块划分：
src/record/（record + item + photo + 签到签退离线 + 垫付结转）+src/abnormal/。 - record 生命周期：serving（签到）→ submitted（签退）；returned/passed 留 C4。
- 服务器取时：checkin_time/checkout_time/duration_min 系统取，接口不接受。
- is_prepaid：record 创建时 elder.treat_status = waiting_period → is_prepaid=1、billable=0。
- 结转：复制垫付 record → 正式 record（is_prepaid=0 + source_prepaid_of），原记录保留只读、不改原始时间戳。
- 扑空：工单转 not_met + 写 record_abnormal（到访/定位/原因），不产生 record。
- exec_result：done/undo_not_done/undo_refused。
- 照片：MinIO 复用，≤500KB，visible_to_family 恒 0，keep_until ≥7 天。
- client_md5 去重：离线补传幂等。
- 主键：UUID v7 VarChar(36)（循代码库，PRD 的 varchar(32) 归一）。
数据模型
通用字段 + UUID v7 + tenantCode + 软删（仅 record；子表循 ElderStatusLog/PlanItem 先例：带 tenant_code、无 deleted_at、不入 SOFT_DELETE）。6 表字段见 docs/superpowers 设计文档；record_abnormal 增加 order_id（扑空指向工单，PRD 最小字段未含）。
接口
record：checkin / item/save / photo/upload / checkout / offline/sync / detail / list / prepaid-list / prepaid/carryover。abnormal：report / list。权限码 record./abnormal.；错误码域 45；规则号 3001/3002/3003/3004 写 message。
Risks / Trade-offs
- 离线幂等 → client_md5 唯一约束 + upsert。
- 扑空 vs 逾期未做 → 有到访证据 vs 无记录。
- 结转复制 vs 改标记 → 复制（两套并存合规）。
- 必拍清单 source of truth → order.item_list 快照落 record_item.photo_required。
Migration Plan
新增 6 表（utf8mb4_general_ci 手改）。迁移链已损坏：用 migrate diff --from-schema-datasource + 手工迁移目录 + migrate deploy。