重构规范文档：提取详细规范为 6 个 Skills 实现模块化和按需加载

- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards - 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills - 添加 Skills 触发表格，说明各规范的加载时机 - 优化规范文档结构，提升可维护性和可读性
2026-01-21 11:19:13 +08:00
parent cfac546f14
commit 9795bb9ace
8 changed files with 1013 additions and 1203 deletions
--- a/.claude/skills/api-routing/SKILL.md
+++ b/.claude/skills/api-routing/SKILL.md
@@ -0,0 +1,120 @@
+---
+name: api-routing
+description: API 路由注册规范。注册新 API 路由时使用。包含 Register() 函数用法、RouteSpec 必填项等规范。
+---
+
+# API 路由注册规范
+
+**所有 HTTP 接口必须使用统一的 `Register()` 函数注册，以自动加入 OpenAPI 文档生成。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 注册新的 API 路由
+- 修改现有路由配置
+- 添加新的 Handler 函数
+
+## 核心规则
+
+### 必须使用 Register() 函数
+
+```go
+// ✅ 正确
+Register(router, doc, basePath, "POST", "/shops", handler.Create, RouteSpec{
+    Summary: "创建店铺",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.CreateShopRequest),
+    Output:  new(model.ShopResponse),
+    Auth:    true,
+})
+
+// ❌ 错误：直接注册不会生成文档
+router.Post("/shops", handler.Create)
+```
+
+## RouteSpec 必填项
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `Summary` | string | 操作说明（中文，简短） | `"创建店铺"` |
+| `Tags` | []string | 分类标签（用于文档分组） | `[]string{"店铺管理"}` |
+| `Input` | interface{} | 请求 DTO（`nil` 表示无参数） | `new(model.CreateShopRequest)` |
+| `Output` | interface{} | 响应 DTO（`nil` 表示无返回） | `new(model.ShopResponse)` |
+| `Auth` | bool | 是否需要认证 | `true` |
+
+## 常见路由模式
+
+### CRUD 路由组
+
+```go
+// 列表查询
+Register(router, doc, basePath, "GET", "/shops", handler.List, RouteSpec{
+    Summary: "获取店铺列表",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.ListShopRequest),
+    Output:  new(model.ShopListResponse),
+    Auth:    true,
+})
+
+// 详情查询
+Register(router, doc, basePath, "GET", "/shops/:id", handler.Get, RouteSpec{
+    Summary: "获取店铺详情",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.IDReq),
+    Output:  new(model.ShopResponse),
+    Auth:    true,
+})
+
+// 创建
+Register(router, doc, basePath, "POST", "/shops", handler.Create, RouteSpec{
+    Summary: "创建店铺",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.CreateShopRequest),
+    Output:  new(model.ShopResponse),
+    Auth:    true,
+})
+
+// 更新
+Register(router, doc, basePath, "PUT", "/shops/:id", handler.Update, RouteSpec{
+    Summary: "更新店铺",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.UpdateShopRequest),
+    Output:  new(model.ShopResponse),
+    Auth:    true,
+})
+
+// 删除
+Register(router, doc, basePath, "DELETE", "/shops/:id", handler.Delete, RouteSpec{
+    Summary: "删除店铺",
+    Tags:    []string{"店铺管理"},
+    Input:   new(model.IDReq),
+    Output:  nil,
+    Auth:    true,
+})
+```
+
+### 无认证路由
+
+```go
+// 公开接口（如健康检查）
+Register(router, doc, basePath, "GET", "/health", handler.Health, RouteSpec{
+    Summary: "健康检查",
+    Tags:    []string{"系统"},
+    Input:   nil,
+    Output:  new(model.HealthResponse),
+    Auth:    false,
+})
+```
+
+## AI 助手检查清单
+
+注册路由后必须检查：
+
+1. ✅ 是否使用 `Register()` 函数而非直接注册
+2. ✅ `Summary` 是否使用中文简短描述
+3. ✅ `Tags` 是否正确分组
+4. ✅ `Input` 和 `Output` 是否指向正确的 DTO
+5. ✅ `Auth` 是否根据业务需求正确设置
+6. ✅ 运行 `go run cmd/gendocs/main.go` 验证文档生成
+
+**完整指南**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md)