# 变更审计记录：助教详情页样式修复 + 数据聚合修复 + 关系指数回测支持

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-29 12:41:38 |
| Prompt-ID | P20260329-122744 |

## 操作摘要

修复助教详情页的样式和数据聚合问题：TASK_TYPE_MAP 的 CSS 类名对齐 WXSS、label 文案调整；fdw_queries 中 `get_coach_top_customers` 修复多卡膨胀（CTE 先聚合再 JOIN）；coach-detail.wxml 近期服务明细限制最多显示 5 条。同时修复 `relation_index_task.py` 的 SQL 语法错误（f-string 拼接 INSERT 参数）并增加 P19 回测模式支持（lookback_days 60→90、as_of_date 替代 NOW()、calc_time 参数化写入）。

## 变更文件清单

| 文件 | 变更类型 | 风险 |
|------|----------|------|
| `apps/backend/app/services/coach_service.py` | 修改 | 中 |
| `apps/backend/app/services/fdw_queries.py` | 修改 | 高 |
| `apps/miniprogram/miniprogram/pages/coach-detail/coach-detail.wxml` | 修改 | 低 |
| `apps/etl/connectors/feiqiu/tasks/dws/index/relation_index_task.py` | 修改 | 高 |

## 改动注解

### `apps/backend/app/services/coach_service.py`
- 变更类型：修改
- 原始原因：TASK_TYPE_MAP 中的 CSS class 值（`tag-recall`/`tag-callback`/`tag-relationship`）与小程序 WXSS 中实际定义的类名不匹配，导致任务标签样式不生效；label 文案需要更贴合业务语义
- 思路分析：将 class 值改为 `high-priority`/`priority`/`callback`/`relationship` 以匹配 WXSS 类名定义；label 从 `回访` → `客户回访`、`紧急召回` → `高优先召回`，新增 `relationship_building` → `关系构建`
- 修改结果：任务类型标签在小程序中正确显示对应颜色样式，文案更准确

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：`get_coach_top_customers` 直接 JOIN `v_dim_member_card_account` 导致同一客户因持有多张卡而出现多行（多卡膨胀），TOP 客户列表数据重复
- 思路分析：引入 CTE `card_balance`，先按 `tenant_member_id` 做 `GROUP BY` + `SUM(balance)` 聚合所有卡余额，再 LEFT JOIN 到主查询。这是 `dim_member_card_account` 多卡膨胀的标准修复模式（参见 frontend-backend-integration 踩坑记录 2026-03-29）
- 修改结果：每个客户在 TOP 列表中只出现一行，余额为所有卡的合计值，消除了行膨胀问题

### `apps/miniprogram/miniprogram/pages/coach-detail/coach-detail.wxml`
- 变更类型：修改
- 原始原因：近期服务明细列表无数量限制，数据量大时页面过长影响体验
- 思路分析：添加 `wx:if="{{index < 5}}"` 条件渲染，限制默认最多显示 5 条记录
- 修改结果：近期服务明细默认只展示前 5 条，页面布局更紧凑

### `apps/etl/connectors/feiqiu/tasks/dws/index/relation_index_task.py`
- 变更类型：修改
- 原始原因：Prompt log 显示 `DWS_RELATION_INDEX` 执行失败，SQL 语法错误 `在 "{" 或附近的`——`_save_relation_rows` 中 INSERT 语句的时间戳占位符使用了 Python f-string 拼接但格式不正确
- 思路分析：
  1. **SQL 语法修复**：将 INSERT SQL 改为 f-string，根据 `use_param_time` 标志动态选择 `%s, %s, %s`（参数化）或 `NOW(), NOW(), NOW()`（直接 SQL）
  2. **P19 回测模式支持**：`execute()` 中 `now` 改为优先读取 `context.as_of_date`（回测时间点），正常模式仍用 `datetime.now()`
  3. **lookback_days 60→90**：所有子指数（RS/OS/MS/ML）的默认回溯天数从 60 天扩展到 90 天
  4. **calc_time 参数化写入**：`_save_relation_rows` 新增 `calc_time` 关键字参数，回测模式按 `calc_time` 删除旧数据（保留其他快照），正常模式按 `site_id` 全量刷新
  5. **参数元组重构**：将 `cur.execute(insert_sql, (...))` 改为先构建 `params` 元组，回测模式追加 3 个 `calc_time` 值
- 修改结果：修复了 SQL 语法错误使任务可正常执行；支持 P19 回测场景的多快照写入；回溯窗口扩大到 90 天覆盖更多历史数据

## 合规检查

| 检查项 | 状态 |
|--------|------|
| 新增迁移 SQL | 无 |
| DDL 基线更新 | ⚠️ DDL 基线待合并（`has_ddl_baseline: false`） |
| OpenAPI spec 同步 | 无需（`api_changed: false`） |
| 文档同步 | `relation_index_task.py` 需同步 ETL 任务文档 |

## 文档同步待办

- [ ] `apps/etl/connectors/feiqiu/docs/etl_tasks/` — 更新 `relation_index_task` 的参数说明（lookback_days 默认值 60→90、新增 calc_time/as_of_date 回测支持）
