# 变更审计记录：美团结算导入 + 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 规则 | 不涉及：本次无新建视图，现有视图保持不变 |