# Contracts Templates Guide

本目录提供 contract-first 开发的最小模板组合。

## 推荐文件

- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板

## 推荐顺序

1. 先完善 `openapi.yaml`
2. 再配置 `orval.config.ts`
3. 生成 client / mocks
4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证

## 最低契约要求

- 请求入口统一通过 generated client 或项目约定的 `apiClient/httpClient`，不要在页面里直接拼 `fetch/axios/baseURL`。
- 分页字段默认统一为 `page/pageSize`；如果项目另有约定，必须在 contract 和 API_MAP 中明确。
- 响应结构必须统一，例如 `code/message/data` 或项目定义的等价结构；不要让前端猜 `res.data` 还是 `res.result`。
- 错误模型必须显式定义，至少覆盖校验失败、权限失败、冲突和服务错误。
- 前端类型优先从 contract 生成，不手写猜测字段。
