seed-forge devlab-contract-web-server
用途
为大型前后端分离项目建立并守护"契约层"：前端与服务端就接口结构、字段类型、序列化形态、错误码、配置边界达成显式契约，避免靠口头约定导致的联调返工与线上事故。
定位：devlab-contract-* 技能簇的首个成员，处于 devlab-srv-*（服务端）与 devlab-web-*（前端）之间的交界地带。
适用场景
- 前后端分离、多人协作、接口频繁演进的中大型项目。
- 联调阶段反复出现"字段对不上/类型不匹配/序列化不一致"。
- 需要把接口从"约定俗成"升级为"可校验契约"。
不适用场景
- 单体、无独立前端的项目。
- 一次性脚本/内部工具（契约成本大于收益）。
输入
- 现有接口清单/文档（OpenAPI、代码里的 DTO/schema 等）。
- 前后端技术栈与序列化方式。
- 已发生的契约类问题（可选）。
输出
- 契约规范文档（字段命名/类型/可空性/枚举/时间格式约定）。
- 契约校验建议（schema 校验、契约测试落点）。
- 联调防错清单。
核心规范
1. 字段类型契约
- 每个字段显式定义：类型、可空性、枚举取值、单位、时间/数字格式。
- 类型一致性：同一字段跨前后端类型必须一致（典型坑：
id服务端 int、前端传 string → 解析失败）。 - 数组元素结构显式声明（典型坑：
groupBy期望字符串数组，前端传对象数组[{field: x}]）。
2. 序列化契约
- 统一约定 null/空值/缺省字段的语义（省略 vs null vs 空串）。
- 显式约定大整数/精度/日期的序列化（避免 JS number 精度、时区歧义）。
- MIME/编码显式声明（响应体类型不靠猜）。
3. 错误契约
- 统一错误码 + 错误体结构；区分业务错误与系统错误。
- 前端按错误码分支，不靠 message 文本判断。
4. 配置分层与"不过度"
- 配置分层：与某子系统强相关的配置归其命名空间（如 LLM 配置与排序配置分离），避免大杂烩。
- "既不过度也不缺失"：每个真实可变项可配，不为不存在的需求预埋开关。
- 敏感配置（密钥）不进前端，前端只按构建工具约定前缀暴露非敏感变量。
5. 契约校验落点
- 服务端入参用 schema 校验（类型/必填/枚举），错误要可读（不是裸 500）。
- 有条件时用 OpenAPI/JSON Schema 作单一事实源，前后端各自生成/校验。
- 契约变更 → 契约测试先失败 → 双方同步 → 再合入（破坏性变更同步调用侧）。
工作流
Phase 1: 盘点接口与现存契约问题
Phase 2: 定义契约规范（字段/序列化/错误/配置）
Phase 3: 落地校验（schema 校验 + 契约测试落点）
Phase 4: 防错清单 + 变更流程（破坏性变更同步调用侧）
联调防错清单
- 关键字段类型前后端一致（尤其 id/数字/布尔/枚举）。
- 数组元素结构一致（对象数组 vs 标量数组）。
- null/缺省/空值语义已约定。
- 时间/时区/数字精度格式已约定。
- 错误码结构统一，前端按码分支。
- 敏感配置未进前端；环境变量前缀正确。
- 契约变更走"契约测试先行 + 同步调用侧"。
与其他 devlab-* Skill 的关系
| Skill | 关系 | 说明 |
|---|---|---|
devlab-srv-* |
邻接（服务端侧） | 服务端接口实现与入参校验 |
devlab-web-* |
邻接（前端侧） | 前端接口调用与类型定义 |
devlab-contract-*（簇） |
同簇 | 未来可扩展 contract-service-service、contract-event 等 |
devlab-ai-agent-engineering |
调用方 | AI 应用前后端交互契约引用本技能 |
约束
- 契约是双方共识，任何一方单改必须走"契约测试先行 + 同步对侧"。
- 不硬编码具体 URL/端口/凭据；示例字段不含真实隐私数据。
- 规范要可校验，避免只写文档不落校验。
推荐触发方式
用 devlab-contract-web-server 帮我把这几个接口的前后端契约固化并加校验
联调老是字段对不上，帮我建一份契约规范 + 防错清单