---
name: designing-contracts
description: "Guides API contract design, event schema definition, and version compatibility management for RMDC system. Triggered when defining new APIs, modifying request/response structures, designing MQTT message schemas, or planning breaking changes. Keywords: API versioning, backward compatibility, schema evolution, OpenAPI, event contract, MQTT payload, breaking change."
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
argument-hint: "$ARGUMENTS: <contract-type> [module] — contract-type: api|event|schema|breaking-change"
---

# designing-contracts

## 概述
本 Skill 指导 RMDC 系统的契约设计，包括 API 接口、事件消息、数据 Schema 的定义与版本管理。

## 动态上下文注入

### 查找现有 API 定义
!`grep -rn "router\.\(GET\|POST\|PUT\|DELETE\)" --include="*.go" | head -30`

### 查找 MQTT topic 定义
!`grep -rn "topic\|Topic\|MQTT" --include="*.go" | head -20`

---

## Plan（规划阶段）

### 契约变更类型判定
| 类型 | 影响范围 | 兼容性要求 |
|:---|:---|:---|
| 新增字段（可选） | 低 | 向后兼容 |
| 新增必填字段 | 高 | Breaking Change |
| 修改字段类型 | 高 | Breaking Change |
| 删除字段 | 高 | Breaking Change |
| 修改字段语义 | 高 | Breaking Change |

### 决策点
- [ ] 是否为 Breaking Change？
- [ ] 是否需要版本化（v1 -> v2）？
- [ ] 影响哪些下游模块/客户端？
- [ ] 是否需要过渡期（同时支持新旧版本）？

---

## Verify（验证清单）

### API 契约检查
- [ ] 新增字段有默认值
- [ ] 必填字段未被删除
- [ ] 字段类型未变更
- [ ] 错误码向后兼容
- [ ] 响应结构保持一致

### 事件契约检查
- [ ] Topic 命名遵循规范
- [ ] Payload 字段向后兼容
- [ ] 消息版本字段存在
- [ ] 消费者兼容新字段

### 验证命令
```bash
# 对比 API 变更
git diff HEAD~1 --name-only | grep -E "handler|router"

# 检查 breaking change
./scripts/verify-api-compatibility.sh
```

---

## Execute（执行步骤）

### 新增 API
1. 定义请求/响应结构体
2. 添加字段校验规则
3. 注册路由
4. 更新 API 文档
5. 通知下游模块

### Breaking Change 处理
1. 创建新版本路由（/v2/...）
2. 保留旧版本兼容期
3. 添加废弃警告
4. 通知所有消费者
5. 设定旧版本下线时间

---

## Pitfalls（常见坑）

1. **删除字段未通知下游**：前端/其他模块仍在使用该字段，导致解析失败。
2. **修改字段类型**：如 `string` 改 `int`，JSON 解析会失败。
3. **错误码语义变更**：下游按错误码做分支处理，语义变更会导致逻辑错误。
4. **MQTT payload 无版本字段**：无法做向后兼容处理。
5. **必填字段无默认值**：旧客户端无法正常调用。

---

## 相关文件
| 用途 | 路径 |
|:---|:---|
| 版本策略 | [reference/api-versioning-policy.md](reference/api-versioning-policy.md) |
| 事件规则 | [reference/event-schema-rules.md](reference/event-schema-rules.md) |
| Breaking Change 清单 | [reference/breaking-change-checklist.md](reference/breaking-change-checklist.md) |