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

2.3 KiB

Raw Blame History

变更审计记录：助教详情页 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 类型定义。

合规检查

无新增迁移 SQL
无接口签名变更（仅修复内部字段映射）
无 DDL 变更
无文档同步需求（Schema 未变更）

2.3 KiB Raw Blame History Unescape Escape