zhixing-system/.trellis/spec/guides/cross-layer-thinking-guide.md

跨层契约思考指南

本仓库的最小链路是：

FastAPI 路由
  → Pydantic response model
  → 同源 /api/v1 代理
  → requestJson<T>
  → feature *.types.ts / *.api.ts
  → React Query hook
  → 页面加载、错误、成功状态

以系统状态为例，链路对应：

• 后端：interfaces/http/router.py 挂载 /api/v1/system/status，interfaces/http/system.py 返回 SystemStatusResponse。
• 后端测试：tests/test_system_http.py 断言状态码和完整 JSON。
• 前端：features/system/api/system.api.ts 使用 /api/v1/system/status，system.types.ts 描述字段，system.query.ts 管理缓存。
• 页面测试：system-status-page.test.tsx 断言“运行正常”和环境文本。

修改 HTTP 字段前

1. 找到后端响应模型、路由和现有契约测试。
2. 找到 feature API 函数、TypeScript 类型、query hook 和页面分支。
3. 确认开发 Vite 代理和生产 Nginx 仍覆盖该路径；浏览器代码保持同源路径。
4. 同步更新后端 HTTP 测试和前端行为测试，再运行两端质量命令。

常见跨层遗漏

• 只修改 Pydantic 字段，没有修改 *.types.ts，导致 UI 仍读取旧形状。
• 把 /api/v1 改成后端绝对 URL，绕过 vite.config.ts 和 Nginx 的同源代理。
• 在页面内直接 fetch，绕过 requestJson 的 ApiError 和 AbortSignal。
• 用 Zustand 缓存服务器响应，造成 React Query 缓存与全局 store 的双重事实来源。
• 只测试请求成功，没有测试 isPending、isError 或字段缺失时的安全展示。

边界验证

提交前至少回答：输入在哪里解析？错误在哪里转换？状态由谁拥有？字段是否在后端、客户端类型和 UI 测试中一致？如果答案不清楚，先补充契约或拆分边界，再实现功能。