225 lines
9.7 KiB
Markdown
225 lines
9.7 KiB
Markdown
# 设计文档：助教废除（Abolish）全链路清理
|
||
|
||
## 概述
|
||
|
||
本设计描述如何安全地从 ETL 全链路中移除"助教废除"独立数据链路。
|
||
核心思路：**删除独立的废除链路（API → ODS → DWD），保留服务记录中已有的 `is_trash` 字段作为唯一废除判断源。**
|
||
|
||
清理范围覆盖：
|
||
- ETL 任务定义（ODS 任务 + 注册表）
|
||
- DWD 加载映射（FACT_MAPPINGS + TABLE_MAP）
|
||
- DWS 聚合逻辑（死代码移除）
|
||
- DWD 验证器配置
|
||
- 数据库 DDL 和迁移脚本
|
||
- 属性测试
|
||
- 运维脚本
|
||
|
||
## 架构
|
||
|
||
### 清理前数据流
|
||
|
||
```mermaid
|
||
graph LR
|
||
API_Abolish["/AssistantPerformance/GetAbolitionAssistant"] --> ODS_ACR["ods.assistant_cancellation_records"]
|
||
ODS_ACR --> DWD_ATE["dwd.dwd_assistant_trash_event"]
|
||
ODS_ACR --> DWD_ATE_EX["dwd.dwd_assistant_trash_event_ex"]
|
||
DWD_ATE --> |"_extract_trash_records (死代码)"| DWS_DAILY["dws.dws_assistant_daily_detail"]
|
||
|
||
API_Service["/AssistantPerformance/GetAssistantServiceRecords"] --> ODS_ASR["ods.assistant_service_records"]
|
||
ODS_ASR --> DWD_SL_EX["dwd.dwd_assistant_service_log_ex"]
|
||
DWD_SL_EX --> |"is_trash 字段 (实际使用)"| DWS_DAILY
|
||
|
||
style API_Abolish fill:#f99,stroke:#c00
|
||
style ODS_ACR fill:#f99,stroke:#c00
|
||
style DWD_ATE fill:#f99,stroke:#c00
|
||
style DWD_ATE_EX fill:#f99,stroke:#c00
|
||
```
|
||
|
||
### 清理后数据流
|
||
|
||
```mermaid
|
||
graph LR
|
||
API_Service["/AssistantPerformance/GetAssistantServiceRecords"] --> ODS_ASR["ods.assistant_service_records"]
|
||
ODS_ASR --> DWD_SL_EX["dwd.dwd_assistant_service_log_ex"]
|
||
DWD_SL_EX --> |"is_trash 字段"| DWS_DAILY["dws.dws_assistant_daily_detail"]
|
||
|
||
style API_Service fill:#9f9,stroke:#090
|
||
style DWD_SL_EX fill:#9f9,stroke:#090
|
||
```
|
||
|
||
## 组件与接口
|
||
|
||
### 需要修改的文件清单
|
||
|
||
| 层级 | 文件 | 操作 | 需求 |
|
||
|------|------|------|------|
|
||
| ODS 任务 | `tasks/ods/ods_tasks.py` | 删除 `OdsTaskSpec` 条目 + 从默认序列移除 | 1.2, 1.3 |
|
||
| 任务注册 | `orchestration/task_registry.py` | 删除 `ODS_ASSISTANT_ABOLISH` 注册 | 1.1 |
|
||
| DWD 加载 | `tasks/dwd/dwd_load_task.py` | 删除 FACT_MAPPINGS 和 TABLE_MAP 条目 | 2.1–2.4 |
|
||
| DWS 日度 | `tasks/dws/assistant_daily_task.py` | 删除 `_extract_trash_records`、`_build_trash_index`，简化 `_aggregate_by_assistant_date` 签名 | 3.1–3.4 |
|
||
| DWD 验证 | `tasks/verification/dwd_verifier.py` | 删除废除表的 ID 和时间字段映射 | 4.1–4.4 |
|
||
| DDL | `db/etl_feiqiu/schemas/dwd.sql` | 删除 `dwd_assistant_trash_event` / `_ex` 的 CREATE TABLE + COMMENT | 6.1–6.2 |
|
||
| DDL | `db/etl_feiqiu/schemas/ods.sql` | 删除 `assistant_cancellation_records` 的 CREATE TABLE + COMMENT | 6.3 |
|
||
| DDL | `db/etl_feiqiu/schemas/schema_dwd_doc.sql` | 删除废除表的 CREATE TABLE + COMMENT | 6.4 |
|
||
| DDL | `db/etl_feiqiu/schemas/schema_ODS_doc.sql` | 删除废除表的 CREATE TABLE + COMMENT | 6.5 |
|
||
| DDL | `db/etl_feiqiu/schemas/dws.sql` | 更新 `dws_assistant_daily_detail` 注释 | 6.6 |
|
||
| DDL | `db/etl_feiqiu/schemas/schema_dws.sql` | 更新 `dws_assistant_daily_detail` 注释 | 6.7 |
|
||
| 迁移 | `db/etl_feiqiu/migrations/` | 新建 DROP TABLE 迁移脚本 | 5.1–5.5 |
|
||
| 属性测试 | `tests/test_property_1_fact_mappings.py` | 删除 `_REQ3_EXPECTED` 和相关引用 | 7.1–7.3 |
|
||
| 运维 | `scripts/ops/dataflow_analyzer.py` | 删除 `ODS_ASSISTANT_ABOLISH` spec 条目 | 8.1 |
|
||
| 运维 | `scripts/ops/gen_full_dataflow_doc.py` | 删除 `ODS_ASSISTANT_ABOLISH` spec 条目 | 8.1 |
|
||
| 运维 | `scripts/ops/etl_consistency_check.py` | 删除废除相关映射 | 8.1–8.2 |
|
||
| 运维 | `scripts/ops/blackbox_test_report.py` | 删除废除相关映射 | 8.1–8.4 |
|
||
| 运维 | `scripts/ops/field_audit.py` | 删除废除表审计条目 | 8.3–8.4 |
|
||
| 运维 | `scripts/ops/gen_field_review_doc.py` | 删除废除表字段定义 | 8.3–8.4 |
|
||
| 运维 | `scripts/ops/gen_api_field_mapping.py` | 从 ODS_TABLES 列表移除 | 8.3 |
|
||
| 运维 | `scripts/ops/export_dwd_field_review.py` | 删除废除表条目 | 8.4 |
|
||
| 运维 | `scripts/ops/check_ods_latest_indexes.py` | 删除废除表索引检查 | 8.3 |
|
||
|
||
### 不需要修改的文件（确认安全）
|
||
|
||
| 文件 | 原因 |
|
||
|------|------|
|
||
| `dwd_assistant_service_log_ex` 表 DDL | 保留 `is_trash` 等字段（需求 9） |
|
||
| `ods.assistant_service_records` 表 DDL | 保留 `is_trash` 等字段（需求 9） |
|
||
| `assistant_monthly_task.py` | 仅消费 `dws_assistant_daily_detail` 的 `trashed_seconds`/`trashed_count`，不直接引用废除表 |
|
||
| `assistant_salary_task.py` | 仅消费 `dws_assistant_monthly_summary`，不直接引用废除表 |
|
||
|
||
## 数据模型
|
||
|
||
### 被删除的表
|
||
|
||
```sql
|
||
-- ODS 层
|
||
ods.assistant_cancellation_records -- 78 条记录
|
||
|
||
-- DWD 层
|
||
dwd.dwd_assistant_trash_event -- 主表
|
||
dwd.dwd_assistant_trash_event_ex -- 扩展表
|
||
```
|
||
|
||
### 保留的废除相关字段
|
||
|
||
```sql
|
||
-- ods.assistant_service_records 中（保留）
|
||
is_trash INT -- 废除标记
|
||
trash_reason TEXT -- 废除原因
|
||
trash_applicant_id BIGINT -- 废除申请人 ID
|
||
trash_applicant_name TEXT -- 废除申请人姓名
|
||
|
||
-- dwd.dwd_assistant_service_log_ex 中（保留）
|
||
is_trash INTEGER -- 废除标记
|
||
trash_applicant_id BIGINT -- 废除申请人 ID
|
||
trash_applicant_name VARCHAR(64) -- 废除申请人姓名
|
||
trash_reason VARCHAR(255) -- 废除原因
|
||
```
|
||
|
||
### DWS 层字段（保留，数据来源变更说明）
|
||
|
||
```sql
|
||
-- dws.dws_assistant_daily_detail（保留，注释需更新）
|
||
trashed_seconds INTEGER -- 数据来源：dwd_assistant_service_log_ex.is_trash + income_seconds
|
||
trashed_count INTEGER -- 数据来源：dwd_assistant_service_log_ex.is_trash 计数
|
||
|
||
-- dws.dws_assistant_monthly_summary（保留）
|
||
trashed_hours NUMERIC(10,2) -- 来自 daily_detail.trashed_seconds 汇总
|
||
```
|
||
|
||
## DWS 代码重构细节
|
||
|
||
### assistant_daily_task.py 变更
|
||
|
||
**删除方法：**
|
||
- `_extract_trash_records()` — 查询 `dwd.dwd_assistant_trash_event` 的 SQL，已无消费者
|
||
- `_build_trash_index()` — 构建废除索引，已不参与判断逻辑
|
||
|
||
**修改方法：**
|
||
- `extract()` — 移除对 `_extract_trash_records` 的调用，移除 `trash_records` 变量
|
||
- `transform()` 或调用 `_aggregate_by_assistant_date` 的地方 — 移除 `trash_index` 参数传递
|
||
- `_aggregate_by_assistant_date()` — 从签名中移除 `trash_index` 参数；`is_trash` 判断逻辑保持不变
|
||
|
||
**不变逻辑：**
|
||
```python
|
||
# 这段逻辑保持不变——通过 is_trash 字段判断废除
|
||
is_trashed = bool(record.get('is_trash', 0))
|
||
if is_trashed:
|
||
agg['trashed_seconds'] += income_seconds
|
||
agg['trashed_count'] += 1
|
||
```
|
||
|
||
|
||
## 正确性属性
|
||
|
||
*正确性属性是一种在系统所有有效执行中都应成立的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1：废除聚合逻辑正确性（is_trash 驱动）
|
||
|
||
*对任意*服务记录集合，其中每条记录包含 `is_trash` 标记和 `income_seconds` 值，聚合后：
|
||
- `trashed_seconds` 应等于所有 `is_trash=1` 记录的 `income_seconds` 之和
|
||
- `trashed_count` 应等于所有 `is_trash=1` 记录的数量
|
||
- `total_service_count` 应等于所有 `is_trash=0` 记录的数量
|
||
- `total_seconds` 应等于所有 `is_trash=0` 记录的 `income_seconds` 之和
|
||
|
||
**Validates: Requirements 3.4, 9.3**
|
||
|
||
### Property 2：FACT_MAPPINGS 一致性（已有属性测试的回归验证）
|
||
|
||
*对任意* FACT_MAPPINGS 中的表名，该表名应在 TABLE_MAP 中有对应的 ODS 源表映射，且映射的每个 DWD 列名应为合法的 SQL 标识符。
|
||
|
||
**Validates: Requirements 2.1–2.4, 7.3**
|
||
|
||
> 注：此属性已由 `tests/test_property_1_fact_mappings.py` 实现。清理后需确保该测试仍然通过。
|
||
|
||
## 错误处理
|
||
|
||
### 迁移脚本安全性
|
||
|
||
- 所有 `DROP TABLE` 语句使用 `IF EXISTS`，确保幂等执行
|
||
- 迁移脚本在单个事务中执行，失败时自动回滚
|
||
- 迁移脚本包含注释说明移除原因，便于审计追溯
|
||
|
||
### 代码删除安全性
|
||
|
||
- 删除 `_extract_trash_records` 和 `_build_trash_index` 前，确认无其他调用者
|
||
- `_aggregate_by_assistant_date` 移除 `trash_index` 参数后，确认所有调用点已同步更新
|
||
- 保留 `is_trash` 判断逻辑不变，确保废除统计功能不受影响
|
||
|
||
### 回滚策略
|
||
|
||
- DDL 变更通过迁移脚本管理，可通过反向迁移（CREATE TABLE）回滚
|
||
- 代码变更通过 Git 版本控制回滚
|
||
- ODS 表数据在删除前可选择性备份（数据量小，仅 78 条）
|
||
|
||
## 测试策略
|
||
|
||
### 属性测试
|
||
|
||
- 使用 `hypothesis` 库进行属性测试
|
||
- 每个属性测试至少运行 100 次迭代
|
||
- 每个测试用注释标注对应的设计属性编号
|
||
|
||
**Property 1 测试方案：**
|
||
- 生成随机服务记录列表（包含随机 `is_trash` 标记和 `income_seconds` 值）
|
||
- 调用 `_aggregate_by_assistant_date` 方法
|
||
- 验证 `trashed_seconds`/`trashed_count` 与手动计算的期望值一致
|
||
- 标签：`Feature: assistant-abolish-cleanup, Property 1: 废除聚合逻辑正确性`
|
||
|
||
**Property 2 测试方案：**
|
||
- 已由 `tests/test_property_1_fact_mappings.py` 覆盖
|
||
- 清理后运行 `pytest tests/ -v` 确认无回归
|
||
- 标签：`Feature: assistant-abolish-cleanup, Property 2: FACT_MAPPINGS 一致性`
|
||
|
||
### 单元测试
|
||
|
||
- 验证 `AssistantDailyTask` 不再有 `_extract_trash_records` 和 `_build_trash_index` 方法
|
||
- 验证 `_aggregate_by_assistant_date` 签名不包含 `trash_index` 参数
|
||
- 验证 FACT_MAPPINGS 不包含废除表条目
|
||
- 验证 TABLE_MAP 不包含废除表映射
|
||
- 验证 DwdVerifier 配置不包含废除表
|
||
|
||
### 集成验证
|
||
|
||
- 运行现有属性测试套件：`pytest tests/ -v`
|
||
- 运行 ETL 单元测试：`cd apps/etl/connectors/feiqiu && pytest tests/unit`
|
||
- 确认所有测试通过，无回归
|