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>
47 lines
2.3 KiB
Markdown
47 lines
2.3 KiB
Markdown
# 变更审计记录：助教详情页 API 500 修复（Schema 字段名对齐）
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-29 08:54:29 |
|
||
| Prompt-ID | P20260329-084833 |
|
||
|
||
## 操作摘要
|
||
|
||
修复助教详情页 API 返回 500 的问题。根因：`coach_service.py` 中 `_build_top_customers` 和 `_build_notes` 方法返回的 dict 字段名与 Pydantic Schema（`TopCustomer.score`、`CoachNoteItem.score`）不匹配，导致 Pydantic 验证失败，FastAPI 返回静默 500。
|
||
|
||
## 根因分析
|
||
|
||
`CoachDetailResponse` 使用嵌套的 CamelModel 子类（`TopCustomer`、`CoachNoteItem`），Pydantic 会严格校验字段名。Service 层返回的 dict 中：
|
||
- `_build_top_customers` 使用 `relation_score` → Schema 期望 `score`
|
||
- `_build_notes` 使用 `ai_score` → Schema 期望 `score`
|
||
|
||
字段名不匹配导致 Pydantic 验证失败，FastAPI 返回 500 但无详细错误信息（静默 500 模式）。
|
||
|
||
## 改动注解
|
||
|
||
### `apps/backend/app/services/coach_service.py`
|
||
- 变更类型：修改
|
||
- 原始原因：助教详情页 API 返回 500，Pydantic 验证失败
|
||
- 思路分析：对齐 service 层返回的 dict key 与 Pydantic Schema 字段名。`relation_score` 改为 `score`（对齐 `TopCustomer.score`），`ai_score` 改为 `score`（对齐 `CoachNoteItem.score`）。同时添加 `@trace_service` 装饰器以支持全链路追踪
|
||
- 修改结果：助教详情页 API 恢复正常返回 200；影响范围仅限 `coach_service.py` 内部字段映射，不影响数据库查询和前端展示
|
||
|
||
## 修改明细
|
||
|
||
| 方法 | 旧字段名 | 新字段名 | 对应 Schema |
|
||
|------|----------|----------|-------------|
|
||
| `_build_top_customers` | `relation_score` | `score` | `TopCustomer.score` |
|
||
| `_build_notes` | `ai_score` | `score` | `CoachNoteItem.score` |
|
||
|
||
附加修改：`get_coach_detail` 函数添加 `@trace_service("获取助教详情", "Get coach detail")` 装饰器。
|
||
|
||
## 踩坑记录
|
||
|
||
此问题属于 Pydantic response_model 类型不匹配导致静默 500 的典型案例（已记录在 `frontend-backend-integration.md` 踩坑记录 2026-03-29）。修改 service 返回字段时，必须同步检查对应的 Schema 类型定义。
|
||
|
||
## 合规检查
|
||
|
||
- [x] 无新增迁移 SQL
|
||
- [x] 无接口签名变更（仅修复内部字段映射）
|
||
- [x] 无 DDL 变更
|
||
- [x] 无文档同步需求（Schema 未变更）
|