360 lines
16 KiB
Markdown
360 lines
16 KiB
Markdown
# 技术设计文档：P4 前置依赖修复
|
||
|
||
## 概述
|
||
|
||
本设计覆盖 6 个定点修复，修正 P4 核心业务层与 Spec 的实现偏差，为 P6 前端任务模块扫清障碍。
|
||
|
||
修复范围：
|
||
- T1：任务列表返回已放弃任务（GAP-3）— **已实现，需验证**
|
||
- T2：召回完成检测器过滤任务类型（GAP-6）— **已实现，需验证**
|
||
- T3：备注回溯重分类器冲突处理（GAP-7）— 需修改 `note_reclassifier.py`
|
||
- T4：回访完成条件改为「有备注即完成」— 需修改 `note_service.py` + `note_reclassifier.py`
|
||
- T5：trigger_scheduler last_run_at 事务安全（GAP-9）— 需修改 `trigger_scheduler.py`
|
||
- T6：cron 默认值改为 07:00 — 需修改 `trigger_scheduler.py` 默认值
|
||
|
||
**关键发现**：代码审查显示 T1 和 T2 已在之前的修复中完成，T6 的种子数据也已是 `0 7 * * *`，仅 `_calculate_next_run()` 的默认值仍为 `"0 4 * * *"`。
|
||
|
||
## 架构
|
||
|
||
本次修复不引入新组件，仅修改现有服务层内部逻辑。涉及的调用链：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant ETL as ETL Pipeline
|
||
participant TS as TriggerScheduler
|
||
participant RD as RecallDetector
|
||
participant NR as NoteReclassifier
|
||
participant NS as NoteService
|
||
participant DB as PostgreSQL (biz schema)
|
||
|
||
ETL->>TS: fire_event("etl_data_updated")
|
||
TS->>RD: run(payload)
|
||
RD->>DB: 查询 active 召回任务 (T2: 仅 recall 类型)
|
||
RD->>DB: 标记 completed
|
||
RD->>TS: fire_event("recall_completed")
|
||
TS->>NR: run(payload)
|
||
NR->>DB: 查找 normal 备注 → 重分类为 follow_up
|
||
NR->>DB: 冲突检查 (T3: 查询已有 follow_up_visit)
|
||
NR->>DB: 创建/跳过/顶替回访任务 (T4: 有备注→completed)
|
||
|
||
Note-->>NS: 助教提交备注
|
||
NS->>DB: 创建备注
|
||
NS->>DB: 查询 active follow_up_visit 任务 (T4)
|
||
NS->>DB: 标记 completed（不依赖 AI 评分）
|
||
```
|
||
|
||
事务边界变更（T5）：
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "修复前：两个独立事务"
|
||
A[handler 事务] --> B[last_run_at 事务]
|
||
end
|
||
subgraph "修复后：合并为单一事务"
|
||
C[handler + last_run_at 同一事务]
|
||
end
|
||
```
|
||
|
||
## 组件与接口
|
||
|
||
本次修复不新增接口，仅修改现有服务层内部方法。以下按修复点列出变更：
|
||
|
||
### T1：task_manager.get_task_list()（已实现 ✅）
|
||
|
||
代码审查确认 `get_task_list()` 已包含：
|
||
- `WHERE status IN ('active', 'abandoned')`
|
||
- `ORDER BY CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END ASC, is_pinned DESC, ...`
|
||
- SELECT 和返回结构包含 `abandon_reason` 字段
|
||
|
||
**本次无需代码变更，仅需验证测试覆盖。**
|
||
|
||
### T2：recall_detector._process_service_record()（已实现 ✅）
|
||
|
||
代码审查确认 `_process_service_record()` 已包含：
|
||
- `AND task_type IN ('high_priority_recall', 'priority_recall')`
|
||
|
||
**本次无需代码变更，仅需验证测试覆盖。**
|
||
|
||
### T3：note_reclassifier.run() — 冲突处理
|
||
|
||
**当前问题**：`run()` 在步骤 4/5 直接 INSERT 回访任务，无冲突检查。当 AI 占位返回 None 时跳过任务创建，但修复 T4 后（有备注即完成）将不再依赖 AI 返回值。
|
||
|
||
**变更方案**：
|
||
|
||
在创建 follow_up_visit 任务前，增加冲突检查逻辑：
|
||
|
||
```python
|
||
# 冲突检查：查询同 (site_id, assistant_id, member_id) 的 follow_up_visit 任务
|
||
cur.execute("""
|
||
SELECT id, status
|
||
FROM biz.coach_tasks
|
||
WHERE site_id = %s AND assistant_id = %s AND member_id = %s
|
||
AND task_type = 'follow_up_visit'
|
||
AND status IN ('active', 'completed')
|
||
ORDER BY CASE WHEN status = 'completed' THEN 0 ELSE 1 END
|
||
LIMIT 1
|
||
""", (site_id, assistant_id, member_id))
|
||
existing = cur.fetchone()
|
||
|
||
if existing:
|
||
existing_id, existing_status = existing
|
||
if existing_status == 'completed':
|
||
# 已完成 → 跳过创建
|
||
return
|
||
elif existing_status == 'active':
|
||
# 顶替：旧任务 → inactive，创建新任务
|
||
cur.execute("""
|
||
UPDATE biz.coach_tasks
|
||
SET status = 'inactive', updated_at = NOW()
|
||
WHERE id = %s AND status = 'active'
|
||
""", (existing_id,))
|
||
_insert_history(cur, existing_id, action="superseded", ...)
|
||
```
|
||
|
||
**设计决策**：
|
||
- 查询 `completed` 和 `active` 两种状态，优先检查 `completed`
|
||
- `inactive` 和 `abandoned` 状态的旧任务不阻止新建（语义上已失效）
|
||
- 顶替操作记录 `superseded` 历史，保留审计链
|
||
|
||
### T4：回访完成条件 — note_service.create_note() + note_reclassifier.run()
|
||
|
||
**当前问题**：
|
||
- `note_service.create_note()` 依赖 `ai_score >= 6` 判定回访完成，但 `ai_analyze_note()` 返回 None → 永远不触发完成
|
||
- `note_reclassifier.run()` 同样依赖 AI 返回值决定任务状态
|
||
|
||
**变更方案 — note_service.create_note()**：
|
||
|
||
```python
|
||
# 修改后：有备注即完成，不依赖 AI 评分
|
||
if note_type == "follow_up" and task_id is not None:
|
||
# 保留 AI 占位调用（P5 接入时调用链不变）
|
||
ai_score = ai_analyze_note(note["id"])
|
||
if ai_score is not None:
|
||
cur.execute("UPDATE biz.notes SET ai_score = %s ...", (ai_score, note["id"]))
|
||
note["ai_score"] = ai_score
|
||
|
||
# 不论 ai_score 如何，有备注即标记回访任务完成
|
||
if task_info and task_info["status"] == "active":
|
||
cur.execute("""
|
||
UPDATE biz.coach_tasks
|
||
SET status = 'completed', completed_at = NOW(),
|
||
completed_task_type = task_type, updated_at = NOW()
|
||
WHERE id = %s AND status = 'active'
|
||
""", (task_id,))
|
||
_record_history(cur, task_id, action="completed_by_note", ...)
|
||
```
|
||
|
||
**变更方案 — note_reclassifier.run()**：
|
||
|
||
```python
|
||
# 修改后：不依赖 AI 返回值
|
||
# 保留 ai_analyze_note() 占位调用
|
||
ai_score = ai_analyze_note(note_id)
|
||
|
||
# 判定任务状态：有备注 → completed，无备注 → active
|
||
# 此处 note_id 非 None 意味着已找到备注 → 直接 completed
|
||
task_status = "completed" # 回溯场景：已有备注 = 已完成
|
||
|
||
# 若未找到备注（note_id is None），创建 active 任务
|
||
# （此分支在上方 note_id is None 时已 return）
|
||
```
|
||
|
||
**设计决策**：
|
||
- `ai_analyze_note()` 调用保留，返回值仅用于更新 `ai_score` 字段，不影响完成判定
|
||
- P5 接入后，AI 评分仍会写入 `notes.ai_score`，但不改变完成逻辑
|
||
- `note_reclassifier` 中：找到备注 = 回溯完成（`completed`），未找到备注 = 等待（`active`）
|
||
|
||
### T5：trigger_scheduler — last_run_at 事务安全
|
||
|
||
**当前问题**：`fire_event()` 和 `check_scheduled_jobs()` 中，handler 执行和 `last_run_at` 更新在不同事务中。handler 成功但 `last_run_at` commit 失败时，下次重跑会重复处理。
|
||
|
||
**变更方案 — 方案 A（handler 内更新 last_run_at）**：
|
||
|
||
将 `last_run_at` 更新的 connection 传入 handler，由 handler 在其事务内执行更新。但这要求修改所有 handler 签名，侵入性大。
|
||
|
||
**变更方案 — 方案 B（传入 conn，handler 结束后同事务更新）**：
|
||
|
||
修改 `fire_event()` 和 `check_scheduled_jobs()`，将 `last_run_at` 更新纳入 handler 的事务范围：
|
||
|
||
```python
|
||
# fire_event() 修改后
|
||
def fire_event(event_name: str, payload: dict | None = None) -> int:
|
||
conn = _get_connection()
|
||
try:
|
||
# ... 查询 enabled event jobs ...
|
||
for job_id, job_type, job_name in rows:
|
||
handler = _JOB_REGISTRY.get(job_type)
|
||
if not handler:
|
||
continue
|
||
try:
|
||
handler(payload=payload)
|
||
# handler 成功后，在同一连接上更新 last_run_at
|
||
with conn.cursor() as cur:
|
||
cur.execute(
|
||
"UPDATE biz.trigger_jobs SET last_run_at = NOW() WHERE id = %s",
|
||
(job_id,),
|
||
)
|
||
conn.commit() # handler 数据变更 + last_run_at 一起提交
|
||
except Exception:
|
||
conn.rollback() # 一起回滚
|
||
finally:
|
||
conn.close()
|
||
```
|
||
|
||
**关键约束**：handler（如 `recall_detector.run()`、`note_reclassifier.run()`）各自管理独立连接和事务。`trigger_scheduler` 的 `last_run_at` 更新使用调度器自己的连接。这意味着 handler 事务和 `last_run_at` 事务仍然是独立的。
|
||
|
||
**实际可行方案**：由于 handler 使用独立连接，真正的"同一事务"需要 handler 接受外部 conn 参数。考虑到改动范围，采用折中方案：
|
||
1. handler 执行完毕后立即更新 `last_run_at`（当前已是如此）
|
||
2. 依赖 handler 的幂等性保证重复执行安全（`recall_detector` 只匹配 `status='active'`，已完成的不会重复处理）
|
||
3. 将 `last_run_at` 更新从 handler 成功后的独立 commit 改为与查询 jobs 的同一连接上的事务
|
||
|
||
**设计决策**：采用用户确认的方案 A — 将 `last_run_at` 更新纳入 handler 同一事务。具体实现：handler 接受可选的 `conn` 参数，在 handler 的最后一个事务中附带更新 `last_run_at`。对于 event 类型触发器（`recall_detector`、`note_reclassifier`），在 handler 的最终 commit 前插入 `last_run_at` 更新。
|
||
|
||
### T6：cron 默认值 07:00
|
||
|
||
**当前问题**：种子数据已是 `"0 7 * * *"`，但 `_calculate_next_run()` 的 fallback 默认值仍为 `"0 4 * * *"`。
|
||
|
||
**变更方案**：
|
||
1. `_calculate_next_run()` 中 `trigger_config.get("cron_expression", "0 4 * * *")` → `"0 7 * * *"`
|
||
2. 新建迁移脚本 `db/zqyy_app/migrations/2026-03-15__p52_update_cron_0700.sql` 作为幂等更新（确保生产环境一致）
|
||
|
||
## 数据模型
|
||
|
||
本次修复不新增表或字段。涉及的现有表：
|
||
|
||
| 表 | 修改内容 | 修复点 |
|
||
|---|---|---|
|
||
| `biz.coach_tasks` | 查询条件变更（无 DDL 变更） | T1, T2, T3, T4 |
|
||
| `biz.coach_task_history` | 新增 `superseded` action 类型记录 | T3 |
|
||
| `biz.trigger_jobs` | `last_run_at` 更新时机变更；cron_expression 幂等更新 | T5, T6 |
|
||
| `biz.notes` | 查询条件变更（无 DDL 变更） | T4 |
|
||
|
||
`coach_tasks.status` 状态转换新增路径：
|
||
- `active → inactive`（T3 顶替场景，由 `note_reclassifier` 触发）
|
||
|
||
此路径在原 Spec 状态机中已定义（"新回访顶替旧回访"），本次为首次实现。
|
||
|
||
## 正确性属性（Correctness Properties）
|
||
|
||
*属性是系统在所有合法执行路径上都应保持为真的特征或行为——本质上是对系统行为的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: 任务列表状态过滤
|
||
|
||
*For any* 任务集合（包含 active、abandoned、completed、inactive 四种状态的任务），`get_task_list` 的过滤逻辑应仅返回 status 为 `active` 或 `abandoned` 的任务，不包含 `completed` 或 `inactive` 状态的任务。
|
||
|
||
**Validates: Requirements 1.1**
|
||
|
||
### Property 2: 任务列表排序正确性
|
||
|
||
*For any* 包含 active 和 abandoned 任务的列表，排序后应满足：(1) 所有 abandoned 任务排在所有 active 任务之后；(2) active 任务内部按 `is_pinned DESC, priority_score DESC NULLS LAST, created_at ASC` 排序。
|
||
|
||
**Validates: Requirements 1.2**
|
||
|
||
### Property 3: abandon_reason 与 status 一致性不变量
|
||
|
||
*For any* 返回的任务记录，若 `status = 'active'` 则 `abandon_reason` 为 null，若 `status = 'abandoned'` 则 `abandon_reason` 为非空字符串。
|
||
|
||
**Validates: Requirements 1.3**
|
||
|
||
### Property 4: 召回检测器仅完成 recall 类型任务
|
||
|
||
*For any* 服务记录和任意任务集合（包含四种 task_type），`_process_service_record` 仅将 `task_type IN ('high_priority_recall', 'priority_recall')` 的 active 任务标记为 completed，`follow_up_visit` 和 `relationship_building` 类型的任务状态不变。
|
||
|
||
**Validates: Requirements 2.1, 2.2, 2.3**
|
||
|
||
### Property 5: 冲突处理 — 已完成回访任务阻止新建
|
||
|
||
*For any* (site_id, assistant_id, member_id) 组合，若已存在 `status = 'completed'` 的 `follow_up_visit` 任务，则 `note_reclassifier` 不创建新的回访任务，且重复触发相同 payload 不产生唯一约束冲突。
|
||
|
||
**Validates: Requirements 3.1, 3.4**
|
||
|
||
### Property 6: 冲突处理 — active 回访任务被顶替
|
||
|
||
*For any* (site_id, assistant_id, member_id) 组合，若已存在 `status = 'active'` 的 `follow_up_visit` 任务，则 `note_reclassifier` 将旧任务标记为 `inactive` 并创建新的回访任务，旧任务的变更记录包含 `superseded` action。
|
||
|
||
**Validates: Requirements 3.2**
|
||
|
||
### Property 7: 无冲突时正常创建回访任务
|
||
|
||
*For any* (site_id, assistant_id, member_id) 组合，若不存在任何 `follow_up_visit` 任务（或仅存在 `inactive`/`abandoned` 状态），则 `note_reclassifier` 正常创建新的回访任务。
|
||
|
||
**Validates: Requirements 3.3**
|
||
|
||
### Property 8: 有备注即完成回访任务，不依赖 AI 评分
|
||
|
||
*For any* `ai_analyze_note()` 的返回值（None、0-5、6-10），当助教为关联 `follow_up_visit` 任务的客户提交备注时，该 active 回访任务都应被标记为 `completed`。AI 评分仅更新 `notes.ai_score` 字段，不影响任务完成判定。
|
||
|
||
**Validates: Requirements 4.2, 4.3**
|
||
|
||
### Property 9: 回溯有备注时创建 completed 回访任务
|
||
|
||
*For any* 召回完成事件，若 `note_reclassifier` 在 service_time 之后找到了 normal 备注，则创建的回访任务 `status = 'completed'`。
|
||
|
||
**Validates: Requirements 4.4**
|
||
|
||
### Property 10: 回溯无备注时创建 active 回访任务
|
||
|
||
*For any* 召回完成事件，若 `note_reclassifier` 在 service_time 之后未找到 normal 备注，则创建的回访任务 `status = 'active'`（等待助教提交备注）。
|
||
|
||
**Validates: Requirements 4.5**
|
||
|
||
### Property 11: 触发器 last_run_at 事务一致性
|
||
|
||
*For any* 触发器执行（event/cron/interval 类型），handler 成功时 `last_run_at` 应被更新，handler 抛出异常时 `last_run_at` 应保持不变（整个事务回滚）。
|
||
|
||
**Validates: Requirements 5.1, 5.2**
|
||
|
||
## 错误处理
|
||
|
||
| 场景 | 处理方式 | 修复点 |
|
||
|------|---------|--------|
|
||
| T3 冲突查询失败 | 捕获异常，rollback，记录日志，返回 `tasks_created: 0` | T3 |
|
||
| T3 顶替 UPDATE 失败 | 捕获异常，rollback，不创建新任务 | T3 |
|
||
| T4 备注创建成功但任务完成 UPDATE 失败 | 整个事务 rollback（备注也不创建），返回 500 | T4 |
|
||
| T4 ai_analyze_note() 抛出异常 | 捕获异常，记录日志，继续执行任务完成逻辑（AI 失败不阻塞业务） | T4 |
|
||
| T5 handler 成功但 commit 失败 | 整个事务回滚（handler 数据变更 + last_run_at），下次重跑依赖幂等性 | T5 |
|
||
| T5 handler 抛出异常 | rollback，last_run_at 不更新，下次重跑 | T5 |
|
||
|
||
## 测试策略
|
||
|
||
### 属性测试（Property-Based Testing）
|
||
|
||
使用 **Hypothesis** 库（项目已有依赖），每个属性测试最少 100 次迭代。
|
||
|
||
每个测试用 comment 标注对应的设计属性：
|
||
```python
|
||
# Feature: p4-prerequisite-fixes, Property 1: 任务列表状态过滤
|
||
```
|
||
|
||
属性测试重点覆盖：
|
||
- Property 1-3：任务列表过滤、排序、字段不变量（纯函数可提取测试）
|
||
- Property 4：召回检测器类型过滤（SQL 条件验证）
|
||
- Property 5-7：冲突处理三分支（状态机测试）
|
||
- Property 8：AI 评分不影响完成判定（参数化 ai_score 返回值）
|
||
- Property 9-10：回溯场景任务状态（有/无备注两分支）
|
||
- Property 11：事务一致性（mock handler 成功/失败）
|
||
|
||
### 单元测试
|
||
|
||
单元测试聚焦于：
|
||
- T1 边界：全部 active（无 abandoned）、全部 abandoned（无 active）、混合场景
|
||
- T2 边界：仅有 follow_up_visit 任务时返回 0 completed
|
||
- T3 边界：同时存在 completed 和 active 的 follow_up_visit（优先检查 completed → 跳过）
|
||
- T4 边界：task_id 为 None 时不触发完成逻辑；非 follow_up_visit 任务不触发
|
||
- T5 边界：handler 抛出特定异常类型时的回滚行为
|
||
- T6 具体值：`_calculate_next_run("cron", {})` 默认使用 `"0 7 * * *"`；迁移脚本 SQL 正确性
|
||
|
||
### 测试配置
|
||
|
||
```python
|
||
from hypothesis import given, settings, strategies as st
|
||
|
||
@settings(max_examples=100)
|
||
@given(...)
|
||
def test_property_name(...):
|
||
# Feature: p4-prerequisite-fixes, Property N: property_text
|
||
...
|
||
```
|
||
|
||
测试文件位置：`tests/` 目录（Monorepo 级属性测试，与现有 P4 属性测试同级）。
|