Neo-ZQYY/docs/audit/changes/2026-03-24__p17-assistant-ownership-task-engine.md

变更审计记录：P17 助教客户归属与任务生成引擎

字段	值
日期	2026-03-24 07:00:13
Prompt-ID	P20260324-062345
Session-ID	415d32f9
Session 路径	docs/audit/session_logs/2026-03/24/25_d27915ce_055410
PRD	docs/prd/specs/P17-assistant-ownership-task-engine.md

操作摘要

P17 助教客户归属与任务生成引擎实施。核心变更：task_generator.py 完全重写（入口从 user_assistant_binding 改为 OS 归属对）、fdw_queries.py 新增 4 个批量查询方法、新建迁移脚本（coach_tasks 新增 3 字段 + 2 张新表 + 2 个新枚举值）、修复属性测试跳过问题。

变更文件清单

文件	变更类型	风险等级
apps/backend/app/services/task_generator.py	修改（完全重写）	高
apps/backend/app/services/fdw_queries.py	修改（追加 4 方法）	高
db/zqyy_app/migrations/2026-03-24__p17_task_engine_ownership.sql	新增	高
tests/test_core_business_properties.py	修改（修复）	中

本次对话文件变更

新增文件

• docs/audit/prompt_logs/prompt_log_20260324_062345.md
• docs/audit/session_logs/2026-03/24/25_d27915ce_055410/main_01_415d32f9.md
• docs/audit/session_logs/2026-03/24/26_b72f6c5a_062011/main_01_88b61816.md
• docs/prd/specs/P18-admin-task-engine-dashboard.md

删除文件

• docs/audit/session_logs/2026-03/24/25_d27915ce_055410/main_01_7469ca03.md

数据库变更（db-schema-change）

迁移脚本

db/zqyy_app/migrations/2026-03-24__p17_task_engine_ownership.sql

变更内容

操作	对象	说明
ALTER TABLE	biz.coach_tasks	新增 3 字段：transfer_count（INTEGER NOT NULL DEFAULT 0）、transferred_from（BIGINT FK→self）、transferred_at（TIMESTAMPTZ）
CREATE TABLE	biz.cfg_task_generator_params	任务引擎参数配置表（6 字段），支持全局默认 + 门店级覆盖，UNIQUE(site_id, param_key)
CREATE TABLE	biz.coach_task_transfer_log	客户转移日志表（11 字段），记录每次转移的完整上下文（三重保护检查快照、转移得分）
ADD ENUM VALUE	task_status	新增 transferred、pending_review（兼容 enum/varchar 两种情况）
INSERT SEED	biz.cfg_task_generator_params	13 条全局默认参数（ON CONFLICT DO NOTHING）
CREATE INDEX	idx_transfer_log_site_created	(site_id, created_at DESC)
CREATE INDEX	idx_transfer_log_member	(member_id, created_at DESC)

⚠️ DDL 基线待合并

compliance.has_ddl_baseline 为 false，新增的表和字段尚未合并到 DDL 基线文件（docs/database/ddl/zqyy_app__biz.sql）。

验证结果

• getDiagnostics: task_generator.py 和 fdw_queries.py 均无语法错误
• 属性测试: Property 1（任务类型判定）和 Property 11（爱心 icon 档位）各 200 用例全部通过
• 下游兼容性: 7 个下游模块均使用显式 status 过滤，新增 transferred/pending_review 状态不会被误匹配

改动注解

apps/backend/app/services/task_generator.py

• 变更类型：修改（完全重写）
• 原始原因：P17 PRD 要求将任务生成入口从 auth.user_assistant_binding（用户-助教绑定表）改为 OS 归属对（fdw_queries.get_ownership_pairs），以支持 MAIN/COMANAGE/POOL 三级归属模型下的精确任务分配
• 思路分析：
  • run() 主流程保持"获取 site_ids → 逐门店处理"的骨架，但入口数据源从绑定表改为 OS 归属视图
  • 新增 _run_for_site() 封装单门店流程：加载参数 → 查询归属对 → 批量读取 WBI/NCI → 逐对生成任务 → 客户转移检查
  • _process_pair() 实现参数化四级漏斗（阈值从 cfg_task_generator_params 读取，不再硬编码）
  • _run_transfer_check() 实现客户转移子流程，含三重保护（门店助教规模、入驻时间、服务关系门槛）
  • _do_transfer() 执行单次转移：原任务标记 transferred → 新助教创建任务（继承 transfer_count+1）→ 写入转移日志
  • 纯函数 determine_task_type/should_replace_task/compute_heart_icon 保持不变，确保属性测试兼容
  • load_params() 实现三级继承链：代码默认 → 全局默认（site_id IS NULL）→ 门店覆盖
• 修改结果：任务生成器从"绑定关系驱动"升级为"归属关系驱动"，支持客户转移和参数化配置。影响范围：trigger_scheduler.py（调用 run()）、biz.coach_tasks 表（新增字段）、biz.cfg_task_generator_params（新表）、biz.coach_task_transfer_log（新表）

apps/backend/app/services/fdw_queries.py

• 变更类型：修改（末尾追加 4 个方法）
• 原始原因：P17 任务生成器需要从 ETL 库读取 OS 归属对和批量指数数据，原有 fdw_queries 不提供这些查询
• 思路分析：
  • get_ownership_pairs(conn, site_id) — 查询 v_dws_member_assistant_relation_index WHERE os_label IN ('MAIN', 'COMANAGE')，返回 [{assistant_id, member_id, rs}]
  • get_pool_assistants(conn, site_id, member_id) — 查询同一客户的 POOL 助教候选池，返回 [{assistant_id, rs, ms, ml}]（用于转移候选排序）
  • get_wbi_batch(conn, site_id) / get_nci_batch(conn, site_id) — 批量读取 WBI/NCI 指数，返回 {member_id: Decimal}
  • 所有方法使用 _fdw_context() 连接 ETL 库，遵循 H2 FDW→直连改造后的统一模式
• 修改结果：为 P17 任务生成器提供完整的数据查询层。影响范围仅限 task_generator.py 调用

db/zqyy_app/migrations/2026-03-24__p17_task_engine_ownership.sql

• 变更类型：新增
• 原始原因：P17 任务引擎需要新的数据库对象支持客户转移追踪和参数化配置
• 思路分析：
  • 使用 DO 块兼容 enum/varchar 两种 status 列类型，安全添加 transferred/pending_review 枚举值
  • coach_tasks 新增 3 字段使用 ADD COLUMN IF NOT EXISTS 保证幂等
  • cfg_task_generator_params 使用 UNIQUE(site_id, param_key) 支持全局+门店级覆盖的继承链
  • coach_task_transfer_log 的 guard_checks 字段使用 JSONB 存储三重保护检查快照，便于审计追溯
  • 种子数据使用 ON CONFLICT DO NOTHING 保证幂等
  • 文件末尾包含注释形式的 ROLLBACK 语句
• 修改结果：为 P17 提供完整的数据库支撑。新增 2 张表、3 个字段、2 个索引、13 条种子数据

tests/test_core_business_properties.py

• 变更类型：修改（修复）
• 原始原因：module-level pytest.skip 导致整个测试文件被跳过（包括不依赖数据库的纯函数属性测试），需要改为更精确的跳过机制
• 思路分析：将 module-level skip 改为 class-level @pytest.mark.skipif，仅跳过需要数据库连接的测试类；加入 apps/backend/ 到 sys.path 解决 from app.* 导入问题；更新 Property 1 断言以匹配 P17 的 RS > 1 下限规则（原规则 RS ≥ 0 生成关系构建，P17 改为 RS > 1）
• 修改结果：属性测试恢复正常运行，Property 1 和 Property 11 各 200 用例全部通过