Neo-ZQYY/docs/audit/changes/2026-03-31__task-engine-overhaul.md

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

字段	值
日期	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

-- 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';