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

# 跨层契约思考指南

本仓库的最小链路是：

```text
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 测试中一致？如果答案不清楚，先补充契约或拆分边界，再实现功能。