# 变更审计记录：DDL vs 数据库结构对比修复 + BD 手册全面审核走查

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-22 19:10:09 |
| Prompt-ID | P20260322-181225 |
| Session-ID | （索引未收录，跳过） |
| Session 路径 | docs/audit/session_logs/2026-03/22/52_08e70bf5_180519/ |

## 操作摘要

用户要求对比 DDL 基线与测试数据库（`test_zqyy_app`）实际结构，发现差异后修复，并对所有 BD 手册从头审核走查。涉及 P15 迁移执行、DDL 文件补齐、10 个 BD 手册文档的修正/归档。

## 变更范围

### 数据库修复
1. `test_zqyy_app` 执行 P15 迁移：`biz.ai_run_logs` 新增 `alert_status` 字段 + CHECK 约束 + 部分索引 + BRIN 索引 + 回填
2. DDL 文件 `docs/database/ddl/zqyy_app__public.sql`：`task_execution_log` 补充 `config jsonb` 字段

### BD 手册修复（10 个文件）
1. `docs/database/README.md` — 更新 auth(8→9)/biz(7→18)/dws(36→35) 表计数，DDL 基线日期，BD_Manual 索引扩展到 12 文件，归档描述更新
2. `docs/database/BD_Manual_auth_tables.md` — 表计数 8→9，新增 `_archived_site_code_mapping` 和 `tenant_admins` 条目，标记 `site_code_mapping` 约束废弃
3. `docs/database/BD_Manual_app_schema_rls_views.md` — 视图计数修正：DWS 24→23（去除重复 `v_dws_assistant_recharge_commission`），别名 6→7，删除过时 P2 预留注释（`v_dws_assistant_order_contribution` 已创建），验证 SQL 更新
4. `docs/database/BD_Manual_ai_tables.md` — 验证 SQL 修正：ai_conversations 字段数 13→14，ai_cache CHECK 约束 1→2 行，ai_run_logs 索引数 4→6 行
5. `docs/database/BD_Manual_fdw_etl_setup.md` — 外部表计数 38→46，分类明细 DWS 24→23 + 别名 6→7
6. `docs/database/BD_Manual_fdw_reverse_retention_clue.md` — 新增 `is_hidden` 列到已知差异
7. `docs/database/BD_Manual_biz_tables.md` — notes CHECK 约束验证 SQL 2→3 行
8. `docs/database/BD_Manual_tenant_admins_deleted_at.md` — 移至 `docs/database/_archived/`（内容已合并到主文档）

### 迁移脚本
- `db/zqyy_app/migrations/2026-03-22__add_config_to_execution_log.sql`（DDL 补齐记录）
- `db/zqyy_app/migrations/2026-03-23__p15_ai_monitoring.sql`（P15 迁移执行记录）

## DDL/迁移检查
- `compliance.new_migration_sql`：空（迁移已在之前的对话中执行）
- `compliance.has_ddl_baseline`：false — ⚠️ DDL 基线待合并（`zqyy_app__public.sql` 已更新 `config jsonb`，但整体基线未重新导出）

## OpenAPI Spec 同步检查
- `compliance.api_changed`：true（`admin_registry.py` 为新增路由文件）
- `compliance.openapi_spec_stale`：true — ⚠️ 接口代码已变更但 OpenAPI spec 未同步
- 注：`admin_registry.py` 在之前对话中创建，本次对话未修改其逻辑，仅被 audit context 捕获为 high_risk_file。待后端启动后手动执行 `python scripts/ops/_export_openapi.py` 重新导出 spec。

## 文档同步检查
- `apps/backend/app/routers/admin_registry.py` 缺少对应文档同步：
  - `apps/backend/docs/API-REFERENCE.md`（已在之前对话中创建，包含注册体系端点）
  - `docs/contracts/openapi/backend-api.json`（待导出）

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260322_181225.md`
- `docs/audit/session_logs/2026-03/22/51_2eea8ffe_174707/main_01_361b984a.md`
- `docs/audit/session_logs/2026-03/22/51_2eea8ffe_174707/sub_01_361b984a.md`
- `docs/audit/session_logs/2026-03/22/52_08e70bf5_180519/main_01_9b253dd1.md`

### 删除文件
- `docs/audit/session_logs/2026-03/22/51_2eea8ffe_174707/main_01_e2059ea7.md`（被替换为 `main_01_361b984a.md`）

## 改动注解

### `apps/backend/app/routers/admin_registry.py`
- 变更类型：修改（被 audit context 标记为 high_risk）
- 原始原因：该文件在之前的对话（TASK 4: 修复"管辖门店"下拉为空）中创建，是管理端路由注册体系（连接器/租户/店铺/简写ID/店铺同步）的核心路由文件
- 思路分析：提供 6 个管理端 API 端点，包括租户列表、店铺列表、简写ID 设置/历史、店铺同步（手动+内部触发）。使用 ETL 库直连（无 RLS）进行跨站点数据同步
- 修改结果：本次对话中该文件实际未发生逻辑变更，仅因 git diff 基线差异被捕获。文件功能完整，已包含 JWT 鉴权 + 角色校验

### `docs/database/ddl/zqyy_app__public.sql`
- 变更类型：修改
- 原始原因：DDL 基线与测试库实际结构对比发现 `task_execution_log` 缺少 `config jsonb` 字段
- 思路分析：TASK 3（僵尸任务修复）中新增了 `config JSONB DEFAULT NULL` 列用于存储任务配置快照，但 DDL 基线文件未同步更新
- 修改结果：DDL 基线补齐，与测试库实际结构一致

### `docs/database/README.md`
- 变更类型：修改
- 原始原因：BD 手册全面审核走查发现表计数、DDL 基线日期、索引条目等多处过时
- 修改结果：auth 8→9 表、biz 7→18 表、dws 36→35 表，BD_Manual 索引扩展到 12 文件

### `docs/database/BD_Manual_auth_tables.md`
- 变更类型：修改
- 原始原因：NS4.1 注册体系迁移后新增了 `_archived_site_code_mapping` 和 `tenant_admins` 表，文档未同步
- 修改结果：表计数 8→9，新增条目，标记废弃约束

### `docs/database/BD_Manual_app_schema_rls_views.md`
- 变更类型：修改
- 原始原因：视图计数存在重复统计（`v_dws_assistant_recharge_commission`），P2 预留注释已过时
- 修改结果：DWS 视图 24→23，别名 6→7，删除过时注释，验证 SQL 更新

### `docs/database/BD_Manual_ai_tables.md`
- 变更类型：修改
- 原始原因：P15 迁移后 ai_run_logs 索引数变更，ai_conversations 字段数变更，验证 SQL 不准确
- 修改结果：验证 SQL 中的预期值全部修正为实际值

### `docs/database/BD_Manual_fdw_etl_setup.md`
- 变更类型：修改
- 原始原因：外部表数量随 DWS 层演进已从 38 增长到 46
- 修改结果：外部表计数 38→46，分类明细同步更新

### `docs/database/BD_Manual_fdw_reverse_retention_clue.md`
- 变更类型：修改
- 原始原因：`member_retention_clue` 表新增了 `is_hidden` 列，FDW 已知差异文档未记录
- 修改结果：新增 `is_hidden` 到已知差异列表

### `docs/database/BD_Manual_biz_tables.md`
- 变更类型：修改
- 原始原因：notes 表新增了 CHECK 约束，验证 SQL 预期值过时
- 修改结果：CHECK 约束验证 SQL 2→3 行

### `docs/database/BD_Manual_tenant_admins_deleted_at.md` → `docs/database/_archived/`
- 变更类型：移动/归档
- 原始原因：该文档内容已合并到 `BD_Manual_auth_tables.md` 主文档中，独立文件冗余
- 修改结果：移至 `_archived/` 目录，避免信息重复
