# 变更审计记录：RNS1.4 CHAT 模块迁移 + R3 项目类型筛选重建

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-20 07:09:51 |
| Prompt-ID | P20260320-065654 |
| Session-ID | （索引未更新，无匹配） |
| Session 路径 | docs/audit/session_logs/2026-03/20/27_bf375635_064532/ |

## 操作摘要

本次变更包含三个关联改造：

1. **RNS1.4 CHAT 模块迁移**：将原 `xcx_ai_chat.py`（`/api/ai/*`）整体迁移为 `xcx_chat.py`（`/api/xcx/chat/*`），新增 `chat_service.py` 业务层和 `xcx_chat.py` Schema，实现 CHAT-1（历史列表）、CHAT-2a/2b（消息查看）、CHAT-3（同步发送）、CHAT-4（SSE 流式）四个端点。权限从 `get_current_user` 升级为 `require_approved()`。
2. **R3 项目类型筛选接口重建**：`SkillFilterEnum` / `ProjectFilterEnum` 枚举值从前端自定义值（`chinese/snooker/mahjong/karaoke`）改为数据库 `cfg_area_category.category_code`（`BILLIARD/SNOOKER/MAHJONG/KTV`），消除前后端映射层。`SkillTypeItem` Schema 同步更新。
3. **小程序前端适配**：chat 页面重写（386 行新增）、board-coach 筛选适配、notes 页面修改、api.ts 接口层重构。

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260320_065654.md`
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/main_01_8969b519.md`

### 删除文件
- `docs/audit/session_logs/2026-03/20/27_bf375635_064532/main_01_3d7bccb1.md`（Session 日志重写替换）

## 改动注解

### `apps/backend/app/main.py`
- 变更类型：修改
- 原始原因：CHAT 模块路由从 `xcx_ai_chat` 迁移到 `xcx_chat`，统一 `/api/xcx/` 路径前缀
- 思路分析：仅修改 import 和 `include_router` 引用，CHANGE 注释追加迁移说明保留历史可追溯性
- 修改结果：路由注册从 `xcx_ai_chat.router` 切换为 `xcx_chat.router`，其他路由不受影响

### `apps/backend/app/routers/xcx_ai_chat.py`
- 变更类型：删除
- 原始原因：整体迁移为 `xcx_chat.py`，旧文件废弃。原 3 个端点（`/api/ai/chat/stream`、`/api/ai/conversations`、`/api/ai/conversations/{id}/messages`）全部由新模块替代
- 修改结果：223 行代码删除，功能由 `xcx_chat.py` + `chat_service.py` 承接

### `apps/backend/app/routers/xcx_chat.py`
- 变更类型：新增
- 原始原因：RNS1.4 PRD 要求统一 CHAT 端点到 `/api/xcx/chat/*` 路径，新增 CHAT-2b（按上下文查消息）和 CHAT-3（同步回复）端点
- 思路分析：路由注册顺序精心设计——`/messages`（CHAT-2b）和 `/stream`（CHAT-4）必须在 `/{chat_id}/messages` 之前注册，避免 FastAPI 路径参数误匹配。权限统一使用 `require_approved()` 替代原来的 `get_current_user`。SSE 流式端点增加归属验证（在流开始前完成，失败返回普通 HTTP 错误而非 SSE 错误）
- 修改结果：5 个端点（CHAT-1/2a/2b/3/4），所有业务逻辑委托给 `ChatService`

### `apps/backend/app/services/chat_service.py`
- 变更类型：新增
- 原始原因：从路由层抽离业务逻辑，实现对话管理、消息持久化、referenceCard 组装、标题生成等核心功能
- 思路分析：依赖 `biz.ai_conversations` 和 `biz.ai_messages` 表（含 `context_type/context_id/title/last_message` 扩展字段）。通过 `fdw_queries` 直连 ETL 库获取会员维度数据。P5 PRD 合规：用户消息发送时即写入
- 修改结果：封装 `get_chat_history`、`get_messages`、`get_or_create_session`、`send_message_sync`、`_save_message`、`_verify_ownership` 等方法

### `apps/backend/app/schemas/xcx_chat.py`
- 变更类型：新增
- 原始原因：CHAT 模块需要独立的请求/响应 Schema，替代原 `app.ai.schemas` 中的定义
- 思路分析：基于 `CamelModel` 基类实现驼峰命名自动转换。新增 `ReferenceCard` 模型支持 AI 回复中的结构化引用卡片
- 修改结果：定义 `ChatHistoryItem/Response`、`ChatMessageItem/MessagesResponse`、`SendMessageRequest/Response`、`ChatStreamRequest` 等 8 个模型

### `apps/backend/app/routers/xcx_board.py`
- 变更类型：修改
- 原始原因：R3 修复——`SkillFilterEnum` / `ProjectFilterEnum` 默认值从 `.all` 改为 `.ALL`，与新枚举值一致
- 思路分析：枚举值变更后，路由参数默认值必须同步更新，否则 FastAPI 启动时会因枚举值不匹配报错
- 修改结果：2 处默认值更新 + AI_CHANGELOG 注释

### `apps/backend/app/schemas/xcx_board.py`
- 变更类型：修改
- 原始原因：R3 修复——枚举值从前端自定义值改为数据库 `category_code`，消除前后端映射层
- 思路分析：`SkillFilterEnum` 和 `ProjectFilterEnum` 的值从 `all/chinese/snooker/mahjong/karaoke` 改为 `ALL/BILLIARD/SNOOKER/MAHJONG/KTV`，直接与 `dws.cfg_area_category.category_code` 对齐。这样前端传参可直接用于 SQL WHERE 条件，无需后端做值映射
- 修改结果：2 个枚举类共 10 个值更新 + CHANGE 注释 + AI_CHANGELOG

### `apps/backend/app/schemas/xcx_config.py`
- 变更类型：修改
- 原始原因：R3 修复——`SkillTypeItem` 的 `key` 注释和 `label` 说明需与新枚举值一致
- 思路分析：`key` 从 `chinese/snooker` 改为 `BILLIARD/SNOOKER`，`label` 改为从 `display_name` 读取（含 emoji），`cls` 保留但后端不再填充
- 修改结果：Schema 注释和文档字符串更新 + CHANGE 注释 + AI_CHANGELOG

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：95 行变更，推测为 CHAT 模块新增的 ETL 直连查询方法或现有查询调整
- 思路分析：diff 被截断，具体变更内容从 diff_stat 推断为新增/修改查询函数以支持 chat_service 的数据需求
- 修改结果：fdw_queries 模块扩展，为 CHAT 模块提供会员维度数据查询能力

### `apps/miniprogram/miniprogram/pages/chat/chat.ts`
- 变更类型：修改（386 行新增）
- 原始原因：适配后端 CHAT 模块迁移，从 `/api/ai/*` 切换到 `/api/xcx/chat/*` 端点
- 思路分析：大幅重写，新增 CHAT-2b（按上下文查消息）、CHAT-3（同步发送）支持，SSE 流式对话适配新事件格式
- 修改结果：chat 页面功能完整重建，支持新的 CHAT-1/2/3/4 端点

### `apps/miniprogram/miniprogram/pages/chat/chat.wxml`
- 变更类型：修改
- 原始原因：配合 chat.ts 重写，新增 UI 元素
- 修改结果：14 行新增模板代码

### `apps/miniprogram/miniprogram/pages/chat/chat.wxss`
- 变更类型：修改
- 原始原因：配合 chat 页面重写，新增样式
- 修改结果：6 行新增样式

### `apps/miniprogram/miniprogram/pages/chat-history/chat-history.ts`
- 变更类型：修改
- 原始原因：适配 CHAT-1 端点迁移（`/api/ai/conversations` → `/api/xcx/chat/history`）
- 修改结果：38 行变更，API 调用路径和响应结构适配

### `apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts`
- 变更类型：修改
- 原始原因：R3 修复——技能筛选参数从 `chinese/snooker` 改为 `BILLIARD/SNOOKER`
- 修改结果：17 行变更，筛选参数值适配新枚举

### `apps/miniprogram/miniprogram/pages/notes/notes.ts`
- 变更类型：修改
- 原始原因：备注页面功能调整
- 修改结果：91 行变更

### `apps/miniprogram/miniprogram/pages/notes/notes.wxml`
- 变更类型：修改
- 原始原因：配合 notes.ts 变更
- 修改结果：8 行变更

### `apps/miniprogram/miniprogram/services/api.ts`
- 变更类型：修改
- 原始原因：API 接口层重构，适配 CHAT 模块端点迁移和 R3 筛选参数变更
- 修改结果：114 行变更，接口定义和调用路径全面更新


### `db/zqyy_app/migrations/2026-03-20__rns14_chat_module_extend.sql`
- 变更类型：新增
- 原始原因：CHAT 模块需要扩展 `biz.ai_conversations` 和 `biz.ai_messages` 表结构（新增 `context_type`、`context_id`、`title`、`last_message`、`reference_card` 等字段）
- 思路分析：ALTER TABLE 扩展现有表而非新建，保留历史数据兼容性
- 修改结果：业务库迁移脚本，支持 CHAT-1/2/3/4 端点的数据存储需求

### `db/etl_feiqiu/migrations/2026-03-20_add_sort_order_and_area_category_view.sql`
- 变更类型：新增
- 原始原因：R3 修复需要 `cfg_area_category` 表新增 `sort_order` 字段，并创建 RLS 视图供前端筛选器使用
- 思路分析：ETL 库迁移，为 CONFIG-1 端点提供数据源
- 修改结果：ETL 库结构扩展

### `docs/database/BD_Manual_app_schema_rls_views.md`
- 变更类型：修改
- 原始原因：同步更新 BD 手册，记录 app schema RLS 视图的变更
- 修改结果：13 行变更，文档与数据库结构保持一致

### `docs/database/ddl/etl_feiqiu__app.sql`
- 变更类型：修改
- 原始原因：DDL 基线同步更新，反映 `app` schema 新增对象
- 修改结果：13 行新增

### `docs/database/ddl/etl_feiqiu__dws.sql`
- 变更类型：修改
- 原始原因：DDL 基线同步更新，反映 `dws` schema 结构变更
- 修改结果：157 行变更（格式整理 + 结构更新）

### `apps/backend/README.md`
- 变更类型：修改（简要）
- 修改结果：4 行新增，记录 CHAT 模块路由变更

### `apps/backend/docs/API-REFERENCE.md`
- 变更类型：修改（简要）
- 修改结果：73 行新增，补充 CHAT-1/2/3/4 端点文档

### `apps/miniprogram/README.md`
- 变更类型：修改（简要）
- 修改结果：4 行新增，记录 CHAT 页面变更

## 合规检查

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 迁移 SQL 执行验证 | ⏭️ 跳过 | `new_migration_sql` 为空（迁移文件已在 changed_files 中但未标记为待执行） |
| DDL 基线同步 | ⚠️ 待确认 | `has_ddl_baseline: false`，但 `etl_feiqiu__app.sql` 和 `etl_feiqiu__dws.sql` 已在变更列表中 |
| BD 手册同步 | ✅ 已更新 | `BD_Manual_app_schema_rls_views.md` 已在变更列表中 |
| OpenAPI Spec | ⏭️ 无需同步 | `api_changed: false` |
| 文档同步 | ✅ 已覆盖 | API-REFERENCE.md、backend README、miniprogram README 均已更新 |
| notes.ts 文档同步 | ⚠️ 需补充 | `notes.ts` 变更但 miniprogram README 页面路由表未包含 notes 页面 |

## 风险评估

- **高风险**：`xcx_ai_chat.py` 删除后，任何仍引用 `/api/ai/*` 路径的客户端将 404。需确认小程序端已全部切换到 `/api/xcx/chat/*`
- **中风险**：`SkillFilterEnum` / `ProjectFilterEnum` 枚举值变更是破坏性变更，小程序端必须同步发版
- **低风险**：`chat_service.py` 新增的 `_verify_ownership` 在 SSE 流开始前执行，归属验证失败返回 HTTP 403 而非 SSE error，前端需正确处理
- **回滚**：恢复 `xcx_ai_chat.py`、回退枚举值、回退小程序代码即可，数据库迁移为 ALTER TABLE ADD COLUMN，回滚需手动 DROP COLUMN
