Neo-ZQYY/docs/audit/changes/2026-03-22__ddl-db-structure-diff-bd-manual-audit.md

变更审计记录：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/ 目录，避免信息重复