架构决策：FollowUpTask 回访状态机与再次预约归因

日期：2026-08-02
状态：Accepted / Code Complete
本体：entity:follow_up_task、rule:BR-FU-001、rule:BR-FU-002

1. 决策

ReportLead 继续保存宠主同意、来源报告、建议日期与退订凭证等留资事实；门店员工的领取、联系、改期、关闭和再次预约改由独立 FollowUpTask 承载。不得继续用 ReportLead.remind_status 同时表达同意事实和多人协作状态。

留资成功后，同一 sourceLeadId 至多存在一个开放任务。重复提交复用开放任务并同步建议日期；上一轮已终结后再次提交，创建新的任务轮次。历史迁移只为 remind_status=pending 的线索回填任务，不推测 sent/canceled/unsubscribed 的真实处理结果。

ReportLead.remind_status 暂保留为兼容投影：新建或改期为 pending，无意向/无效联系方式为 canceled，真实再次预约为 sent，退订为 unsubscribed。Admin 回访工作流与经营统计不再以该兼容字段为事实源。

2. 状态机

pending --领取--> in_progress
in_progress --未接通/稍后联系--> pending（attempt_count + 1，更新 due_date）
in_progress --暂无意向/联系方式无效--> completed（attempt_count + 1）
in_progress --真实预约创建成功--> completed / rebooked（attempt_count + 1）
pending|in_progress --宠主退订--> canceled / unsubscribed（不增加员工联系次数）

pending 不允许有领取人；in_progress 必须有领取人。
只有领取该任务的当前员工才能改期、关闭或发起再次预约。
两名员工并发领取时通过悲观锁和 @Version 防止静默覆盖；他人已领取返回 409。
completed/canceled 为终态，不回退。跨店任务按不存在返回 404。
no_answer/follow_later 仅是非终态联系结果；rebooked/not_interested/invalid_contact/unsubscribed 仅是终态结果。

3. 真实再次预约归因

rebooked 不是员工可手工选择的关闭结果。只有 POST /api/appointment/create 在同一事务中满足下列条件，才能写入：

followUpTaskId 属于当前门店，处于 in_progress 且由当前员工领取；
任务的 canonical StoreCustomer 与本次代客预约解析出的客户一致；
预约通过未来时间、服务时长和每个半小时桶容量校验并真实保存；
保存后任务写 rebooked_appointment_id，同时落 follow_up_completed 与 rebook_created 事实。

无号源、客户不匹配、状态冲突或预约保存失败时，整笔事务回滚，任务保持处理中。漏斗中的“回访后再次预约”只统计 rebook_created，不从手机号相同或后续页面点击推断。

4. 权限、隐私与审计

GET/POST /api/admin/follow-up-tasks/** 仅本店 boss/staff，storeId 和操作人均从 session 派生。
同店已认证员工为了实际电话联系可在开放任务中看到完整手机号；终态任务只返回脱敏手机号。工作台、客户时间线、BusinessEvent 和 AuditLog 只保留脱敏或低敏字段。
BusinessEvent metadata 仅允许 dueDate/attemptOutcome/outcome/attemptCount/bookingOrigin 等白名单标量，不存手机号、备注、微信标识、token、IP 或请求体。
领取、改期、关闭和真实再次预约均写不可变低敏 AuditLog；退订由公开凭证触发，不伪装成员工联系次数或操作人。

5. 迁移与验收

迁移：backend/db/migrations/20260802_create_follow_up_task.sql，固定在 StoreCustomer 时间线迁移后第八个执行。末尾五项验证必须为 0：

待处理历史线索无开放任务；
任务客户归属或 canonical 范围无效；
状态、结果、领取人、联系回执或真实预约引用不一致；
同一线索存在多个开放任务；
任务缺少创建事实。

生产只读预检同步检查上述不变量，并额外要求 rebooked_appointment_id 指向同店、未删除的真实预约以及对应 rebook_created 事件。

自动化验收覆盖：历史回填、状态机、并发领取冲突、跨店 404、非领取人拒绝、退订取消、真实预约成功闭环、容量失败不闭环、客户时间线低敏投影、Admin 控制器权限与 production build。

4.3 KiB Raw Blame History Unescape Escape