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>
73 lines
5.9 KiB
Markdown
73 lines
5.9 KiB
Markdown
# 变更审计记录：助教详情页设计稿对齐 + 数据格式化修复
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-29 09:16:43 |
|
||
| Prompt-ID | P20260329-090937 |
|
||
| Session-ID | 96ce2a05 |
|
||
| Session 路径 | docs/audit/session_logs/2026-03/29/29_abf3b322_085456 |
|
||
|
||
## 操作摘要
|
||
修复助教详情页与设计稿的多项显示差异：后端金额/数量字段从预格式化字符串改为返回原始数字（避免前端 WXS 格式化 NaN），收入 color 从 hex 值改为 CSS 类名，服务记录 table 从 table_id 改为 table_name，WXML 模板统一使用 `fmt.safe()` / `fmt.money()` / `fmt.hours()` WXS 函数格式化。同时将 coach-detail 和 customer-detail 页面的自定义加载组件替换为小程序原生 `wx.showLoading`。
|
||
|
||
## 根因分析
|
||
后端 `_format_currency()` 预格式化金额为字符串（如 "¥25,447"），前端 WXML 中 WXS `money()` 函数对字符串输入返回 NaN。违反了"TS 与 WXS 格式化互斥"规范（`frontend-backend-integration.md`）。
|
||
|
||
## 本次对话文件变更
|
||
|
||
### 新增文件
|
||
- `docs/audit/prompt_logs/prompt_log_20260329_090937.md`
|
||
- `docs/audit/session_logs/2026-03/29/29_abf3b322_085456/main_01_96ce2a05.md`
|
||
|
||
## 改动注解
|
||
|
||
### `apps/backend/app/schemas/xcx_coaches.py`
|
||
- 变更类型：修改
|
||
- 原始原因：前端 WXS `money()` 函数对已格式化的字符串（如 "¥25,447"）调用数值方法返回 NaN，需要后端返回原始数字
|
||
- 思路分析：将 `TopCustomer.balance/consume` 从 `str` → `float`，`CoachServiceRecord.income` 从 `str` → `float`，`HistoryMonth.customers` 从 `str` → `int`、`hours/salary` 从 `str` → `float`。遵循"TS 与 WXS 格式化互斥"规范，后端只返回原始数值，格式化交给前端 WXS
|
||
- 修改结果：Schema 类型与 service 层返回值对齐，Pydantic 验证通过，前端 WXS 可正确格式化数值
|
||
|
||
### `apps/backend/app/services/coach_service.py`
|
||
- 变更类型：修改
|
||
- 原始原因：多处与设计稿不一致：color 用 hex 值而非 CSS 类名、金额预格式化导致前端 NaN、table 显示 id 而非名称、TASK_TYPE_MAP 缺少 relationship_building
|
||
- 思路分析：(1) `_build_income` 中 color 从 hex（`#42A5F5` 等）改为 CSS 类名（`primary/success/warning/purple`），符合"后端值拼接 WXSS 类名时必须是合法 CSS 标识符"规范；(2) `_build_top_customers` 中 `balance/consume` 从 `_format_currency()` 改为返回原始 float；(3) `_build_service_records` 中 `income` 改为原始 float，`table` 从 `table_id` 改为 `table_name`；(4) `_build_history_months` 中 `customers/hours/salary` 改为原始数字；(5) TASK_TYPE_MAP 新增 `relationship_building` → "关系维护"；(6) `_build_notes` 中 `ai_score` → `score` 对齐 Schema；(7) 添加 `@trace_service` 装饰器
|
||
- 修改结果：所有数值字段返回原始类型，前端 WXS 可正确格式化；color 值为合法 CSS 类名；table 显示人类可读名称
|
||
|
||
### `apps/backend/app/services/fdw_queries.py`
|
||
- 变更类型：修改
|
||
- 原始原因：`get_assistant_info` 的 hire_date 带时区后缀、`get_coach_top_customers` 未过滤散客、`get_coach_service_records` 缺少 table_name
|
||
- 思路分析：(1) `get_assistant_info` 中 hire_date 从 `str(row[3])` 改为 `.strftime("%Y-%m-%d")`，去除时区信息；(2) `get_coach_top_customers` 添加 `tenant_member_id > 0` 过滤散客（散客 member_id ≤ 0，符合飞球数据规范）；(3) `get_coach_service_records` LEFT JOIN `v_dim_table` 获取 `table_name`，返回 `table_name` 字段替代 `table_id`
|
||
- 修改结果：hire_date 格式统一为 YYYY-MM-DD；TOP 客户列表不再包含散客；服务记录显示台桌名称而非 ID
|
||
|
||
### `apps/miniprogram/miniprogram/pages/coach-detail/coach-detail.wxml`
|
||
- 变更类型：修改
|
||
- 原始原因：(1) 使用自定义加载组件（`g-toast-loading` + `t-loading`），需改为原生 `wx.showLoading`；(2) 数据展示未使用 WXS 格式化函数；(3) 更多信息表格 hours 格式化从 `fmt.hours` 改为 `fmt.hoursH`（"小时"→"h"）
|
||
- 思路分析：移除自定义加载 DOM，引入 `format.wxs`，所有数据绑定统一使用 `fmt.safe()` / `fmt.money()` / `fmt.hours()` WXS 函数，确保 null/undefined 值安全显示
|
||
- 修改结果：页面加载使用原生遮罩，数据展示统一通过 WXS 格式化，避免 NaN 和 undefined 显示
|
||
|
||
### `apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.wxml`
|
||
- 变更类型：修改
|
||
- 原始原因：使用自定义加载组件，需改为原生 `wx.showLoading`；数据展示未统一使用 WXS 格式化
|
||
- 思路分析：与 coach-detail 同步改造，移除自定义加载 DOM，统一使用 `fmt.safe()` / `fmt.money()` / `fmt.hours()` WXS 函数格式化所有数据绑定
|
||
- 修改结果：页面加载使用原生遮罩，金额/时长/文本统一通过 WXS 格式化
|
||
|
||
### `apps/miniprogram/miniprogram/pages/customer-records/customer-records.wxml`
|
||
- 变更类型：修改
|
||
- 原始原因：消费记录页面数据展示未统一使用 WXS 格式化，金额直接拼接 `¥` 前缀
|
||
- 思路分析：所有金额字段改用 `fmt.money()` 格式化，文本字段用 `fmt.safe()` 防护，时长用 `fmt.hours()` 格式化
|
||
- 修改结果：消费记录页面数据展示统一通过 WXS 格式化，与其他页面保持一致
|
||
|
||
## 合规检查
|
||
|
||
| 检查项 | 状态 |
|
||
|--------|------|
|
||
| 新增迁移 SQL | 无 |
|
||
| DDL 基线 | N/A |
|
||
| BD 手册 | N/A（无 DB schema 变更） |
|
||
| ⚠️ OpenAPI spec | 接口返回类型已变更但 spec 未同步。自动导出失败（`dashscope` 模块缺失），需手动在后端 venv 中执行 `python scripts/ops/_export_openapi.py` |
|
||
|
||
## 风险评估
|
||
- 影响范围：助教详情页（COACH-1）、客户详情页、消费记录页
|
||
- 前后端契约变更：`TopCustomer.balance/consume`、`CoachServiceRecord.income`、`HistoryMonth.customers/hours/salary` 类型从 str 变为数值类型，前端已同步适配 WXS 格式化
|
||
- 向后兼容：前端已同步修改，无兼容性问题
|