在前后端开发联调前 的提交20260223
This commit is contained in:
224
.kiro/specs/assistant-abolish-cleanup/design.md
Normal file
224
.kiro/specs/assistant-abolish-cleanup/design.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 设计文档：助教废除（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`
|
||||
- 确认所有测试通过，无回归
|
||||
Reference in New Issue
Block a user