# backend/record Specification

## Purpose
定义服务机构端履约留痕域的后端行为——签到/签退/项目执行/照片/离线补传/垫付台账与结转。

## Requirements

### Requirement: 签到
`POST /record/checkin` MUST 校验 L3（order 存在、order_status ∈ {assigned, serving}、elder/assignee 匹配）；checkin_time 服务器取时（不接受客户端传入）；定位失败 3002 不阻塞（locate_status=failed/denied）；建 record（serving）并返回 record_id。

#### Scenario: 服务器取时
- **WHEN** 签到
- **THEN** checkin_time 由服务端生成，客户端传入被忽略

#### Scenario: 定位失败不阻塞
- **WHEN** 签到但定位失败
- **THEN** 标记 locate_status=failed，照常提交（3002）

### Requirement: 签退提交
`POST /record/checkout` MUST 校验必拍未拍（3001 硬拒 + 拒拍出路 is_refused_photo=1）；checkout_time/duration_min 服务器取时；record_status 转 submitted；waiting_period 老人 is_prepaid=1、billable=0（3004 仅标记）。

#### Scenario: 必拍未拍硬拒
- **WHEN** 必拍项未拍照且未走拒拍出路
- **THEN** 返回 3001 拒绝签退

#### Scenario: 垫付标记
- **WHEN** 等待期老人签退
- **THEN** record.is_prepaid=1、billable=0，不计费

### Requirement: 项目执行
`POST /record/item/save` MUST exec_result ∈ {done, undo_not_done, undo_refused}；svc_id 落本机构 L4；photo_required 快照自 order.item_list。

#### Scenario: 措辞纪律
- **WHEN** 项目未执行
- **THEN** exec_result 用 undo_not_done（非 not_done）

### Requirement: 照片上传
`POST /record/photo/upload` MUST 校验文件 ≤500KB；visible_to_family=0；keep_until 补传后 ≥7 天。

#### Scenario: 超限拒绝
- **WHEN** 上传超过 500KB 的照片
- **THEN** 拒绝并提示压缩

### Requirement: 离线补传
`POST /record/offline/sync` MUST 按 client_md5 幂等去重（重复提交返回已存在，静默不弹窗）。

#### Scenario: 去重
- **WHEN** 同 client_md5 重复补传
- **THEN** 幂等返回，不重复落库

### Requirement: 垫付台账与结转
`waiting_period` 老人留痕 MUST `is_prepaid=1`、`billable=0`；`POST /record/prepaid/carryover` MUST 勾选若干 is_prepaid=1 记录 → 生成对应正式记录（复制、is_prepaid=0、source_prepaid_of=原 id），原记录保留只读、不改原始时间戳（签到时间/定位/照片仍是原始值）。

#### Scenario: 结转不改原始时间戳
- **WHEN** 结转垫付记录
- **THEN** 新记录签到时间/定位/照片仍为原始值，仅标记来源

### Requirement: 留痕列表与详情
`GET /record/list`（admin B3，按 elder/assignee/日期/状态筛选）与 `GET /record/detail` MUST 返回留痕列表/详情（含项目、照片、异常、定位、垫付标记）。

#### Scenario: 质控查看留痕
- **WHEN** 质控员查询留痕列表与详情
- **THEN** 返回时间/项目/照片/异常/定位/垫付标记