chore(audit): 2026-04-20 历史批次预审 + 文档同步 + .gitignore 修正

- 新增 docs/audit/changes/2026-04-20__historical-batch-pre-audit.md 157 文件分批盘点审计（7 条主线 + 10 项高/中风险 + 2 份迁移 SQL DDL 清单） - 补追 docs/audit/changes/2026-04-15__meituan-settle-core-sync.md 原审计产物因 .gitignore 屏蔽长期未入仓，本次一并追回 - 刷新 docs/audit/audit_dashboard.md（33 条审计记录） - .gitignore 白名单放行 docs/audit/changes/*.md 与 audit_dashboard.md 同时屏蔽 changes/changes/ 嵌套误产物目录 - 新增 docs/specs/audit-gap-recovery/tasks.md 扫描嵌套目录发现 96 份 D 类孤本（从未入过 git history），生成独立 PRD 供单开任务清理与补追 - 文档同步（高风险项）： - apps/backend/docs/API-REFERENCE.md (+69) - apps/miniprogram/README.md (+50) - apps/etl/connectors/feiqiu/docs/architecture/data_flow.md (+52/-2) - apps/etl/connectors/feiqiu/docs/architecture/system_overview.md (+5/-3) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 06:32:58 +08:00
parent 2a7a5d68aa
commit 80bda9b991
9 changed files with 914 additions and 366 deletions
--- a/docs/audit/changes/2026-04-15__meituan-settle-core-sync.md
+++ b/docs/audit/changes/2026-04-15__meituan-settle-core-sync.md
@@ -0,0 +1,124 @@
+# 变更审计记录：美团结算导入 + core 层定位 + CORE_DIM_SYNC 任务
+
+| 字段 | 值 |
+|------|-----|
+| 日期 | 2026-04-15 01:41:01 |
+
+## 操作摘要
+
+本次变更包含 5 项关联改动，围绕"美团结算数据入库"和"core 维度层重新启用"两条主线展开：
+
+1. **美团结算数据导入**：在 dwd.dwd_groupbuy_redemption 新增 6 个 mt_* 字段（mt_settlement_price / mt_gross_income / mt_service_fee / mt_marketing_fee / mt_other_adjust / mt_import_time），通过临时表批量 UPDATE 导入 15,878 条结算价记录（95.4% 覆盖率，未匹配 759 条为非美团券码）。
+2. **core 层重新定位与数据填充**：明确 core 层为"跨平台统一维度层"（屏蔽 ODS/DWD 多数据源差异），对 core.dim_assistant / dim_member / dim_site / dim_project 执行 TRUNCATE+INSERT 全量填充，修复 app 视图空查询问题。
+3. **CORE_DIM_SYNC 新 ETL 任务**：新建 core_dim_sync_task.py 实现 DWD->core 全量刷新（TRUNCATE+INSERT 4 个维度表），注册到 ETL task_registry（depends_on=DWD_LOAD_FROM_ODS）和后端 task_registry（admin-web 展示），meta.etl_task 新增 task_id=69。
+4. **DWS_ASSISTANT_ORDER_CONTRIBUTION 补全**：该任务此前仅在 ETL 侧注册，本次补齐后端 task_registry 注册和 meta.etl_task 配置（task_id=68），并全量回刷 2025-09-01~2026-04-15 数据（2,207 条）。
+5. **文档同步**：db/README.md 补充 core 层说明，ETL 任务文档新增 Core 层段落，BD 手册补 6 个 mt_* 字段说明。
+
+## 变更文件
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `apps/etl/connectors/feiqiu/tasks/dws/core_dim_sync_task.py` | CORE_DIM_SYNC 任务实现（TRUNCATE+INSERT 4 个维度表） |
+
+### 修改
+
+| 文件 | 说明 |
+|------|------|
+| `db/etl_feiqiu/schemas/dwd.sql` | DDL 基线同步：dwd_groupbuy_redemption 新增 6 个 mt_* 字段 |
+| `db/etl_feiqiu/schemas/app.sql` | 视图定义同步（保持指向 core） |
+| `db/etl_feiqiu/schemas/core.sql` | 注释更新：core 层定位说明 |
+| `db/README.md` | core 层补充说明 |
+| `apps/etl/connectors/feiqiu/tasks/dws/__init__.py` | 导出 CoreDimSyncTask |
+| `apps/etl/connectors/feiqiu/orchestration/task_registry.py` | 注册 CORE_DIM_SYNC（task_id=69, depends_on=DWD_LOAD_FROM_ODS） |
+| `apps/backend/app/services/task_registry.py` | 注册 CORE_DIM_SYNC + DWS_ASSISTANT_ORDER_CONTRIBUTION 到 admin-web 展示 |
+| `apps/etl/connectors/feiqiu/docs/etl_tasks/README.md` | 新增 Core 层段落 |
+| `apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dwd_groupbuy_redemption.md` | 补充 6 个 mt_* 字段说明 |
+
+## 改动注解
+
+### 高风险
+
+- **db/etl_feiqiu/schemas/dwd.sql**：ALTER TABLE 新增 6 列均为 NULLABLE，无破坏性。DDL 基线已同步数据库现状。数据通过临时表 UPDATE 导入，非 ETL 自动流程。
+- **db/etl_feiqiu/schemas/app.sql**：app.v_assistant / v_member / v_site 视图保持原始定义（指向 core.dim_*），core 表已填充数据，视图查询恢复正常。
+- **db/etl_feiqiu/schemas/core.sql**：注释变更，无结构变更。core 层定位从"待废弃"改为"跨平台统一维度层"。
+- **apps/etl/connectors/feiqiu/orchestration/task_registry.py**：新增 CORE_DIM_SYNC 注册项，depends_on=DWD_LOAD_FROM_ODS 确保在 DWD 加载后执行。
+- **apps/backend/app/services/task_registry.py**：新增 2 项展示注册（CORE_DIM_SYNC + DWS_ASSISTANT_ORDER_CONTRIBUTION），不影响已有任务。
+
+### 普通
+
+- **apps/etl/connectors/feiqiu/tasks/dws/core_dim_sync_task.py**：新建文件，TRUNCATE+INSERT 全量刷新模式，4 个维度表映射关系明确。
+- **apps/etl/connectors/feiqiu/tasks/dws/__init__.py**：仅添加导出行。
+- **db/README.md**：文档补充。
+- **apps/etl/connectors/feiqiu/docs/**：ETL 文档同步，无逻辑影响。
+
+## 数据库变更
+
+### etl_feiqiu 库
+
+| 操作 | 对象 | 详情 | 执行状态 |
+|------|------|------|----------|
+| ALTER TABLE | `dwd.dwd_groupbuy_redemption` | 新增 6 列：mt_settlement_price (numeric(10,2)), mt_gross_income (numeric(10,2)), mt_service_fee (numeric(10,2)), mt_marketing_fee (numeric(10,2)), mt_other_adjust (numeric(10,2)), mt_import_time (timestamptz) | 已执行 |
+| TRUNCATE+INSERT | `core.dim_assistant` | 从 DWD 全量填充 | 已执行 |
+| TRUNCATE+INSERT | `core.dim_member` | 从 DWD 全量填充 | 已执行 |
+| TRUNCATE+INSERT | `core.dim_site` | 从 DWD 全量填充 | 已执行 |
+| TRUNCATE+INSERT | `core.dim_project` | 从 DWD 全量填充 | 已执行 |
+| INSERT | `meta.etl_task` | task_id=68 (DWS_ASSISTANT_ORDER_CONTRIBUTION) | 已执行 |
+| INSERT | `meta.etl_task` | task_id=69 (CORE_DIM_SYNC) | 已执行 |
+| CREATE OR REPLACE VIEW | `app.v_assistant / v_member / v_site` | 确认保持指向 core.dim_*（无变更） | 已验证 |
+
+## 风险与回滚
+
+### 风险点
+
+| 级别 | 风险 | 缓解 |
+|------|------|------|
+| 中 | mt_* 字段通过临时表手工导入，非 ETL 自动化流程，后续美团结算单需手动重跑 | 后续可考虑封装为 scripts/ops/ 脚本 |
+| 中 | CORE_DIM_SYNC 使用 TRUNCATE+INSERT 全量刷新，执行期间 core 表短暂为空 | 任务执行时间极短（4 个维度表数据量小），可接受 |
+| 低 | DWS_ASSISTANT_ORDER_CONTRIBUTION 回刷数据量大（2,207 条跨 7 个月） | 已验证数据正确性 |
+
+### 回滚要点
+
+1. mt_* 字段回滚：`ALTER TABLE dwd.dwd_groupbuy_redemption DROP COLUMN mt_settlement_price, DROP COLUMN mt_gross_income, DROP COLUMN mt_service_fee, DROP COLUMN mt_marketing_fee, DROP COLUMN mt_other_adjust, DROP COLUMN mt_import_time;`
+2. CORE_DIM_SYNC 回滚：删除 core_dim_sync_task.py，从两个 task_registry 移除注册项，`DELETE FROM meta.etl_task WHERE task_id = 69;`
+3. DWS_ASSISTANT_ORDER_CONTRIBUTION 回滚：从后端 task_registry 移除，`DELETE FROM meta.etl_task WHERE task_id = 68;`
+
+## 验证
+
+```sql
+-- 1. 验证 mt_* 字段导入覆盖率
+SELECT
+  COUNT(*) AS total,
+  COUNT(mt_settlement_price) AS has_settle,
+  ROUND(COUNT(mt_settlement_price)::numeric / COUNT(*) * 100, 1) AS pct
+FROM dwd.dwd_groupbuy_redemption;
+
+-- 2. 验证 core 维度表非空
+SELECT 'dim_assistant' AS tbl, COUNT(*) FROM core.dim_assistant
+UNION ALL SELECT 'dim_member', COUNT(*) FROM core.dim_member
+UNION ALL SELECT 'dim_site', COUNT(*) FROM core.dim_site
+UNION ALL SELECT 'dim_project', COUNT(*) FROM core.dim_project;
+
+-- 3. 验证 app 视图正常返回数据
+SELECT COUNT(*) FROM app.v_assistant;
+SELECT COUNT(*) FROM app.v_member;
+
+-- 4. 验证 meta.etl_task 新增记录
+SELECT task_id, task_name, is_active FROM meta.etl_task WHERE task_id IN (68, 69);
+
+-- 5. 验证 DWS_ASSISTANT_ORDER_CONTRIBUTION 回刷数据
+SELECT COUNT(*), MIN(stat_date), MAX(stat_date)
+FROM dws.dws_assistant_order_contribution;
+```
+
+## 合规检查
+
+| 项目 | 状态 |
+|------|------|
+| DDL 基线同步（db/etl_feiqiu/schemas/） | 已完成：dwd.sql, app.sql, core.sql 已更新 |
+| db/README.md 文档同步 | 已完成：core 层说明已补充 |
+| ETL 任务文档同步 | 已完成：docs/etl_tasks/README.md 新增 Core 层段落 |
+| BD 手册同步 | 已完成：BD_manual_dwd_groupbuy_redemption.md 补 mt_* 字段 |
+| 后端 task_registry 同步 | 已完成：CORE_DIM_SYNC + DWS_ASSISTANT_ORDER_CONTRIBUTION 已注册 |
+| RLS 视图双 Schema 规则 | 不涉及：本次无新建视图，现有视图保持不变 |