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>
89 lines
5.4 KiB
Markdown
89 lines
5.4 KiB
Markdown
# 变更审计记录：财务看板 DWS 区域维度重构审计
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-28 23:35:22 |
|
||
| Prompt-ID | P20260328-233107 |
|
||
| Session-ID | a3db0ed6 |
|
||
| Session 路径 | docs/audit/session_logs/2026-03/28/21_c1352cc4_224728 |
|
||
|
||
## 操作摘要
|
||
|
||
本次对话执行了助教姓名显示规范修正（强制使用昵称/花名），同时涉及 board-finance DWS 区域维度重构 spec 关联的多模块变更：后端 fdw_queries.py ETL 连接复用改造 + trace 装饰器 + 薪资计算字段扩展，小程序 board-customer 页面 Mock→真实 API 迁移 + 筛选枚举值修正，以及前后端联调规范文档更新。
|
||
|
||
Session 索引中的关联 session（89a28deb，同一 chatSessionId c1352cc4）还包含：board-detail-gap-analysis.md PRD 编写、board-coach 页面修改、test_board_api.py 测试脚本创建。
|
||
|
||
## 风险标签
|
||
|
||
`root-file` · `dir:admin-web` · `dir:backend` · `dir:etl` · `dir:miniprogram` · `dir:db` · `db-schema-change` · `dir:shared`
|
||
|
||
## 高风险文件
|
||
|
||
| 文件 | 变更类型 |
|
||
|------|----------|
|
||
| `apps/backend/app/services/fdw_queries.py` | 修改 |
|
||
| `apps/backend/app/ai/data_fetchers/member_data.py` | 修改 |
|
||
| `apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts` | 修改 |
|
||
|
||
## 本次对话文件变更
|
||
|
||
### 新增文件
|
||
- `docs/audit/prompt_logs/prompt_log_20260328_233107.md`
|
||
- `docs/audit/session_logs/2026-03/28/21_c1352cc4_224728/main_01_89a28deb.md`
|
||
- `docs/audit/session_logs/2026-03/28/21_c1352cc4_224728/sub_01_89a28deb.md`
|
||
|
||
### 删除文件
|
||
- `docs/audit/session_logs/2026-03/28/21_c1352cc4_224728/main_01_fb0eb0c8.md`（被 89a28deb 版本替代）
|
||
|
||
## 改动注解
|
||
|
||
### `apps/backend/app/services/fdw_queries.py`
|
||
- 变更类型：修改
|
||
- 原始原因：用户要求所有助教使用昵称/花名显示，同时该文件在 board-finance DWS 区域重构 spec 中承担后端查询改造职责。近期多轮迭代（3/24 档位配置、3/25 保底关系对、3/27 财务看板集成 T2.1-T2.3）持续扩展该文件。
|
||
- 思路分析：
|
||
1. ETL 连接复用：`_fdw_context` 新增 `etl_conn` 可选参数，传入时复用已有连接（不关闭），不传时新建并自动关闭。避免同一请求内多次新建连接（每次 ~2.6s）。
|
||
2. `@trace_service` 装饰器：为 `get_member_info`、`get_member_balance`、`get_last_visit_days`、`get_salary_calc` 等函数添加链路追踪。
|
||
3. 薪资计算扩展：`get_salary_calc` 新增 `top_rank_bonus`、`recharge_commission`、`other_bonus`、`base_deduction`、`bonus_deduction_ratio` 五个字段，用于 performance 页收入明细和到手费率计算。
|
||
4. 新增 `get_monthly_summary` 等函数支持财务看板数据查询。
|
||
- 修改结果：所有 fdw_queries 函数支持 ETL 连接复用，减少查询延迟；薪资计算返回完整奖金拆分数据；新增链路追踪便于性能监控。影响 board_service.py、customer_service.py、performance_service.py 等调用方。
|
||
|
||
### `apps/backend/app/ai/data_fetchers/member_data.py`
|
||
- 变更类型：修改
|
||
- 原始原因：助教姓名显示规范修正——SQL 查询中助教姓名字段需改为 `COALESCE(nickname, real_name, '')` 优先使用昵称。
|
||
- 思路分析：AI 数据获取器中涉及助教信息的查询，统一修改为昵称优先策略，与前端展示规范保持一致。
|
||
- 修改结果：AI 模块获取的助教数据将优先显示昵称/花名，不再泄露真实姓名。
|
||
|
||
### `apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts`
|
||
- 变更类型：修改
|
||
- 原始原因：P5 联调阶段将 Mock 数据替换为真实 API 调用；P9 修正前端筛选枚举值与后端不一致的问题（踩坑记录 2026-03-28）。
|
||
- 思路分析：
|
||
1. Mock→API 迁移：引入 `fetchBoardCustomers` 替代硬编码 Mock 数据，Mock 数据保留为空骨架项（用于排查字段为空时的渲染表现）。
|
||
2. 枚举值修正：`PROJECT_OPTIONS` 的 value 从小写（`all/chinese/snooker/mahjong/karaoke`）改为大写数据库 category_code（`ALL/BILLIARD/SNOOKER/MAHJONG/KTV`），与 board-coach 的 `SKILL_OPTIONS` 保持同步。
|
||
3. 权限守卫：`onShow` 添加 `checkPageAccess` + `getVisibleBoardTabs` 调用。
|
||
4. AI_CHANGELOG 头部注释：记录变更历史。
|
||
- 修改结果：客户看板页面完成真实数据对接，筛选功能与后端枚举一致，权限守卫生效。
|
||
|
||
### 非高风险文件简要注解
|
||
- `docs/prd/specs/board-detail-gap-analysis.md` — 新建 PRD 文档，记录看板详情页与原型的差距分析
|
||
- `.kiro/steering/frontend-backend-integration.md` — 更新前后端联调规范，新增助教姓名显示规则、枚举同步踩坑记录等
|
||
- `docs/audit/session_logs/` 下多个 `_day_index.json` — Session 索引日常更新（自动生成）
|
||
|
||
## 合规检查
|
||
|
||
| 检查项 | 状态 |
|
||
|--------|------|
|
||
| 新增迁移 SQL | 无（本次对话未新增迁移脚本） |
|
||
| DDL 基线 | ⚠️ DDL 基线待合并（has_ddl_baseline: false） |
|
||
| BD 手册 | ⚠️ 未同步更新（has_bd_manual: false） |
|
||
| API 接口变更 | 无 |
|
||
| OpenAPI Spec | 无需更新 |
|
||
|
||
## 文档同步缺失
|
||
|
||
| 代码文件 | 应同步更新的文档 |
|
||
|----------|-----------------|
|
||
| `apps/backend/app/services/fdw_queries.py` | `apps/backend/docs/API-REFERENCE.md`、`apps/backend/README.md` |
|
||
| `apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts` | `apps/miniprogram/README.md` |
|
||
|
||
> 注：上述文档同步项来自 compliance prescan，建议在下次提交前补齐。
|