重构规范文档：提取详细规范为 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)
--- a/.claude/skills/db-migration/SKILL.md
+++ b/.claude/skills/db-migration/SKILL.md
@@ -0,0 +1,212 @@
+---
+name: db-migration
+description: 数据库迁移规范。创建迁移、修改数据库结构、执行 migrate 命令时使用。包含迁移工具、文件规范、执行流程、失败处理等完整指南。
+---
+
+# 数据库迁移规范
+
+**项目使用 golang-migrate 进行数据库迁移管理。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 创建新的数据库迁移
+- 修改数据库表结构
+- 执行 `make migrate-*` 命令
+- 处理迁移失败问题
+
+## 基本命令
+
+```bash
+# 查看当前迁移版本
+make migrate-version
+
+# 执行所有待迁移
+make migrate-up
+
+# 回滚上一次迁移
+make migrate-down
+
+# 创建新迁移文件
+make migrate-create
+# 然后输入迁移名称，例如: add_user_email
+```
+
+## 迁移文件规范
+
+### 文件位置和命名
+
+迁移文件位于 `migrations/` 目录：
+
+```
+migrations/
+├── 000001_initial_schema.up.sql
+├── 000001_initial_schema.down.sql
+├── 000002_add_user_email.up.sql
+├── 000002_add_user_email.down.sql
+```
+
+**命名规范**:
+- 格式: `{序号}_{描述}.{up|down}.sql`
+- 序号: 6位数字，从 000001 开始
+- 描述: 小写英文，用下划线分隔
+- up: 应用迁移（向前）
+- down: 回滚迁移（向后）
+
+### 编写规范
+
+```sql
+-- up.sql 示例
+-- 添加字段时必须考虑向后兼容
+ALTER TABLE tb_users 
+ADD COLUMN email VARCHAR(100);
+
+-- 添加注释
+COMMENT ON COLUMN tb_users.email IS '用户邮箱';
+
+-- 为现有数据设置默认值（如果需要）
+UPDATE tb_users SET email = '' WHERE email IS NULL;
+
+-- down.sql 示例
+ALTER TABLE tb_users 
+DROP COLUMN IF EXISTS email;
+```
+
+## 迁移执行流程（必须遵守）
+
+当你创建迁移文件后，**必须**执行以下验证步骤：
+
+### 1. 执行迁移
+
+```bash
+make migrate-up
+```
+
+### 2. 验证迁移状态
+
+```bash
+make migrate-version
+# 确认版本号已更新且 dirty=false
+```
+
+### 3. 验证数据库结构
+
+使用 PostgreSQL MCP 工具检查：
+- 字段是否正确创建
+- 类型是否符合预期
+- 默认值是否正确
+- 注释是否存在
+
+```
+PostgresGetObjectDetails:
+- schema_name: "public"
+- object_name: "tb_users"
+- object_type: "table"
+```
+
+### 4. 验证查询功能
+
+编写临时脚本测试新字段的查询功能
+
+### 5. 更新 Model
+
+在 `internal/model/` 中添加对应字段
+
+### 6. 清理测试数据
+
+如果插入了测试数据，记得清理
+
+## 迁移失败处理
+
+如果迁移执行失败，数据库会被标记为 dirty 状态：
+
+```bash
+# 1. 检查错误原因
+make migrate-version
+# 如果显示 dirty=true，说明迁移失败
+
+# 2. 手动修复数据库状态
+# 使用 PostgreSQL MCP 连接数据库
+# 检查失败的迁移是否部分执行
+# 手动清理或完成迁移
+
+# 3. 清除 dirty 标记
+UPDATE schema_migrations SET dirty = false WHERE version = {失败的版本号};
+
+# 4. 修复迁移文件中的错误
+
+# 5. 重新执行迁移
+make migrate-up
+```
+
+## 迁移最佳实践
+
+### 1. 向后兼容
+
+- 添加字段时使用 `DEFAULT` 或允许 NULL
+- 删除字段前确保代码已不再使用
+- 修改字段类型要考虑数据转换
+
+### 2. 原子性
+
+- 每个迁移文件只做一件事
+- 复杂变更拆分成多个迁移
+
+### 3. 可回滚
+
+- down.sql 必须能完整回滚 up.sql 的所有变更
+- 测试回滚功能: `make migrate-down && make migrate-up`
+
+### 4. 注释完整
+
+- 迁移文件顶部说明变更原因
+- 关键 SQL 添加行内注释
+- 数据库字段使用 COMMENT 添加说明
+
+### 5. 测试数据
+
+- 不要在迁移文件中插入业务数据
+- 可以插入配置数据或枚举值
+- 测试数据用临时脚本处理
+
+## PostgreSQL MCP 工具使用
+
+### 查看表结构
+
+```
+PostgresGetObjectDetails: 
+- schema_name: "public"
+- object_name: "tb_permission"
+- object_type: "table"
+```
+
+### 列出所有表
+
+```
+PostgresListObjects:
+- schema_name: "public"
+- object_type: "table"
+```
+
+### 执行查询
+
+```
+PostgresExecuteSql:
+- sql: "SELECT * FROM tb_permission LIMIT 5"
+```
+
+## 注意事项
+
+- ⚠️ MCP 工具只支持只读查询（SELECT）
+- ⚠️ 不要直接修改数据，修改必须通过迁移文件
+- ⚠️ 测试数据可以通过临时 Go 脚本插入
+
+## AI 助手检查清单
+
+创建迁移后必须：
+
+1. ✅ 执行 `make migrate-up`
+2. ✅ 执行 `make migrate-version` 确认成功
+3. ✅ 使用 PostgresGetObjectDetails 验证表结构
+4. ✅ 在 `internal/model/` 中更新对应 Model
+5. ✅ 测试回滚：`make migrate-down && make migrate-up`
--- a/.claude/skills/db-validation/SKILL.md
+++ b/.claude/skills/db-validation/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: db-validation
+description: 数据库验证规范。测试 API 接口、验证业务逻辑、调试数据问题时使用。包含 PostgreSQL MCP 工具使用方法和验证示例。
+---
+
+# 数据库验证规范
+
+**AI 在测试接口或验证业务逻辑时，必须使用 PostgreSQL MCP 工具直接查询数据库验证数据的正确性。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 测试 API 接口后验证数据
+- 检查数据库表结构
+- 验证数据库迁移结果
+- 调试业务逻辑
+- 验证事务处理
+- 检查数据权限过滤
+
+## 何时使用 PostgreSQL MCP
+
+### ✅ 必须使用的场景
+
+- 测试 API 接口后验证数据是否正确写入数据库
+- 检查数据库表结构是否符合 Model 定义
+- 验证数据库迁移是否成功执行
+- 调试业务逻辑时查看实际数据状态
+- 验证事务是否正确提交或回滚
+- 检查数据权限过滤是否生效
+
+### ❌ 不要
+
+- 仅依赖 API 响应判断数据是否正确（响应可能只是内存中的临时数据）
+- 通过日志推测数据库状态
+- 假设代码逻辑正确就认为数据正确
+
+## 可用的 PostgreSQL MCP 工具
+
+```
+1. PostgresListSchemas - 列出所有数据库模式
+2. PostgresListObjects - 列出指定模式下的表/视图/序列
+3. PostgresGetObjectDetails - 查看表结构详情（字段、类型、约束、注释）
+4. PostgresExecuteSql - 执行只读 SQL 查询（SELECT）
+```
+
+## 验证示例
+
+### 场景 1：测试创建用户接口
+
+```
+1. 调用 POST /api/v1/accounts 创建用户
+   → 响应：{"code":0, "data":{"id":123, "username":"testuser"}}
+
+2. ✅ 使用 PostgreSQL MCP 验证数据库
+   PostgresExecuteSql:
+   - sql: "SELECT id, username, user_type, status, created_at FROM tb_account WHERE id = 123"
+   
+3. 检查查询结果：
+   ✅ 用户确实已创建
+   ✅ 字段值与请求参数一致
+   ✅ status = 1（启用）
+   ✅ created_at 有值
+```
+
+### 场景 2：测试数据权限过滤
+
+```
+1. 以代理用户登录，查询店铺列表
+   → 响应：返回 5 个店铺
+
+2. ✅ 使用 PostgreSQL MCP 验证过滤逻辑
+   PostgresExecuteSql:
+   - sql: "SELECT id, shop_name, parent_id FROM tb_shop WHERE deleted_at IS NULL"
+   
+3. 检查：
+   ✅ 数据库实际有 10 个店铺
+   ✅ API 只返回了当前用户及下级的 5 个店铺
+   ✅ 数据权限过滤生效
+```
+
+### 场景 3：验证迁移执行
+
+```
+1. 执行迁移：make migrate-up
+
+2. ✅ 验证表结构
+   PostgresGetObjectDetails:
+   - schema_name: "public"
+   - object_name: "tb_account"
+   - object_type: "table"
+   
+3. 检查：
+   ✅ 新字段 enterprise_id 已添加
+   ✅ 类型为 bigint
+   ✅ 允许 NULL
+   ✅ 注释为"企业ID"
+```
+
+## 工具使用方法
+
+### 查看表结构
+
+```
+PostgresGetObjectDetails: 
+- schema_name: "public"
+- object_name: "tb_permission"
+- object_type: "table"
+```
+
+### 列出所有表
+
+```
+PostgresListObjects:
+- schema_name: "public"
+- object_type: "table"
+```
+
+### 执行查询
+
+```
+PostgresExecuteSql:
+- sql: "SELECT * FROM tb_permission LIMIT 5"
+```
+
+## 注意事项
+
+### ⚠️ 限制
+
+- PostgreSQL MCP 只支持只读查询（SELECT），不能执行 INSERT/UPDATE/DELETE
+- 如需插入测试数据，使用 Go 脚本或迁移文件
+
+### ⚠️ 安全
+
+- 避免在查询中暴露敏感数据（如密码哈希）
+- 生产环境使用时需谨慎，避免查询大量数据
+
+### ✅ 最佳实践
+
+- 每次 API 测试后都验证数据库状态
+- 使用 LIMIT 限制查询结果数量（如 `LIMIT 10`）
+- 验证完成后清理测试数据
+
+## AI 助手检查清单
+
+测试接口后必须：
+
+1. ✅ 使用 PostgresExecuteSql 查询相关数据
+2. ✅ 验证数据是否正确写入
+3. ✅ 验证字段值是否符合预期
+4. ✅ 验证关联数据是否正确
+5. ✅ 如有数据权限，验证过滤是否生效
--- a/.claude/skills/doc-management/SKILL.md
+++ b/.claude/skills/doc-management/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: doc-management
+description: 规范文档管理。添加新规范、更新规范文档、维护 AGENTS.md 时使用。包含规范文档流程和维护规则。
+---
+
+# 规范文档管理
+
+**当你需要为项目添加新的开发规范时，必须遵循以下流程。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 添加新的开发规范
+- 更新现有规范文档
+- 维护 AGENTS.md 文件
+- 创建技术指南文档
+
+## 添加新规范的流程
+
+### 步骤 1：创建详细规范文档
+
+在 `docs/` 目录下创建详细的规范文档（Markdown 格式）：
+
+```
+docs/
+├── api-documentation-guide.md    # API 文档生成规范
+├── code-review-checklist.md      # 代码审查清单
+├── testing-guide.md               # 测试规范
+└── ...
+```
+
+**文档内容要求**：
+- ✅ 包含完整的规范说明、示例代码、常见问题
+- ✅ 使用中文编写，代码示例使用英文
+- ✅ 提供正确示例（✅）和错误示例（❌）的对比
+- ✅ 包含故障排查和调试指南
+
+### 步骤 2：在 AGENTS.md 中添加简短引导
+
+在 `AGENTS.md` 的相关章节中添加**简短**的规范说明 + 引导链接：
+
+```markdown
+## XXX 规范
+
+**核心要求：一句话说明最重要的规则。**
+
+```go
+// ✅ 正确示例（3-5 行）
+...
+
+// ❌ 错误示例（3-5 行）
+...
+```
+
+**关键要点**：
+- 规则 1
+- 规则 2
+- 规则 3
+
+**完整指南**: 参见 [`docs/xxx-guide.md`](docs/xxx-guide.md)
+```
+
+**注意**：
+- ⚠️ AGENTS.md 中的说明不超过 20 行
+- ⚠️ 只保留最核心的规则和示例
+- ⚠️ 必须包含引导链接到详细文档
+
+### 步骤 3：在 README.md 中添加文档链接
+
+在 `README.md` 的"## 文档"章节中添加链接：
+
+```markdown
+## 文档
+
+### 开发规范
+
+- **[API 文档生成规范](docs/api-documentation-guide.md)**：路由注册规范、DTO 规范、OpenAPI 文档生成流程
+- **[XXX 规范](docs/xxx-guide.md)**：简短的一句话说明
+```
+
+**分类规则**：
+- 开发规范：代码规范、API 规范、测试规范
+- 功能指南：功能使用指南、配置指南
+- 架构设计：设计文档、技术选型
+
+## 规范文档的维护
+
+### 更新规范时
+
+1. 优先更新 `docs/` 下的详细文档
+2. 如果核心规则变化，同步更新 AGENTS.md 中的简短说明
+3. 保持 AGENTS.md 简洁，避免冗余
+
+### 删除规范时
+
+1. 删除 `docs/` 下的详细文档
+2. 删除 AGENTS.md 中的相关章节
+3. 删除 README.md 中的链接
+4. 说明删除原因（在 commit message 中）
+
+## Skill 规范管理
+
+### 何时创建 Skill
+
+当规范内容满足以下条件时，应该提取为 Skill：
+- 内容超过 50 行
+- 只在特定任务场景需要
+- 包含详细的步骤和示例
+
+### Skill 文件结构
+
+```
+.claude/skills/{skill-name}/
+└── SKILL.md
+```
+
+### Skill 命名规范
+
+- 使用小写字母和连字符
+- 名称应描述规范主题
+- 示例：`dto-standards`、`db-migration`、`api-routing`
+
+### Skill Frontmatter
+
+```yaml
+---
+name: skill-name
+description: 简短描述（1-2 句话），说明何时使用此 skill
+---
+```
+
+## AI 助手检查清单
+
+添加/更新规范后必须：
+
+1. ✅ 详细文档在 `docs/` 目录
+2. ✅ AGENTS.md 中有简短引导（≤20 行）
+3. ✅ README.md 中有文档链接
+4. ✅ 如果内容 >50 行，考虑提取为 Skill
+5. ✅ Skill 的 name 与目录名一致
+6. ✅ Skill 的 description 清晰描述触发条件
--- a/.claude/skills/dto-standards/SKILL.md
+++ b/.claude/skills/dto-standards/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: dto-standards
+description: DTO 数据传输对象规范。创建或修改 DTO 文件、请求/响应结构时使用。包含 description 标签、枚举字段、验证标签等规范。
+---
+
+# DTO 规范
+
+**所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 创建或修改 `internal/model/` 下的请求/响应 DTO
+- 创建 `XXXRequest`、`XXXResponse`、`XXXReq`、`XXXResp` 结构体
+- 添加或修改 API 接口的输入输出参数
+
+## 必须项（MUST）
+
+### 1. Description 标签规范
+
+**所有字段必须使用 `description` 标签，禁止使用行内注释**
+
+❌ **错误**：
+```go
+type CreateUserRequest struct {
+    Username string `json:"username"` // 用户名
+    Status   int    `json:"status"`   // 状态
+}
+```
+
+✅ **正确**：
+```go
+type CreateUserRequest struct {
+    Username string `json:"username" description:"用户名"`
+    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
+}
+```
+
+### 2. 枚举字段必须列出所有可能值（中文）
+
+**所有枚举类型字段必须在 `description` 中列出所有可能值和对应的中文含义**
+
+```go
+// 用户类型
+UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+
+// 角色类型
+RoleType int `json:"role_type" description:"角色类型 (1:平台角色, 2:客户角色)"`
+
+// 权限类型
+PermType int `json:"perm_type" description:"权限类型 (1:菜单, 2:按钮)"`
+
+// 状态字段
+Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
+
+// 适用端口
+Platform string `json:"platform" description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
+```
+
+❌ **禁止使用英文枚举值**：
+```go
+UserType int `json:"user_type" description:"用户类型 (1:SuperAdmin, 2:Platform)"` // 错误！
+```
+
+### 3. 验证标签与 OpenAPI 标签一致
+
+**所有验证约束必须同时在 `validate` 和 OpenAPI 标签中声明**
+
+```go
+Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
+```
+
+**标签对照表**：
+
+| validate 标签 | OpenAPI 标签 | 说明 |
+|--------------|--------------|------|
+| `required` | `required:"true"` | 必填字段 |
+| `min=N,max=M` | `minimum:"N" maximum:"M"` | 数值范围 |
+| `min=N,max=M` (字符串) | `minLength:"N" maxLength:"M"` | 字符串长度 |
+| `len=N` | `minLength:"N" maxLength:"N"` | 固定长度 |
+| `oneof=A B C` | `description` 中说明 | 枚举值 |
+
+### 4. 请求参数类型标签
+
+**Query 参数和 Path 参数必须添加对应标签**
+
+```go
+// Query 参数
+type ListRequest struct {
+    Page     int  `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+    UserType *int `json:"user_type" query:"user_type" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+}
+
+// Path 参数
+type IDReq struct {
+    ID uint `path:"id" description:"ID" required:"true"`
+}
+```
+
+### 5. 响应 DTO 完整性
+
+**所有响应 DTO 的字段都必须有完整的 `description` 标签**
+
+```go
+type AccountResponse struct {
+    ID        uint   `json:"id" description:"账号ID"`
+    Username  string `json:"username" description:"用户名"`
+    UserType  int    `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
+    Status    int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
+    CreatedAt string `json:"created_at" description:"创建时间"`
+    UpdatedAt string `json:"updated_at" description:"更新时间"`
+}
+```
+
+## AI 助手必须执行的检查
+
+**在创建或修改任何 DTO 文件后，必须执行以下检查：**
+
+1. ✅ 检查所有字段是否有 `description` 标签
+2. ✅ 检查枚举字段是否列出了所有可能值（中文）
+3. ✅ 检查状态字段是否说明了 0 和 1 的含义
+4. ✅ 检查 validate 标签与 OpenAPI 标签是否一致
+5. ✅ 检查是否禁止使用行内注释替代 description
+6. ✅ 检查枚举值是否使用中文而非英文
+7. ✅ 重新生成 OpenAPI 文档验证：`go run cmd/gendocs/main.go`
+
+**详细检查清单**: 参见 `docs/code-review-checklist.md`
+
+## 常见枚举字段标准值
+
+```go
+// 用户类型
+description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
+
+// 角色类型
+description:"角色类型 (1:平台角色, 2:客户角色)"
+
+// 权限类型
+description:"权限类型 (1:菜单, 2:按钮)"
+
+// 适用端口
+description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
+
+// 状态
+description:"状态 (0:禁用, 1:启用)"
+
+// 店铺层级
+description:"店铺层级 (1-7级)"
+```
--- a/.claude/skills/model-standards/SKILL.md
+++ b/.claude/skills/model-standards/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: model-standards
+description: GORM Model 模型规范。创建或修改数据库模型时使用。包含模型结构、字段标签、TableName 实现等规范。
+---
+
+# Model 模型规范
+
+**创建或修改 `internal/model/` 下的数据库模型时必须遵守本规范。**
+
+## 触发条件
+
+在以下情况下必须遵守本规范：
+- 创建新的数据库模型
+- 修改现有模型的字段
+- 添加新的数据库表
+
+## 必须遵守的模型结构
+
+```go
+// ModelName 模型名称模型
+// 详细的业务说明（2-3行）
+// 特殊说明（如果有）
+type ModelName struct {
+	gorm.Model              // 包含 ID、CreatedAt、UpdatedAt、DeletedAt
+	BaseModel `gorm:"embedded"` // 包含 Creator、Updater
+	Field1    string `gorm:"column:field1;type:varchar(50);not null;comment:字段1说明" json:"field1"`
+	// ... 其他字段
+}
+
+// TableName 指定表名
+func (ModelName) TableName() string {
+	return "tb_model_name"
+}
+```
+
+## 关键要点
+
+### 必须嵌入基础模型
+
+- ✅ **必须**嵌入 `gorm.Model` 和 `BaseModel`
+- ❌ **禁止**手动定义 ID、CreatedAt、UpdatedAt、DeletedAt、Creator、Updater
+
+### 必须添加中文注释
+
+- ✅ **必须**为模型添加中文注释，说明业务用途（参考 `internal/model/iot_card.go`）
+- ✅ **必须**在每个字段的 `comment` 标签中添加中文说明
+- ✅ **必须**为导出的类型编写 godoc 格式的文档注释
+
+### 必须实现 TableName
+
+- ✅ **必须**实现 `TableName()` 方法
+- ✅ 表名使用 `tb_` 前缀
+
+### 字段标签规范
+
+- ✅ 所有字段必须显式指定 `gorm:"column:field_name"` 标签
+- ✅ 金额字段使用 `int64` 类型，单位为分
+- ✅ 时间字段使用 `*time.Time`（可空）或 `time.Time`（必填）
+- ✅ JSONB 字段需要实现 `driver.Valuer` 和 `sql.Scanner` 接口
+
+## 完整示例
+
+```go
+// IotCard 物联网卡模型
+// 记录物联网卡的基础信息、状态和套餐关联
+// 支持单卡和设备绑定两种使用模式
+type IotCard struct {
+	gorm.Model
+	BaseModel   `gorm:"embedded"`
+	ICCID       string     `gorm:"column:iccid;type:varchar(20);uniqueIndex;not null;comment:ICCID卡号" json:"iccid"`
+	IMSI        string     `gorm:"column:imsi;type:varchar(20);comment:IMSI号" json:"imsi"`
+	Status      int        `gorm:"column:status;type:smallint;default:0;comment:状态(0:未激活,1:已激活,2:已停机)" json:"status"`
+	ActivatedAt *time.Time `gorm:"column:activated_at;comment:激活时间" json:"activated_at"`
+	ShopID      uint       `gorm:"column:shop_id;index;comment:所属店铺ID" json:"shop_id"`
+}
+
+// TableName 指定表名
+func (IotCard) TableName() string {
+	return "tb_iot_card"
+}
+```
+
+## AI 助手检查清单
+
+修改模型后必须检查：
+
+1. ✅ 是否嵌入了 `gorm.Model` 和 `BaseModel`
+2. ✅ 是否有 godoc 格式的模型注释
+3. ✅ 所有字段是否有 `gorm:"column:xxx"` 标签
+4. ✅ 所有字段是否有 `comment:xxx` 说明
+5. ✅ 是否实现了 `TableName()` 方法
+6. ✅ 表名是否使用 `tb_` 前缀
+7. ✅ 金额字段是否使用 `int64`（单位：分）