Files

Neo 14a12342b5 chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08

这些审计记录原本堆积在 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>

2026-04-20 06:35:42 +08:00

5.4 KiB

Raw Blame History

变更审计记录：财务看板 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，建议在下次提交前补齐。

5.4 KiB Raw Blame History Unescape Escape