2.9 KiB
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 返回时间/项目/照片/异常/定位/垫付标记