Neo
14a12342b5
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。
按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。
涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
DDL 基线合并 / Kiro 到 Claude Code 迁移
阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
126 lines
7.0 KiB
Markdown
126 lines
7.0 KiB
Markdown
# 审计记录：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: 续推进技术设计文档
|
||
```
|