# 变更审计记录：RNS1.4 CHAT 模块重建 + FDW→直连统一 + R3 筛选修复

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-20 07:24:18 |
| Prompt-ID | P20260320-071439 |
| Session-ID | bf375635 |
| Session 路径 | docs/audit/session_logs/2026-03/20/27_bf375635_064532 |

## 操作摘要

本次对话延续上一轮上下文，完成了 5 项主要任务：
1. RNS1 系列 AI 自主决策风险审计报告（76 个 session，34 个风险点）
2. gift-card-breakdown DDL 迁移验证与文档同步
3. H1 残留问题 R1 修复（`fdw_queries.py` 引用不存在列）
4. R3 完整修复 — 项目类型筛选接口重建（SkillFilterEnum/ProjectFilterEnum 枚举值对齐 cfg_area_category）
5. H2 修复 — FDW→直连 ETL 架构统一（4 个 service 文件从 `fdw_etl.*` 改为 `app.v_*` RLS 视图）

涉及后端 13 个文件、小程序 18 个文件、数据库迁移 2 个、文档 4 个，总计 42 文件 +1543/-1373 行。

## 风险标签

- `dir:backend` — 后端路由/Schema/Service 大规模重构
- `dir:miniprogram` — 小程序全页面 API 层重写
- `dir:db` — 新增迁移 SQL（etl_feiqiu + zqyy_app）
- `db-schema-change` — DDL 变更（sort_order 字段、area_category 视图、chat 模块表扩展）

## 本次对话文件变更

### 新增文件
- `docs/audit/changes/2026-03-20__h2-fdw-to-direct-etl-unification.md` — H2 修复独立审计记录
- `docs/audit/prompt_logs/prompt_log_20260320_071439.md` — Prompt 日志
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/main_01_545a6df2.md` — Session 主日志
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/sub_01_224a7d74.md` — 子代理日志 1
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/sub_02_224a7d74.md` — 子代理日志 2
- `docs/audit/session_logs/2026-03/20/28_804968a7_071409/main_01_224a7d74.md` — 后续 Session 日志
- `scripts/ops/test_chat_e2e.py` — CHAT 模块端到端测试脚本

### 删除文件
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/main_01_8969b519.md` — 被替换的旧 Session 日志

## DDL/迁移检查

- `compliance.new_migration_sql`：空（迁移文件已在之前的对话中创建并执行）
- ⚠️ DDL 基线待合并（`has_ddl_baseline: false`）

## 改动注解

### `apps/backend/app/main.py`
- 变更类型：修改
- 原始原因：xcx_ai_chat 路由迁移为 xcx_chat，统一到 `/api/xcx/chat/*` 路径
- 思路分析：将 import 和 include_router 从 `xcx_ai_chat` 改为 `xcx_chat`，CHANGE 注释追加迁移说明
- 修改结果：路由注册指向新模块，旧 `/api/ai/*` 路径废弃

### `apps/backend/app/routers/xcx_ai_chat.py`
- 变更类型：删除
- 原始原因：CHAT 模块从 `/api/ai/*` 迁移到 `/api/xcx/chat/*`，旧路由文件不再需要
- 修改结果：223 行代码删除，功能由 `xcx_chat.py` 替代

### `apps/backend/app/routers/xcx_chat.py`
- 变更类型：新增
- 原始原因：实现 CHAT-1/2/3/4 四个端点，替代旧 xcx_ai_chat.py
- 思路分析：新增 CHAT-1（对话历史）、CHAT-2a/2b（消息查询，按 chatId 或 contextType+contextId）、CHAT-3（同步发送）、CHAT-4（SSE 流式）。使用 `require_approved()` 权限检查，引入 `ChatService` 业务层
- 修改结果：统一路径前缀 `/api/xcx/chat`，新增 contextType 路由复用机制

### `apps/backend/app/routers/xcx_board.py`
- 变更类型：修改
- 原始原因：R3 修复 — SkillFilterEnum/ProjectFilterEnum 默认值从 `.all` 改为 `.ALL`
- 思路分析：枚举值对齐 `dws.cfg_area_category.category_code`，消除前后端映射层
- 修改结果：助教看板和客户看板的筛选参数默认值与数据库一致

### `apps/backend/app/schemas/xcx_board.py`
- 变更类型：修改
- 原始原因：R3 修复 — 枚举值从 chinese/snooker 等前端自定义值改为 BILLIARD/SNOOKER 等数据库 category_code
- 思路分析：SkillFilterEnum 和 ProjectFilterEnum 的值直接使用 `cfg_area_category.category_code`，消除前后端映射层
- 修改结果：枚举值与数据库一致，前端直接传递数据库值

### `apps/backend/app/schemas/xcx_chat.py`
- 变更类型：新增
- 原始原因：CHAT 模块需要独立的 Pydantic Schema（对话历史、消息、发送、SSE 请求）
- 思路分析：基于 CamelModel 基类，定义 ChatHistoryItem/Response、ChatMessageItem/Response、SendMessageRequest/Response、ChatStreamRequest、ReferenceCard 等模型
- 修改结果：CHAT 模块完整的请求/响应模型定义

### `apps/backend/app/schemas/xcx_config.py`
- 变更类型：修改
- 原始原因：R3 修复 — SkillTypeItem.key 注释从 chinese/snooker 改为 BILLIARD/SNOOKER
- 思路分析：key 值与 `dws.cfg_area_category.category_code` 一致，label 从 `display_name` 读取
- 修改结果：Schema 注释与实际数据源对齐

### `apps/backend/app/services/chat_service.py`
- 变更类型：新增
- 原始原因：CHAT 模块业务逻辑层，封装对话管理、消息持久化、referenceCard 组装
- 思路分析：独立 Service 层，处理对话 session 的创建/复用、消息 CRUD、AI 回复集成
- 修改结果：CHAT-1/2/3/4 端点的核心业务逻辑

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：H1 残留修复 — `get_consumption_records` 引用 5 个不存在的列
- 思路分析：通过 `LEFT JOIN app.v_dwd_settlement_head` 补全缺失列
- 修改结果：查询语法正确，MCP 验证通过

### `apps/backend/app/services/matching.py`
- 变更类型：修改
- 原始原因：H2 修复 — FDW→直连 ETL 统一改造
- 思路分析：`fdw_etl.v_dim_assistant/v_dim_staff/v_dim_staff_ex` → `app.v_*`；`scd2_is_current = TRUE` → `= 1`；连接改为 `_fdw_context(None, site_id)`
- 修改结果：消除 FDW 外部表依赖，RLS 门店隔离生效

### `apps/backend/app/services/recall_detector.py`
- 变更类型：修改
- 原始原因：H2 修复 — FDW→直连 ETL 统一改造
- 思路分析：`fdw_etl.v_dwd_assistant_service_log` → `app.v_*`；列名映射修正（assistant_id→site_assistant_id、member_id→tenant_member_id、service_time→create_time）
- 修改结果：消除 FDW 外部表依赖，列名与 RLS 视图一致

### `apps/backend/app/services/task_generator.py`
- 变更类型：修改
- 原始原因：H2 修复 — FDW→直连 ETL 统一改造
- 思路分析：3 处 `fdw_etl.v_dws_member_winback/newconv/relation_index` → `app.v_*`；使用 `_fdw_context(conn, site_id)`
- 修改结果：WBI/NCI 全表扫描改为 RLS 隔离查询

### `apps/backend/app/services/task_manager.py`
- 变更类型：修改
- 原始原因：H2 修复 — FDW→直连 ETL 统一改造（4 处）
- 思路分析：`get_task_list()` 中 `fdw_etl.v_dim_member`（列名 member_name→nickname、member_phone→mobile）+ RS 指数；`get_task_list_v2()` 和 `get_task_detail()` 中 RS 指数查询
- 修改结果：4 处 FDW 查询全部改为直连 ETL + RLS 视图

### `apps/miniprogram/miniprogram/services/api.ts`
- 变更类型：修改
- 原始原因：小程序 API 层全面重写，适配后端路由迁移和新 CHAT 模块
- 思路分析：API 路径从 `/api/ai/*` 迁移到 `/api/xcx/chat/*`，新增 CHAT-1/2/3/4 对应的 API 函数
- 修改结果：400 行变更，API 层与后端路由完全对齐

### `apps/miniprogram/miniprogram/pages/chat/chat.ts`
- 变更类型：修改
- 原始原因：CHAT 页面大规模重构，适配新 CHAT 模块接口
- 思路分析：386 行新增，实现 CHAT-2b（contextType 路由）、CHAT-3（同步发送）、CHAT-4（SSE 流式）的前端交互
- 修改结果：聊天页面功能完整，支持上下文关联对话

### 小程序其他页面（简要注解）
- `board-coach.ts` / `board-customer.ts`：筛选参数从 chinese/snooker 改为 BILLIARD/SNOOKER
- `chat-history.ts`：适配 CHAT-1 新接口路径
- `chat.wxml` / `chat.wxss`：CHAT 页面模板和样式扩展
- `coach-detail.ts`：适配后端接口变更
- `customer-detail.ts`：适配后端接口变更
- `customer-service-records.ts` / `.wxml` / `.wxss`：客户服务记录页面重构
- `my-profile.ts`：个人中心适配
- `notes.ts` / `notes.wxml`：备注页面适配
- `performance-records.ts`：绩效记录页面重构
- `task-detail.ts`：任务详情适配
- `task-list.ts`：任务列表适配

### `db/etl_feiqiu/migrations/2026-03-20_add_sort_order_and_area_category_view.sql`
- 变更类型：新增（高风险）
- 原始原因：R3 修复 — cfg_area_category 表新增 sort_order 字段，创建 category 级别去重视图
- 思路分析：为 CONFIG-1 接口提供排序能力，视图去重到 category 级别排除 SPECIAL/OTHER
- 修改结果：DDL 变更，需确认已在测试库执行

### `db/zqyy_app/migrations/2026-03-20__rns14_chat_module_extend.sql`
- 变更类型：新增（高风险）
- 原始原因：CHAT 模块表结构扩展（ai_chat_sessions / ai_chat_messages 新增字段）
- 思路分析：支持 contextType/contextId 路由复用、referenceCard 存储等新功能
- 修改结果：DDL 变更，需确认已在测试库执行

### `scripts/ops/test_chat_e2e.py`
- 变更类型：新增
- 原始原因：CHAT 模块端到端测试脚本
- 修改结果：验证 CHAT-1/2/3/4 端点的完整功能

### 文档文件（简要注解）
- `apps/backend/README.md`：新增 xcx_chat 路由和 chat_service 说明
- `apps/backend/docs/API-REFERENCE.md`：新增 CHAT 模块 API 文档（73 行）
- `apps/miniprogram/README.md`：新增 CHAT 模块集成说明
- `docs/database/BD_Manual_app_schema_rls_views.md`：更新 RLS 视图文档
- `docs/database/ddl/etl_feiqiu__app.sql`：DDL 基线更新
- `docs/database/ddl/etl_feiqiu__dws.sql`：DDL 基线更新

## DB 文档全量对账

⚠️ 全量对账延迟执行：测试库 DSN 连接时出现 `UnicodeDecodeError`（DSN 字符串含非 UTF-8 字符），无法通过脚本自动连接 `test_etl_feiqiu`。

已有文档状态：
- `docs/database/BD_Manual_app_schema_rls_views.md` — 本次已更新（RLS 视图变更）
- `docs/database/BD_Manual_ai_tables.md` — 已有（AI 相关表）
- `docs/database/BD_Manual_auth_tables.md` — 已有（认证表）
- `docs/database/BD_Manual_biz_tables.md` — 已有（业务表）
- `docs/database/BD_Manual_fdw_etl_setup.md` — 已有（FDW 配置）
- `docs/database/ddl/etl_feiqiu__app.sql` — 本次已更新
- `docs/database/ddl/etl_feiqiu__dws.sql` — 本次已更新

待手动执行：用户需通过 pg power MCP server（`pg-etl-test` / `pg-app-test`）手动验证表结构与文档一致性。
