# 变更审计记录：Fix-13 回滚手动完成 + 广义召回完成机制

| 字段 | 值 |
|------|-----|
| 日期 | 2026-04-08 15:08:50 |

## 操作摘要

Fix-13 看板审计修复计划，包含两部分改动。

**第一部分：回滚手动完成路径。** 用户确认回访任务应通过提交备注自动完成（note_service 中 completed_by_note 逻辑），不需要手动完成按钮。删除 `POST /{task_id}/complete` 接口、`ManualCompleteRequest` 模型及 `manual_complete_task()` 函数。`completion_type` 字段保留，recall_detector 自动完成仍写 `'auto'`。

**第二部分：广义召回完成机制。** 原 recall_detector 只检测有 active 任务的客户到店。需求要求所有 MAIN 关系对的关联客户到店都算一次广义召回，都要分配回访任务。重写 recall_detector，新增 `biz.recall_events` 表记录召回事件（ON CONFLICT 按天去重），看板召回数改从该表统计。

## 变更文件

### 修改

| 文件 | 改动要点 |
|------|----------|
| `apps/backend/app/routers/xcx_tasks.py` | 删除 `POST /{task_id}/complete` 接口、`ManualCompleteRequest` 模型、pydantic `BaseModel, Field` 导入 |
| `apps/backend/app/services/task_manager.py` | 删除 `manual_complete_task()` 函数（约 47 行） |
| `apps/backend/app/services/recall_detector.py` | 重写。扫描范围从"有 active 任务"扩大为"所有 os_label='MAIN' 的关联客户"。新增写 recall_events 表（ON CONFLICT 按天去重）。无 active 任务的客户到店也生成 follow_up_visit（48h 过期） |
| `apps/backend/app/services/board_service.py` | `_query_coach_tasks()` 召回数改从 `recall_events` 统计（天然去重），回访数保持从 `coach_tasks` 统计 |
| `db/zqyy_app/schemas/biz.sql` | 新增 `recall_events` 表定义 |
| `docs/database/ddl/zqyy_app__biz.sql` | 同步源 DDL |

## 改动注解

### `apps/backend/app/services/recall_detector.py`（高风险）
完全重写。核心变化：
- 扫描范围：从"有 active 任务的客户"扩大为"所有 os_label='MAIN' 的关联客户"
- 新增逻辑：每次检测到客户到店，写入 `biz.recall_events`（按天去重）
- 新增逻辑：无 active 任务的客户到店也生成 `follow_up_visit` 类型回访任务（48h 过期）
- 每个 site_id 两次 `_fdw_context` 调用

### `apps/backend/app/services/board_service.py`（高风险）
`_query_coach_tasks()` 中召回数数据源从 coach_tasks 改为 recall_events 表，天然去重不重复叠加。回访数统计逻辑不变。

### `apps/backend/app/routers/xcx_tasks.py`（高风险）
删除手动完成接口及相关模型。路由数从 8 个减少到 7 个。

### `apps/backend/app/services/task_manager.py`（高风险）
删除 `manual_complete_task()` 函数（约 47 行），其余逻辑不变。

### `db/zqyy_app/schemas/biz.sql`（高风险）
新增 `recall_events` 表，详见数据库变更节。

### `docs/database/ddl/zqyy_app__biz.sql`
同步源 DDL，无额外逻辑。

## 数据库变更

### 新增

| 对象 | 类型 | 说明 |
|------|------|------|
| `biz.recall_events` | 表 | 召回事件记录（8 字段：id, site_id, assistant_id, member_id, pay_time, task_id, task_type, created_at） |
| `biz.recall_events_id_seq` | 序列 | recall_events 主键序列 |
| `recall_events_pkey` | 主键约束 | PK on id |
| `recall_events_task_id_fkey` | 外键约束 | FK → coach_tasks(id) |
| `idx_recall_events_site_assistant_member_day` | 唯一索引 | (site_id, assistant_id, member_id, date(pay_time))，按天去重 |
| `idx_recall_events_assistant_pay` | 索引 | (assistant_id, pay_time)，查询优化 |

## 风险与回滚

### 风险

| 级别 | 描述 |
|------|------|
| 高 | 首次运行 recall_detector 会为所有历史有结算的 MAIN 关系对写 recall_events + 生成回访任务，数据量可能很大 |
| 中 | ETL 连接开销，每个 site_id 两次 _fdw_context |
| 低 | coach_tasks 唯一约束冲突（已通过先关闭旧回访再新建避免） |

### 回滚策略

数据库回滚（逆序执行）：

```sql
DROP INDEX IF EXISTS biz.idx_recall_events_assistant_pay;
DROP INDEX IF EXISTS biz.idx_recall_events_site_assistant_member_day;
ALTER TABLE biz.recall_events DROP CONSTRAINT IF EXISTS recall_events_task_id_fkey;
ALTER TABLE biz.recall_events DROP CONSTRAINT IF EXISTS recall_events_pkey;
DROP TABLE IF EXISTS biz.recall_events;
DROP SEQUENCE IF EXISTS biz.recall_events_id_seq;
```

后端代码回退：`git checkout HEAD~1 -- apps/backend/app/services/recall_detector.py apps/backend/app/services/board_service.py apps/backend/app/routers/xcx_tasks.py apps/backend/app/services/task_manager.py`

## 验证

| 验证项 | 结果 |
|--------|------|
| 模块导入 `recall_detector` | ✅ 通过 |
| 路由验证 `xcx_tasks` 7 个路由，无 `/complete` | ✅ 通过 |
| 数据库表结构（recall_events 8 字段） | ✅ 通过 |
| 唯一索引（按天去重） | ✅ 通过 |
| FK 约束（→ coach_tasks） | ✅ 通过 |
| 后端 pytest | ⚠️ 无法运行（dashscope 依赖未安装，非本次改动引入） |

## 合规检查

| 检查项 | 结果 |
|--------|------|
| DDL 文档同步 `docs/database/ddl/zqyy_app__biz.sql` | ✅ 已同步 |
| RLS 双 Schema 规则 | ⚠️ recall_events 为业务库表，非 ETL 层，不适用 |
| API 文档 `apps/backend/docs/API-REFERENCE.md` | ⚠️ 待检查是否存在 |
| 后端 README `apps/backend/README.md` | ⚠️ 待检查是否存在 |
| 审计记录 | ✅ 本文件 |