## 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

1. **表命名**：`ho_record`/`ho_record_item`/`ho_record_photo`/`ho_record_abnormal`（前缀 ho，禁用 checkin/clockin/punch）；`settlement`/`report` 无前缀预留。
2. **模块划分**：`src/record/`（record + item + photo + 签到签退离线 + 垫付结转）+ `src/abnormal/`。
3. **record 生命周期**：serving（签到）→ submitted（签退）；returned/passed 留 C4。
4. **服务器取时**：checkin_time/checkout_time/duration_min 系统取，接口不接受。
5. **is_prepaid**：record 创建时 elder.treat_status = waiting_period → is_prepaid=1、billable=0。
6. **结转**：复制垫付 record → 正式 record（is_prepaid=0 + source_prepaid_of），原记录保留只读、不改原始时间戳。
7. **扑空**：工单转 not_met + 写 record_abnormal（到访/定位/原因），不产生 record。
8. **exec_result**：done/undo_not_done/undo_refused。
9. **照片**：MinIO 复用，≤500KB，visible_to_family 恒 0，keep_until ≥7 天。
10. **client_md5 去重**：离线补传幂等。
11. **主键**：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`。