1

docs/prd/specs/P5.2-p4-prerequisite-fixes.md

@@ -0,0 +1,145 @@
+# P5.2：P4 前置依赖修复 — p4-prerequisite-fixes
+
+> 优先级：P5.2（P6 前置，必须在 P6 开发前完成）
+> 预估工作量：小（6 个定点修复，无新表/新接口）
+> 依赖：P4 已完成
+> 来源：P4 Spec vs 实现差异分析（`docs/reports/P4-spec-vs-implementation-gap-analysis.md`）
+
+---
+
+## 背景
+
+P4 核心业务层已实现并通过属性测试，但对比最新 Spec 发现 6 处实现偏差。
+这些偏差会影响 P6（前端任务模块）的正常开发，必须前置修复。
+
+参考文档：
+- 差异分析：`docs/reports/P4-spec-vs-implementation-gap-analysis.md`
+- 生命周期全景：`docs/reports/P4-task-lifecycle-panorama.md`
+
+---
+
+## 需求（Requirements）
+
+### 验收标准
+
+- AC1：任务列表 API 返回 active + abandoned 两种状态，abandoned 排在最后且包含 abandon_reason
+- AC2：召回完成检测器仅完成 high_priority_recall / priority_recall 两种任务类型
+- AC3：备注回溯重分类器创建回访任务时，已有 active 回访 → 顶替（旧→无效），已完成 → 跳过
+- AC4：回访任务完成条件为「助教为该客户提交备注」，不依赖 AI 评分
+- AC5：trigger_scheduler 的 last_run_at 更新具备事务安全性
+- AC6：任务生成器 cron 时间为 07:00
+
+---
+
+## 任务清单
+
+### T1：任务列表返回已放弃任务（GAP-3）
+
+文件：`apps/backend/app/services/task_manager.py` → `get_task_list()`
+
+修改内容：
+1. SQL WHERE 条件：`status = 'active'` → `status IN ('active', 'abandoned')`
+2. SQL ORDER BY 增加：`CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END` 排在 `is_pinned DESC` 之前
+3. SELECT 增加 `abandon_reason` 字段
+4. 返回结构增加 `abandon_reason` 字段
+
+验证：
+- 有 abandoned 任务时，列表末尾出现灰化任务且包含 abandon_reason
+- 有 active + pinned 任务时，排序为：置顶 → 一般 → 已放弃
+
+---
+
+### T2：召回完成检测器过滤任务类型（GAP-6）
+
+文件：`apps/backend/app/services/recall_detector.py` → `_process_service_record()`
+
+修改内容：
+1. SQL 增加 `AND task_type IN ('high_priority_recall', 'priority_recall')`
+
+验证：
+- follow_up_visit 和 relationship_building 类型的 active 任务不会被召回检测器完成
+- high_priority_recall 和 priority_recall 正常完成
+
+---
+
+### T3：备注回溯重分类器冲突处理（GAP-7）
+
+文件：`apps/backend/app/services/note_reclassifier.py` → `run()`
+
+修改内容：
+1. 创建回访任务前，先查询是否已有同 (site_id, assistant_id, member_id) 的 follow_up_visit 任务
+2. 已有 completed 的回访任务 → 跳过创建（回访完成 +1 的语义已满足）
+3. 已有 active 的回访任务 → 旧任务标记 inactive，创建新任务
+4. 不存在 → 正常创建
+
+验证：
+- 重复触发不会产生唯一约束冲突
+- 已完成的回访任务不会被覆盖
+
+---
+
+### T4：回访完成条件改为「有备注即完成」（新-1）
+
+文件：
+- `apps/backend/app/services/note_service.py` → `create_note()`
+- `apps/backend/app/services/note_reclassifier.py` → `run()`
+
+修改内容：
+1. `note_service.create_note()` 增加逻辑：创建备注后，通过 user_assistant_binding 查 assistant_id，
+   再查该 (site_id, assistant_id, member_id) 是否有 active 的 follow_up_visit 任务，有则标记 completed
+2. `note_reclassifier.py`：去掉 AI 评分判定逻辑，有备注 → 回访任务直接标记 completed；
+   无备注 → 创建 active 回访任务（等待备注）
+
+验证：
+- 助教提交备注后，对应客户的 active 回访任务自动完成
+- 不依赖 AI 评分返回值
+
+---
+
+### T5：trigger_scheduler last_run_at 事务安全（GAP-9）
+
+文件：`apps/backend/app/services/trigger_scheduler.py`
+
+修改内容：
+1. `fire_event()` 和 `check_scheduled_jobs()` 中，将 last_run_at 更新纳入 handler 的事务范围，
+   或改为执行前更新（at-most-once 语义，配合 handler 幂等性）
+
+验证：
+- handler 成功但 commit 失败的场景不会导致重复处理（或重复处理是幂等的）
+
+---
+
+### T6：任务生成器 cron 改为 07:00（新-2）
+
+文件：
+- `db/zqyy_app/migrations/2026-03-15__p52_update_cron_0700.sql`（新建迁移脚本）
+- `apps/backend/app/services/trigger_scheduler.py` → `_calculate_next_run()` 默认值
+
+修改内容：
+1. 新建迁移脚本：`UPDATE biz.trigger_jobs SET trigger_config = '{"cron_expression": "0 7 * * *"}' WHERE job_name = 'task_generator'`
+2. `_calculate_next_run()` 中 cron 默认值从 `"0 4 * * *"` 改为 `"0 7 * * *"`
+
+验证：
+- trigger_jobs 表中 task_generator 的 cron_expression 为 `0 7 * * *`
+- 下次运行时间计算正确
+
+---
+
+## 执行顺序
+
+```
+批次 1（无依赖，可并行）：T1、T2、T6
+批次 2（依赖 T2 确认）：T3、T4
+批次 3（依赖 T3/T4 验证）：T5
+```
+
+---
+
+## 不在本 SPEC 范围
+
+| 项目 | 归属 | 说明 |
+|------|------|------|
+| GAP-5 备注分页 | P6-T6 | 已写入 P6 Spec |
+| GAP-8 问问 AI | P5 | P5 AI 集成层已覆盖 |
+| GAP-2 cancel_abandon 重置 is_pinned | 已修复 | 2026-03-14 |
+| GAP-4 completed_task_type 快照 | 无差异 | 实现正确 |