# 变更审计记录：任务引擎改造 — 参数调优 + 客户级升级/转移 + 任务统计写入

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-31 23:31:55 |
| Prompt-ID | P20260331-233155 |
| Session-ID | b743f2ab |
| Session 路径 | docs/audit/session_logs/2026-03/31/07_7dabc6f0_231307 |

## 操作摘要

在 task_generator.py 中新增 `_update_task_stats()` 函数，在每次任务生成完成后统计当前门店的任务数据并写入汇总表。统计分两层：B 层按助教+月份汇总写入 `biz.dws_assistant_task_monthly`（月度统计），C 层按助教+客户写入 `dws.dws_member_assistant_relation_index` 的 6 个新增历史总计字段。同时创建了对应的迁移 SQL。

本次变更是 P19 任务引擎改造系列的一部分，此前已完成参数调优、`_run_for_site()` 客户级升级/转移重写、recall_detector 直接生成回访任务、relation_index OS 方案重写、as_of_date 回测支持等改动。

## 风险评估

- `task_generator.py` 核心逻辑改动：**高**（`_run_for_site()` 完全重写，从任务级别升级改为客户级别升级/转移；参数阈值多处调整）
- 新建 `dws_assistant_task_monthly` 表：**中**（新表，不影响现有数据，但统计逻辑需验证准确性）
- `dws_member_assistant_relation_index` 新增字段：**中**（ALTER TABLE ADD COLUMN，默认值 0，不影响现有查询）
- DDL 基线已合并：✅

## 数据库变更

### 新建表
- `biz.dws_assistant_task_monthly` — 助教任务月度统计汇总（site_id + assistant_id + stat_month 唯一约束）
  - 字段：recall_created, follow_up_created, relationship_created, total_created, recall_completed, follow_up_completed, total_completed, abandoned_count, transferred_count

### 新增字段
- `dws.dws_member_assistant_relation_index` 新增 6 个统计字段：
  - `recall_created_total` / `recall_completed_total` — 历史累计召回任务创建/完成数
  - `follow_up_created_total` / `follow_up_completed_total` — 历史累计回访任务创建/完成数
  - `total_created` / `total_completed` — 历史累计任务创建/完成总数

### 迁移脚本
- `db/zqyy_app/migrations/2026-03-31__task_stats_tables.sql` — 新建月度汇总表
- `db/etl_feiqiu/migrations/2026-03-31__relation_index_task_stats.sql` — 关系指数表新增字段

### DDL 基线
- `docs/database/ddl/zqyy_app__biz.sql` — ✅ 已合并

### ⚠️ 迁移执行状态
- 待验证：需在测试库执行迁移后确认表结构


## 本次对话文件变更

### 新增文件
- `db/etl_feiqiu/migrations/2026-03-31__relation_index_task_stats.sql` — 关系指数表新增 6 个历史总计统计字段
- `db/zqyy_app/migrations/2026-03-31__task_stats_tables.sql` — 新建 `biz.dws_assistant_task_monthly` 月度汇总表
- `docs/audit/prompt_logs/prompt_log_20260331_233155.md` — Prompt 日志

### 删除文件
- `docs/audit/session_logs/2026-03/31/07_7dabc6f0_231307/main_01_0f0a9f5b.md` — Session 日志重建（被 b743f2ab 替代）

### 修改文件
- `apps/backend/app/services/task_generator.py` — 新增 `_update_task_stats()` 统计写入函数（月度汇总 + 历史总计）

## 改动注解

### `apps/backend/app/services/task_generator.py`
- 变更类型：修改
- 原始原因：用户要求在 task_generator.run() 末尾统计当前门店的任务数据并写入。B 层按月统计（助教维度），C 层按客户维度统计历史总和
- 思路分析：新增 `_update_task_stats(conn, site_id)` 函数，在 run() 主循环的 Step 4 中逐门店调用。B 层使用 `INSERT ... ON CONFLICT DO UPDATE` 对 `biz.dws_assistant_task_monthly` 做 upsert，按 `(site_id, assistant_id, stat_month)` 唯一键聚合当月任务数据。C 层对 `dws.dws_member_assistant_relation_index` 的 6 个新增字段做 UPDATE ... FROM 子查询，按 `(site_id, assistant_id, member_id)` 聚合历史总计。两层统计独立事务，互不影响
- 修改结果：每次任务生成完成后自动更新统计数据，供看板和报表使用。统计失败仅记录日志不中断主流程

### `db/zqyy_app/migrations/2026-03-31__task_stats_tables.sql`
- 变更类型：新增
- 原始原因：B 层月度统计需要持久化存储，按助教+月份维度汇总任务创建/完成/放弃/转移数量
- 思路分析：新建 `biz.dws_assistant_task_monthly` 表，主键 BIGSERIAL，唯一约束 `(site_id, assistant_id, stat_month)`。字段覆盖召回/回访/关系构建三种任务类型的创建数和完成数，以及放弃和转移计数。两个索引分别支持按门店+月份和按助教+月份的查询模式
- 修改结果：为任务引擎提供月度统计持久化能力，支持助教绩效看板展示

### `db/etl_feiqiu/migrations/2026-03-31__relation_index_task_stats.sql`
- 变更类型：新增
- 原始原因：C 层历史总计需要在关系指数表上新增字段，记录每对助教-客户关系的累计任务数据
- 思路分析：使用 `ALTER TABLE ADD COLUMN IF NOT EXISTS` 安全添加 6 个 INT 字段（默认值 0），分别记录召回/回访/总计的创建和完成数。包含 ROLLBACK 注释便于回滚
- 修改结果：关系指数表扩展为同时承载指数数据和任务统计数据，供客户详情页和任务分析使用

### `docs/database/ddl/zqyy_app__biz.sql`
- 变更类型：修改（简要）
- DDL 基线已合并新建表定义

## 验证 SQL

```sql
-- 1. 验证 dws_assistant_task_monthly 表存在且结构正确
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema = 'biz' AND table_name = 'dws_assistant_task_monthly'
ORDER BY ordinal_position;

-- 2. 验证 relation_index 新增字段
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema = 'dws' AND table_name = 'dws_member_assistant_relation_index'
  AND column_name IN ('recall_created_total', 'recall_completed_total',
                      'follow_up_created_total', 'follow_up_completed_total',
                      'total_created', 'total_completed');

-- 3. 验证唯一约束
SELECT conname, contype
FROM pg_constraint
WHERE conrelid = 'biz.dws_assistant_task_monthly'::regclass AND contype = 'u';
```
