# 审计记录：ETL Bug 修复 — dim_staff_ex 列映射 + assistant_daily table_area_name

- 日期：2026-02-26 20:44:35
- Prompt-ID：`P20260226-191453`
- 风险标签：`root-file`, `dir:admin-web`, `dir:backend`, `dir:etl`, `dir:db`, `db-schema-change`
- 变更统计：152 files changed, 6895 insertions(+), 216697 deletions(-)
- 审计范围：本次审计聚焦于两个 ETL bug 修复及配套 BD Manual 文档

## 变更概述

本次变更修复两个 ETL 运行时 bug，均导致 `FLOW_API_FULL` 执行失败：

1. **dim_staff_ex 列映射错误**：`dwd_load_task.py` 中 `FACT_MAPPINGS["dwd.dim_staff_ex"]` 的 ODS 源列名 `"rankname"` 应为 `"rank_name"`，导致 PostgreSQL 报 `UndefinedColumn` 错误，dim_staff_ex SCD2 合并每个窗口段均失败
2. **assistant_daily table_area_name 不存在**：`assistant_daily_task.py` 的 `_extract_service_records()` SQL 引用 `asl.table_area_name`，但 `dwd.dwd_assistant_service_log` 表无此列，导致 DWS_ASSISTANT_DAILY 失败并级联 13 个后续 DWS/INDEX 任务全部 `InFailedSqlTransaction`

### 影响范围

| 子系统 | 影响 |
|--------|------|
| ETL DWD 层 | dim_staff_ex 恢复正常加载，rank_name 字段正确映射 |
| ETL DWS 层 | dws_assistant_daily 恢复正常，table_area_name 改从 dim_table 维度表获取；级联失败消除 |
| 后端 API | 无影响 |
| DDL | 无变更 |

## 本次对话文件变更（session_diff）

### 新增文件
- `NeoZQYY.z01`
- `NeoZQYY.z02`
- `NeoZQYY.z03`
- `NeoZQYY.z04`
- `docs/audit/prompt_logs/prompt_log_20260226_191453.md`
- `docs/audit/session_logs/session_20260226_201650.md`

### 修改文件
- `NeoZQYY.zip`
- `apps/backend/app/config.py`
- `apps/backend/app/routers/xcx_auth.py`
- `apps/backend/app/schemas/xcx_auth.py`
- `apps/backend/app/services/wechat.py`
- `tests/test_auth_system_properties.py`

## DDL / 迁移检查

- `compliance.new_migration_sql`：空（无新增迁移）
- ⚠️ DDL 基线待合并（`has_ddl_baseline: false`）
- BD Manual 已创建：
  - `docs/database/BD_Manual_fix_dim_staff_ex_rankname.md`
  - `docs/database/BD_Manual_fix_dws_assistant_daily_table_area.md`
  - `docs/database/BD_Manual_assistant_service_records.md`（更新映射修正记录表）

## OpenAPI Spec 同步检查

- ⚠️ 接口代码已变更但 OpenAPI spec 可能未同步（`api_changed: true`, `openapi_spec_stale: true`）
- 注：本次审计聚焦 ETL bug 修复，接口变更属于前序 session 的维客线索重构 + 小程序鉴权，已在 `2026-02-26__retention-clue-refactor.md` 和 `2026-02-26__p1-p2-p3-fullstack-integration.md` 中审计
- 待手动操作：运行 `python scripts/ops/_export_openapi.py` 重新导出 spec，导出成功后重连 OpenAPI Power MCP server

## 文档同步检查（compliance.code_without_docs）

| 代码文件 | 缺失文档 | 状态 |
|----------|----------|------|
| `apps/backend/app/routers/xcx_auth.py` | `apps/backend/docs/API-REFERENCE.md`, `docs/contracts/openapi/backend-api.json` | ⚠️ 待同步（属前序小程序鉴权变更） |
| `apps/backend/app/schemas/xcx_auth.py` | `docs/contracts/openapi/backend-api.json` | ⚠️ 待同步（同上） |
| `apps/backend/app/services/wechat.py` | `apps/backend/docs/API-REFERENCE.md`, `apps/backend/README.md` | ⚠️ 待同步（同上） |

注：上述文档缺失均为前序 session 的小程序鉴权变更引入，非本次 ETL bug 修复范围。建议在下次接口相关审计时统一补齐。

## 改动注解

### `apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
- 变更类型：修改
- 原始原因：`FLOW_API_FULL` 执行时 `DWD_LOAD_FROM_ODS` 阶段 dim_staff_ex 加载失败，PostgreSQL 报 `UndefinedColumn: 字段 "rankname" 不存在`
- 思路分析：`FACT_MAPPINGS["dwd.dim_staff_ex"]` 中映射元组 `(dwd_列名, ods_源列名, 类型转换)` 的第二个元素应与 ODS 表 `ods.staff_info_master` 的实际列名一致。ODS 表列名为 `rank_name`（带下划线），而非 `rankname`（驼峰转蛇形时遗漏下划线）
- 修改结果：`("rank_name", "rankname", None)` → `("rank_name", "rank_name", None)`，dim_staff_ex SCD2 合并恢复正常

### `apps/etl/connectors/feiqiu/tasks/dws/assistant_daily_task.py`
- 变更类型：修改
- 原始原因：`_extract_service_records()` SQL 引用 `asl.table_area_name`，但 `dwd.dwd_assistant_service_log` 表无此列（DDL 可确认），导致 DWS_ASSISTANT_DAILY 失败并级联 13 个后续任务
- 思路分析：台区名称应从维度表 `dwd.dim_table` 的 `site_table_area_name` 字段获取，通过 `asl.site_table_id = dt.table_id AND dt.scd2_is_current = 1` 关联。使用 `COALESCE(..., '')` 处理无匹配情况，避免 NULL 传播
- 修改结果：新增 `LEFT JOIN dwd.dim_table dt`，`asl.table_area_name` 替换为 `COALESCE(dt.site_table_area_name, '') AS table_area_name`，DWS 阶段全部任务恢复正常执行

### `docs/database/BD_Manual_fix_dim_staff_ex_rankname.md`
- 变更类型：新增
- 原始原因：为 dim_staff_ex 列映射修复创建 BD Manual 变更记录，确保可追溯
- 思路分析：记录错误原因、修复方式、兼容性影响、回滚策略和验证 SQL
- 修改结果：完整的变更文档，含 4 条验证 SQL 可直接在测试库执行

### `docs/database/BD_Manual_fix_dws_assistant_daily_table_area.md`
- 变更类型：新增
- 原始原因：为 assistant_daily table_area_name 修复创建 BD Manual 变更记录
- 思路分析：记录级联失败机制、JOIN 条件设计、回滚策略和验证 SQL
- 修改结果：完整的变更文档，含级联失败的 13 个任务清单和 4 条验证 SQL

### `docs/database/BD_Manual_assistant_service_records.md`
- 变更类型：修改
- 原始原因：在映射修正记录表中补充 2026-02-26 的下游 table_area_name 修正条目
- 思路分析：该文档是 assistant_service_records 的主映射文档，下游 DWS 任务对该表字段的引用修正应在此记录
- 修改结果：映射修正记录表新增一行，交叉引用 `BD_Manual_fix_dws_assistant_daily_table_area.md`

### `apps/backend/app/config.py`
- 变更类型：修改（session_diff.modified）
- 简要注解：新增 `WX_APPID`、`WX_SECRET`、`WX_DEV_MODE` 配置项，属前序小程序鉴权变更

### `apps/backend/app/routers/xcx_auth.py`
- 变更类型：修改（session_diff.modified）
- 简要注解：新增 `POST /api/xcx/dev-login` 开发模式 mock 登录端点，属前序小程序鉴权变更

### `apps/backend/app/schemas/xcx_auth.py`
- 变更类型：修改（session_diff.modified）
- 简要注解：新增 `DevLoginRequest` Pydantic 模型，属前序小程序鉴权变更

### `apps/backend/app/services/wechat.py`
- 变更类型：修改（session_diff.modified）
- 简要注解：`code2session()` 改为从模块级常量读取 `WX_APPID`/`WX_SECRET`，属前序小程序鉴权变更

### `tests/test_auth_system_properties.py`
- 变更类型：修改（session_diff.modified）
- 简要注解：鉴权系统属性测试更新，属前序小程序鉴权变更

## Prompt 溯源

```
- [P20260226-191453] 2026-02-26 19:14:53 +0800
  - summary: 续推进技术设计文档
```
