# 变更审计记录：R3 项目类型筛选接口重建（fetchSkillTypes / cfg_area_category）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-20 06:34:33 |
| Prompt-ID | P20260320-060704 |
| Session-ID | 2418703b |
| Session 路径 | docs/audit/session_logs/2026-03/20/22_fcfce9bc_054759 |

## 操作摘要

将项目类型筛选从虚构的 `v_cfg_skill_type` 视图改为真实的 `dws.cfg_area_category` 数据源。新建 `app.v_cfg_area_category` RLS 视图（DISTINCT 去重到 category 级别，排除 SPECIAL/OTHER，按 sort_order 排序）。前后端枚举值统一为数据库 category_code（BILLIARD/SNOOKER/MAHJONG/KTV），消除映射层。同时包含 RNS1.4 CHAT 模块的 schema/service/迁移脚本新建，以及 R1 修复（get_consumption_records 费用拆分字段来源修正）。

## 变更文件清单

| 文件 | 变更类型 | 风险标签 |
|------|----------|----------|
| `apps/backend/app/schemas/xcx_chat.py` | 新增 | dir:backend |
| `apps/backend/app/services/chat_service.py` | 新增 | dir:backend |
| `apps/backend/app/services/fdw_queries.py` | 修改 | dir:backend |
| `db/zqyy_app/migrations/2026-03-20__rns14_chat_module_extend.sql` | 新增 | dir:db, db-schema-change |
| `docs/database/BD_Manual_app_schema_rls_views.md` | 修改 | dir:db |

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260320_060704.md`
- `docs/audit/session_logs/2026-03/20/22_fcfce9bc_054759/main_01_2418703b.md`
- `docs/audit/session_logs/2026-03/20/22_fcfce9bc_054759/sub_01_2418703b.md`

### 删除文件
- `docs/audit/session_logs/2026-03/20/22_fcfce9bc_054759/main_01_45199c54.md`（被 2418703b 取代）


## 合规检查

| 检查项 | 状态 | 说明 |
|--------|------|------|
| AI_CHANGELOG | ✅ | 所有高风险文件头部已有 AI_CHANGELOG 注释 |
| CHANGE 标记 | ✅ | fdw_queries.py 中 get_consumption_records 已有 CHANGE 注释 |
| 迁移 SQL | ℹ️ | `compliance.new_migration_sql` 为空（迁移脚本在 audit_context 构建前已存在） |
| DDL 基线 | ⚠️ | `compliance.has_ddl_baseline` 为 false — DDL 基线待合并 |
| BD 手册 | ⚠️ | `compliance.has_bd_manual` 为 false — BD 手册待补充 CHAT 模块表结构 |
| OpenAPI Spec | ✅ | `compliance.api_changed` 为 false，无需同步 |
| 文档同步 | ⚠️ | `chat_service.py` 缺少对应的 API-REFERENCE.md 和 README.md 更新（见下方文档补齐段落） |

## 文档补齐待办

根据 `compliance.code_without_docs` 检测：

- `apps/backend/app/services/chat_service.py` → 需更新：
  - `apps/backend/docs/API-REFERENCE.md`：补充 CHAT 模块端点（CHAT-1/2/3/4）
  - `apps/backend/README.md`：路由总览表补充 `/api/xcx/chat`，服务层表补充 `chat_service.py`

> ⚠️ 由于 CHAT 路由文件（`xcx_chat.py`）尚未在本次 `changed_files` 中出现，说明路由层可能尚未实现。文档补齐应在路由层完成后统一进行。当前仅标注待办。

## 改动注解

### `apps/backend/app/schemas/xcx_chat.py`
- 变更类型：新增
- 原始原因：RNS1.4 CHAT 模块需要 Pydantic 请求/响应模型，覆盖对话历史（CHAT-1）、消息查看（CHAT-2）、发送消息（CHAT-3）、SSE 流式（CHAT-4）四个端点
- 思路分析：继承 `CamelModel` 基类实现 camelCase 自动转换；`ReferenceCard` 作为嵌套模型支持 AI 回复中的结构化引用卡片；所有时间字段统一为 ISO 8601 字符串
- 修改结果：定义了 8 个 Schema 类，为 CHAT 路由层提供类型安全的请求/响应定义

### `apps/backend/app/services/chat_service.py`
- 变更类型：新增
- 原始原因：RNS1.4 CHAT 模块业务逻辑层，封装对话管理、消息持久化、referenceCard 组装、标题生成
- 思路分析：`ChatService` 类封装全部业务逻辑；对话复用策略按 context_type 区分（task 无时限复用、customer/coach 3 天时限、general 始终新建）；referenceCard 通过 FDW 查询客户指标组装，失败时静默降级为 null；遵循 DWD-DOC 规则（金额用 items_sum 口径、会员信息通过 dim_member JOIN）
- 修改结果：实现 CHAT-1（历史列表）、CHAT-2（消息列表）、CHAT-3（同步发送）核心逻辑，依赖 `biz.ai_conversations` 和 `biz.ai_messages` 表

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：R1 修复 — `get_consumption_records` 函数引用 5 个不存在于 `v_dwd_assistant_service_log` 的列（table_charge_money, goods_money, assistant_pd_money, assistant_cx_money, settle_type），这些列实际属于 `v_dwd_settlement_head`
- 思路分析：添加 `LEFT JOIN app.v_dwd_settlement_head sh ON sl.order_settle_id = sh.order_settle_id`，5 个列引用从 `sl.` 改为 `sh.`，WHERE 中 `settle_type` 引用也改为 `sh.`。假设每条 service_log 对应 0 或 1 条 settlement_head（1:1 或 1:0）
- 修改结果：消费记录查询恢复正常，费用拆分字段（台费、商品、陪打费、超休费、结算类型）正确来自结算单头表。MCP 端到端验证通过

### `db/zqyy_app/migrations/2026-03-20__rns14_chat_module_extend.sql`
- 变更类型：新增
- 原始原因：CHAT 模块需要扩展 `biz.ai_conversations`（多入口对话复用、历史列表展示）和 `biz.ai_messages`（引用卡片）
- 思路分析：使用 `ADD COLUMN IF NOT EXISTS` 保证幂等；新增 2 个索引优化上下文查找和历史列表排序；包含完整的回滚 SQL 和验证查询
- 修改结果：ai_conversations 新增 5 字段（context_type, context_id, title, last_message, last_message_at），ai_messages 新增 1 字段（reference_card jsonb），2 个索引

### `docs/database/BD_Manual_app_schema_rls_views.md`
- 变更类型：修改
- 原始原因：新增 `app.v_cfg_area_category` RLS 视图后，BD 手册中 cfg 视图数量和视图总数需要更新
- 思路分析：cfg 视图从 4 张改为 5 张，视图总数从 38 改为 39
- 修改结果：BD 手册数据与实际数据库一致
