更新RMDC系统的模块SKILL

1-AgentSkills/designing-contracts/SKILL.md

@@ -0,0 +1,105 @@
+---
+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) |