# 变更审计记录：助教详情页 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 未变更）