csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards
- 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills
- 添加 Skills 触发表格，说明各规范的加载时机
- 优化规范文档结构，提升可维护性和可读性
This commit is contained in:
huang
2026-01-21 11:19:13 +08:00
parent cfac546f14
commit 9795bb9ace
8 changed files with 1013 additions and 1203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
.claude/skills/api-routing/SKILL.md Normal file
View File

@@ -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)

212
.claude/skills/db-migration/SKILL.md Normal file
View File

@@ -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`

151
.claude/skills/db-validation/SKILL.md Normal file
View File

@@ -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. ✅ 如有数据权限，验证过滤是否生效

141
.claude/skills/doc-management/SKILL.md Normal file
View File

@@ -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 清晰描述触发条件

149
.claude/skills/dto-standards/SKILL.md Normal file
View File

@@ -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级)"
```

93
.claude/skills/model-standards/SKILL.md Normal file
View File

@@ -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`（单位：分）

607
AGENTS.md
View File

@@ -21,7 +21,22 @@ Keep this managed block so 'openspec update' can refresh the instructions.
# junhong_cmp_fiber 项目开发规范
**重要提示**: 完整的开发规范和 OpenSpec 工作流详细说明请查看 `@/openspec/AGENTS.md`
**重要**: 本文件包含核心规范。详细规范已提取为 Skills，在特定任务时按需加载。
## 专项规范 Skills（按需加载）
以下规范在相关任务时**自动触发**，无需手动加载：
| 任务类型 | 触发 Skill | 说明 |
|---------|-----------|------|
| 创建/修改 DTO 文件 | `dto-standards` | description 标签、枚举字段、验证标签规范 |
| 创建/修改 Model 模型 | `model-standards` | GORM 模型结构、字段标签、TableName 规范 |
| 注册 API 路由 | `api-routing` | Register() 函数、RouteSpec 必填项 |
| 测试接口/验证数据 | `db-validation` | PostgreSQL MCP 使用方法和验证示例 |
| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
---
## 语言要求
@@ -36,17 +51,19 @@ Keep this managed block so 'openspec update' can refresh the instructions.
## 技术栈
**必须严格遵守以下技术栈，禁止使用替代方案:**
**必须严格遵守，禁止替代方案:**
- **HTTP 框架**: Fiber v2.x
- **ORM**: GORM v1.25.x
- **配置管理**: Viper
- **日志**: Zap + Lumberjack.v2
- **JSON 序列化**: sonic（优先），encoding/json（必要时）
- **验证**: Validator
- **任务队列**: Asynq v0.24.x
- **数据库**: PostgreSQL 14+
- **缓存**: Redis 6.0+
| 类型 | 技术 |
|------|------|
| HTTP 框架 | Fiber v2.x |
| ORM | GORM v1.25.x |
| 配置管理 | Viper |
| 日志 | Zap + Lumberjack.v2 |
| JSON 序列化 | sonic（优先），encoding/json（必要时） |
| 验证 | Validator |
| 任务队列 | Asynq v0.24.x |
| 数据库 | PostgreSQL 14+ |
| 缓存 | Redis 6.0+ |
**禁止:**
- 直接使用 `database/sql`（必须通过 GORM）
@@ -80,215 +97,14 @@ Handler → Service → Store → Model
### 常量管理
- 所有常量定义在 `pkg/constants/`
- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)`
- 格式: `{module}:{purpose}:{identifier}`
- 禁止硬编码字符串和 magic numbers
- **必须为所有常量添加中文注释**，参考 `pkg/constants/iot.go` 的注释风格
- 常量分组使用 `// ========` 分隔线和标题注释
- 每个常量值后必须添加行内注释说明含义
- **必须为所有常量添加中文注释**
### Go 代码风格
- 使用 `gofmt` 格式化
- 遵循 [Effective Go](https://go.dev/doc/effective_go)
- 包名: 简短、小写、单数、无下划线
- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）
- 缩写词: 全大写或全小写（URL、ID、HTTP 或 url、id、http）
## DTO 规范（重要！）
**所有 DTO 文件必须遵循以下规范，这是 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级)"
```
## 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()` 方法，表名使用 `tb_` 前缀
- ✅ 所有字段必须显式指定 `gorm:"column:field_name"` 标签
- ✅ 金额字段使用 `int64` 类型，单位为分
- ✅ 时间字段使用 `*time.Time`（可空）或 `time.Time`（必填）
- ✅ JSONB 字段需要实现 `driver.Valuer` 和 `sql.Scanner` 接口
## API 路由注册规范
**核心要求：所有 HTTP 接口必须使用统一的 `Register()` 函数注册，以自动加入 OpenAPI 文档生成。**
```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` - 操作说明（中文，简短）
- `Tags` - 分类标签（用于文档分组）
- `Input` - 请求 DTO（`nil` 表示无参数）
- `Output` - 响应 DTO（`nil` 表示无返回）
- `Auth` - 是否需要认证
**完整指南**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md)
## 数据库设计
@@ -298,8 +114,6 @@ router.Post("/shops", handler.Create)
- ✅ 关联通过存储 ID 字段手动维护
- ✅ 关联数据在代码层面显式查询
**理由**: 灵活性、性能、可控性、分布式友好
## Go 惯用法 vs Java 风格
### ✅ Go 风格（推荐）
@@ -308,16 +122,13 @@ router.Post("/shops", handler.Create)
- 直接访问导出字段（不用 getter/setter）
- 组合优于继承
- 显式错误返回和检查
- goroutines + channels（不用线程池）
### ❌ Java 风格（禁止）
- 过度抽象（不必要的接口、工厂）
- Getter/Setter 方法
- 深层继承层次
- 异常处理（panic/recover）
- 单例模式
- 类型前缀（IService、AbstractBase、ServiceImpl）
- Bean 风格
## 测试要求
@@ -326,102 +137,6 @@ router.Post("/shops", handler.Create)
- 使用 table-driven tests
- 单元测试 < 100ms，集成测试 < 1s
## 数据库验证规范
**核心要求：AI 在测试接口或验证业务逻辑时，必须使用 PostgreSQL MCP 工具直接查询数据库验证数据的正确性。**
### 何时使用 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"
```
### 注意事项
⚠️ **限制**：
- PostgreSQL MCP 只支持只读查询（SELECT），不能执行 INSERT/UPDATE/DELETE
- 如需插入测试数据，使用 Go 脚本或迁移文件
⚠️ **安全**：
- 避免在查询中暴露敏感数据（如密码哈希）
- 生产环境使用时需谨慎，避免查询大量数据
✅ **最佳实践**：
- 每次 API 测试后都验证数据库状态
- 使用 LIMIT 限制查询结果数量（如 `LIMIT 10`）
- 验证完成后清理测试数据
## 性能要求
- API P95 响应时间 < 200ms
@@ -450,185 +165,6 @@ router.Post("/shops", handler.Create)
- 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
- 使用 JSON 格式，配置自动轮转
## 数据库迁移
### 迁移工具
项目使用 **golang-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 工具检查：
- 字段是否正确创建
- 类型是否符合预期
- 默认值是否正确
- 注释是否存在
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
```
### 使用 PostgreSQL MCP 访问数据库
项目配置了 PostgreSQL MCP 工具，用于直接访问和查询数据库。
**可用工具**:
1. **查看表结构**:
```
PostgresGetObjectDetails:
- schema_name: "public"
- object_name: "tb_permission"
- object_type: "table"
```
2. **列出所有表**:
```
PostgresListObjects:
- schema_name: "public"
- object_type: "table"
```
3. **执行查询**:
```
PostgresExecuteSql:
- sql: "SELECT * FROM tb_permission LIMIT 5"
```
**使用场景**:
- ✅ 验证迁移是否成功执行
- ✅ 检查字段类型、默认值、约束
- ✅ 查看现有数据
- ✅ 测试新增字段的查询功能
- ✅ 调试数据库问题
**注意事项**:
- ⚠️ MCP 工具只支持只读查询（SELECT）
- ⚠️ 不要直接修改数据，修改必须通过迁移文件
- ⚠️ 测试数据可以通过临时 Go 脚本插入
### 迁移最佳实践
1. **向后兼容**:
- 添加字段时使用 `DEFAULT` 或允许 NULL
- 删除字段前确保代码已不再使用
- 修改字段类型要考虑数据转换
2. **原子性**:
- 每个迁移文件只做一件事
- 复杂变更拆分成多个迁移
3. **可回滚**:
- down.sql 必须能完整回滚 up.sql 的所有变更
- 测试回滚功能: `make migrate-down && make migrate-up`
4. **注释完整**:
- 迁移文件顶部说明变更原因
- 关键 SQL 添加行内注释
- 数据库字段使用 COMMENT 添加说明
5. **测试数据**:
- 不要在迁移文件中插入业务数据
- 可以插入配置数据或枚举值
- 测试数据用临时脚本处理
## OpenSpec 工作流
创建提案前的检查清单：
@@ -644,88 +180,3 @@ make migrate-up
9. ✅ 中文优先
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/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 中）

743
CLAUDE.md
View File

@@ -17,673 +17,166 @@ Keep this managed block so 'openspec update' can refresh the instructions.
<!-- OPENSPEC:END -->
# junhong_cmp_fiber Development Guidelines
---
Auto-generated from all feature plans. Last updated: 2025-11-10
# junhong_cmp_fiber 项目开发规范
## Active Technologies
- Go 1.25.4 + Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), golang-migrate (数据库迁移) (002-gorm-postgres-asynq)
- PostgreSQL 14+（主数据库）, Redis 6.0+（任务队列存储） (002-gorm-postgres-asynq)
- Go 1.25.4 + Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), Redis, PostgreSQL (004-rbac-data-permission)
- PostgreSQL 14+ (主数据库), Redis 6.0+ (缓存和任务队列) (004-rbac-data-permission)
- Go 1.25.4 + Fiber v2.x (HTTP 框架), GORM v1.25.x (ORM), Viper (配置管理), Zap + Lumberjack.v2 (日志), sonic (JSON 序列化), Asynq v0.24.x (异步任务队列), golang-migrate (数据库迁移) (004-rbac-data-permission)
- PostgreSQL 14+ (主数据库), Redis 6.0+ (缓存和任务队列存储) (004-rbac-data-permission)
- Go 1.25.4 + Fiber v2.x (HTTP), GORM v1.25.x (ORM), Asynq v0.24.x (任务队列), Viper (配置), Zap + Lumberjack.v2 (日志), sonic (JSON), Validator (005-framework-cleanup-refactor)
**重要**: 本文件包含核心规范。详细规范已提取为 Skills，在特定任务时按需加载。
- Go 1.25.4 (001-fiber-middleware-integration)
## 专项规范 Skills（按需加载）
## Project Structure
以下规范在相关任务时**自动触发**，无需手动加载：
```text
backend/
frontend/
tests/
```
## Commands
# Add commands for Go 1.25.1
| 任务类型 | 触发 Skill | 说明 |
|---------|-----------|------|
| 创建/修改 DTO 文件 | `dto-standards` | description 标签、枚举字段、验证标签规范 |
| 创建/修改 Model 模型 | `model-standards` | GORM 模型结构、字段标签、TableName 规范 |
| 注册 API 路由 | `api-routing` | Register() 函数、RouteSpec 必填项 |
| 测试接口/验证数据 | `db-validation` | PostgreSQL MCP 使用方法和验证示例 |
| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
---
## 核心开发原则
## 语言要求
### 技术栈遵守
**必须遵守 (MUST):**
- 开发时严格遵守项目定义的技术栈：Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL
- 禁止使用原生调用或绕过框架的快捷方式（禁止 `database/sql` 直接调用、禁止 `net/http` 替代 Fiber、禁止 `encoding/json` 替代 sonic）
- 所有 HTTP 路由和中间件必须使用 Fiber 框架
- 所有数据库操作必须通过 GORM 进行
- 所有配置管理必须使用 Viper
- 所有日志记录必须使用 Zap + Lumberjack.v2
- 所有 JSON 序列化优先使用 sonic，仅在必须使用标准库的场景才使用 `encoding/json`
- 所有异步任务必须使用 Asynq
- 必须使用 Go 官方工具链：`go fmt`、`go vet`、`golangci-lint`
- 必须使用 Go Modules 进行依赖管理
**理由:**
一致的技术栈使用确保代码可维护性、团队协作效率和长期技术债务可控。绕过框架的"快捷方式"会导致代码碎片化、难以调试、性能不一致和安全漏洞。
---
### 代码质量标准
**架构分层:**
- 代码必须遵循项目分层架构：`Handler → Service → Store → Model`
- Handler 层只能处理 HTTP 请求/响应，不得包含业务逻辑
- Service 层包含所有业务逻辑，支持跨模块调用
- Store 层统一管理所有数据访问，支持事务处理
- Model 层定义清晰的数据结构和 DTO
- 所有依赖通过结构体字段进行依赖注入（不使用构造函数模式）
**错误和响应处理:**
- 所有公共错误必须在 `pkg/errors/` 中定义，使用统一错误码
- 所有 API 响应必须使用 `pkg/response/` 的统一格式
- 所有常量必须在 `pkg/constants/` 中定义和管理
- 所有 Redis key 必须通过 `pkg/constants/` 中的 Key 生成函数统一管理
**代码注释和文档:**
- 必须为所有导出的函数、类型和常量编写 Go 风格的文档注释（`// FunctionName does something...`）
- 代码注释（implementation comments）应该使用中文
- 日志消息应该使用中文
- 用户可见的错误消息必须使用中文（通过 `pkg/errors/` 的双语消息支持）
- Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳
**必须遵守:**
- 永远用中文交互
- 注释必须使用中文
- 文档必须使用中文
- 日志消息必须使用中文
- 用户可见的错误消息必须使用中文
- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
- GIT提交的commit必须使用中文
**DTO 规范（API 文档生成基础）:**
## 技术栈
所有 DTO 文件必须严格遵循以下规范，这是 OpenAPI 文档自动生成的基础：
**必须严格遵守，禁止替代方案:**
1. **所有字段必须使用 `description` 标签**（禁止使用行内注释）
```go
// ✅ 正确
Username string `json:"username" description:"用户名"`
| 类型 | 技术 |
|------|------|
| HTTP 框架 | Fiber v2.x |
| ORM | GORM v1.25.x |
| 配置管理 | Viper |
| 日志 | Zap + Lumberjack.v2 |
| JSON 序列化 | sonic（优先），encoding/json（必要时） |
| 验证 | Validator |
| 任务队列 | Asynq v0.24.x |
| 数据库 | PostgreSQL 14+ |
| 缓存 | Redis 6.0+ |
// ❌ 错误
Username string `json:"username"` // 用户名
```
**禁止:**
- 直接使用 `database/sql`（必须通过 GORM）
- 使用 `net/http` 替代 Fiber
- 使用 `encoding/json` 替代 sonic（除非必要）
2. **枚举字段必须列出所有可能值（使用中文）**
```go
UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
Status int `json:"status" description:"状态 (0:禁用, 1:启用)"`
```
## 架构分层
3. **validate 标签必须与 OpenAPI 标签一致**
```go
Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
```
必须遵循以下分层架构：
4. **Query 和 Path 参数必须添加对应标签**
```go
Page int `json:"page" query:"page" description:"页码"`
ID uint `path:"id" description:"ID" required:"true"`
```
5. **AI 助手在创建/修改 DTO 后必须执行以下检查**：
- ✅ 所有字段都有 `description` 标签
- ✅ 枚举字段列出了所有可能值（中文）
- ✅ 状态字段说明了 0 和 1 的含义
- ✅ validate 标签与 OpenAPI 标签一致
- ✅ 禁止使用英文枚举值
- ✅ 重新生成文档验证：`go run cmd/gendocs/main.go`
详细规范参见：`docs/code-review-checklist.md`
**Go 代码风格要求:**
- 必须使用 `gofmt` 格式化所有代码
- 必须遵循 [Effective Go](https://go.dev/doc/effective_go) 和 [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
- 变量命名必须使用 Go 风格：`userID`（不是 `userId`）、`HTTPServer`（不是 `HttpServer`）
- 缩写词必须全部大写或全部小写：`URL`、`ID`、`HTTP`（导出）或 `url`、`id`、`http`（未导出）
- 包名必须简短、小写、单数、无下划线：`user`、`order`、`pkg`（不是 `users`、`userService`、`user_service`）
- 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Logger`（不是 `ILogger`、`LoggerInterface`）
**常量管理规范:**
- 业务常量（状态码、类型枚举等）必须定义在 `pkg/constants/constants.go` 或按模块分文件
- Redis key 必须使用函数生成，不允许硬编码字符串拼接
- Redis key 生成函数必须遵循命名规范：`Redis{Module}{Purpose}Key(params...)`
- Redis key 格式必须使用冒号分隔：`{module}:{purpose}:{identifier}`
- 禁止在代码中直接使用 magic numbers（未定义含义的数字字面量）
- 禁止在代码中硬编码字符串字面量（URL、状态码、配置值、业务规则等）
- 当相同的字面量值在 3 个或以上位置使用时，必须提取为常量
- 已定义的常量必须被使用，禁止重复硬编码相同的值
**函数复杂度和职责分离:**
- 函数长度不得超过合理范围（通常 50-100 行，核心逻辑建议 ≤ 50 行）
- 超过 100 行的函数必须拆分为多个小函数，每个函数只负责一件事
- `main()` 函数只做编排（orchestration），不包含具体实现逻辑
- `main()` 函数中的每个初始化步骤应该提取为独立的辅助函数
- 编排函数必须清晰表达流程，避免嵌套的实现细节
- 必须遵循单一职责原则（Single Responsibility Principle）
---
### Go 语言惯用设计原则
**核心理念：写 Go 味道的代码，不要写 Java 味道的代码**
**包组织:**
- 包结构必须扁平化，避免深层嵌套（最多 2-3 层）
- 包必须按功能组织，不是按层次组织
- 包名必须描述功能，不是类型（`http` 不是 `httputils`、`handlers`）
推荐的 Go 风格结构:
```
internal/
├── user/ # user 功能的所有代码
│ ├── handler.go # HTTP handlers
│ ├── service.go # 业务逻辑
│ ├── store.go # 数据访问
│ └── model.go # 数据模型
├── order/
└── sim/
Handler → Service → Store → Model
```
**接口设计:**
- **Handler**: 只处理 HTTP 请求/响应，不包含业务逻辑
- **Service**: 包含所有业务逻辑，支持跨模块调用
- **Store**: 统一管理所有数据访问，支持事务处理
- **Model**: 定义数据结构和 DTO
- 接口必须小而专注（1-3 个方法），不是大而全
- 接口应该在使用方定义，不是实现方（依赖倒置）
- 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Storer`
- 禁止使用 `I` 前缀或 `Interface` 后缀
- 禁止创建只有一个实现的接口（除非明确需要抽象）
## 核心原则
**错误处理:**
### 错误处理
- 所有错误必须在 `pkg/errors/` 中定义
- 使用统一错误码系统
- Handler 层通过返回 `error` 传递给全局 ErrorHandler
- 错误必须显式返回和检查，不使用异常（panic/recover）
- 错误处理必须紧跟错误产生的代码
- 必须使用 `errors.Is()` 和 `errors.As()` 检查错误类型
- 必须使用 `fmt.Errorf()` 包装错误，保留错误链
- 自定义错误应该实现 `error` 接口
- panic 只能用于不可恢复的程序错误
### 响应格式
- 所有 API 响应使用 `pkg/response/` 的统一格式
- 格式: `{code, message, data, timestamp}`
**结构体和方法:**
### 常量管理
- 所有常量定义在 `pkg/constants/`
- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)`
- 禁止硬编码字符串和 magic numbers
- **必须为所有常量添加中文注释**
- 结构体必须简单直接，不是类（class）的替代品
- 禁止为每个字段创建 getter/setter 方法
- 必须直接访问导出的字段（大写开头）
- 必须使用组合（composition）而不是继承（inheritance）
- 构造函数应该命名为 `New` 或 `NewXxx`，返回具体类型
- 禁止使用构造器模式（Builder Pattern）除非真正需要
### Go 代码风格
- 使用 `gofmt` 格式化
- 遵循 [Effective Go](https://go.dev/doc/effective_go)
- 包名: 简短、小写、单数、无下划线
- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）
**并发模式:**
- 必须使用 goroutines 和 channels，不是线程和锁（大多数情况）
- 必须使用 `context.Context` 传递取消信号
- 必须遵循"通过通信共享内存，不要通过共享内存通信"
- 应该使用 `sync.WaitGroup` 等待 goroutines 完成
- 应该使用 `sync.Once` 确保只执行一次
- 禁止创建线程池类（Go 运行时已处理）
**命名约定:**
- 变量名必须简短且符合上下文（短作用域用短名字：`i`, `j`, `k`；长作用域用描述性名字）
- 缩写词必须保持一致的大小写：`URL`, `HTTP`, `ID`（不是 `Url`, `Http`, `Id`）
- 禁止使用匈牙利命名法或类型前缀：`strName`, `arrUsers`
- 禁止使用下划线连接（除了测试和包名）
- 方法接收者名称应该使用 1-2 个字母的缩写，全文件保持一致
**严格禁止的 Java 风格模式:**
1. ❌ 过度抽象（不需要的接口、工厂、构造器）
2. ❌ Getter/Setter（直接访问导出字段）
3. ❌ 继承层次（使用组合，不是嵌入）
4. ❌ 异常处理（使用错误返回，不是 panic/recover）
5. ❌ 单例模式（使用包级别变量或 `sync.Once`）
6. ❌ 线程池（直接使用 goroutines）
7. ❌ 深层包嵌套（保持扁平结构）
8. ❌ 类型前缀（`IService`, `AbstractBase`, `ServiceImpl`）
9. ❌ Bean 风格（不需要 POJO/JavaBean 模式）
10. ❌ 过度 DI 框架（简单直接的依赖注入）
---
### 测试标准
**测试要求:**
- 所有核心业务逻辑（Service 层）必须有单元测试覆盖
- 所有 API 端点必须有集成测试覆盖
- 所有数据库操作应该有事务回滚测试
- 测试必须使用 Go 标准测试框架（`testing` 包）
- 测试文件必须与源文件同目录，命名为 `*_test.go`
- 测试函数必须使用 `Test` 前缀：`func TestUserCreate(t *testing.T)`
- 基准测试必须使用 `Benchmark` 前缀：`func BenchmarkUserCreate(b *testing.B)`
**测试性能要求:**
- 测试必须可独立运行，不依赖外部服务（使用 mock 或 testcontainers）
- 单元测试必须在 100ms 内完成
- 集成测试应该在 1s 内完成
- 测试覆盖率应该达到 70% 以上（核心业务代码必须 90% 以上）
**测试最佳实践:**
- 测试必须使用 table-driven tests 处理多个测试用例
- 测试必须使用 `t.Helper()` 标记辅助函数
---
### API 设计规范
**统一响应格式:**
所有 API 响应必须使用统一的 JSON 格式：
```json
{
"code": 0,
"message": "success",
"data": {},
"timestamp": "2025-11-10T15:30:00Z"
}
```
**API 设计要求:**
- 所有错误响应必须包含明确的错误码和错误消息（中英文双语）
- 所有 API 端点必须遵循 RESTful 设计原则
- 所有分页 API 必须使用统一的分页参数：`page`、`page_size`、`total`
- 所有时间字段必须使用 ISO 8601 格式（RFC3339）
- 所有货币金额必须使用整数表示（分为单位），避免浮点精度问题
- 所有布尔字段必须使用 `true`/`false`，不使用 `0`/`1`
- API 版本必须通过 URL 路径管理（如 `/api/v1/...`）
---
### 性能要求
**性能指标:**
- API 响应时间（P95）必须 < 200ms（数据库查询 < 50ms）
- API 响应时间（P99）必须 < 500ms
- 批量操作必须使用批量查询/插入，避免 N+1 查询问题
- 所有数据库查询必须有适当的索引支持
- 列表查询必须实现分页，默认 `page_size=20`，最大 `page_size=100`
- 异步任务必须用于非实时操作（批量同步、分佣计算等）
**资源限制:**
- 内存使用（API 服务）应该 < 500MB（正常负载）
- 内存使用（Worker 服务）应该 < 1GB（正常负载）
- 数据库连接池必须配置合理（`MaxOpenConns=25`, `MaxIdleConns=10`, `ConnMaxLifetime=5m`）
- Redis 连接池必须配置合理（`PoolSize=10`, `MinIdleConns=5`）
**并发处理:**
- 并发操作应该使用 goroutines 和 channels（不是线程池模式）
- 必须使用 `context.Context` 进行超时和取消控制
- 必须使用 `sync.Pool` 复用频繁分配的对象（如缓冲区）
---
### 数据库设计原则
## 数据库设计
**核心规则:**
- ❌ 禁止建立外键约束
- ❌ 禁止使用 GORM 关联关系标签（foreignKey、hasMany、belongsTo）
- ✅ 关联通过存储 ID 字段手动维护
- ✅ 关联数据在代码层面显式查询
- 数据库表之间禁止建立外键约束（Foreign Key Constraints）
- GORM 模型之间禁止使用 ORM 关联关系（`foreignKey`、`references`、`hasMany`、`belongsTo` 等标签）
- 表之间的关联必须通过存储关联 ID 字段手动维护
- 关联数据查询必须在代码层面显式执行，不依赖 ORM 的自动加载或预加载
- 模型结构体只能包含简单字段，不应包含其他模型的嵌套引用
- 数据库迁移脚本禁止包含外键约束定义
- 数据库迁移脚本禁止包含触发器用于维护关联数据
- 时间字段（`created_at`、`updated_at`）的更新必须由 GORM 自动处理，不使用数据库触发器
## Go 惯用法 vs Java 风格
**GORM 模型字段规范:**
### ✅ Go 风格（推荐）
- 扁平化包结构（最多 2-3 层）
- 小而专注的接口（1-3 个方法）
- 直接访问导出字段（不用 getter/setter）
- 组合优于继承
- 显式错误返回和检查
- 数据库字段名必须使用下划线命名法（snake_case），如 `user_id`、`email_address`、`created_at`
- Go 结构体字段名必须使用驼峰命名法（PascalCase），如 `UserID`、`EmailAddress`、`CreatedAt`
- **所有字段必须显式指定数据库列名**：使用 `gorm:"column:字段名"` 标签明确指定数据库字段名，不依赖 GORM 的自动转换
- 示例：`UserID uint gorm:"column:user_id;not null" json:"user_id"`
- 禁止省略 `column:` 标签，即使 GORM 能自动推断字段名
- 这确保了 Go 字段名和数据库字段名的映射关系清晰可见，避免命名歧义
- 字符串字段长度必须明确定义且保持一致性：
- 短文本（名称、标题等）：`VARCHAR(255)` 或 `VARCHAR(100)`
- 中等文本（描述、备注等）：`VARCHAR(500)` 或 `VARCHAR(1000)`
- 长文本（内容、详情等）：`TEXT` 类型
- **货币金额字段必须使用整数类型存储（分为单位）**：
- Go 类型：`int64`（不是 `float64`）
- 数据库类型：`BIGINT`（不是 `DECIMAL` 或 `NUMERIC`）
- 示例：`CostPrice int64 gorm:"column:cost_price;type:bigint;default:0;comment:成本价(分为单位)" json:"cost_price"`
- 理由：避免浮点数精度问题，确保货币计算的准确性
- 显示时转换：金额除以 100 转换为元（如 10000 分 = 100.00 元）
- 数值字段精度必须明确定义：
- 百分比：使用 `int64` 存储千分比或万分比（如 2000 表示 20%，避免浮点精度问题）
- 计数器：`INTEGER` 或 `BIGINT`
- 流量数据：`BIGINT`（如 MB、KB 为单位的流量使用量）
- 所有字段必须添加中文注释，说明字段用途和业务含义
- 必填字段必须在 GORM 标签中指定 `not null`
- 唯一字段必须在 GORM 标签中指定 `unique` 或通过数据库索引保证唯一性
- 枚举字段应该使用 `VARCHAR` 或 `INTEGER` 类型，并在代码中定义常量映射
- JSONB 字段必须使用 `datatypes.JSON` 类型（从 `gorm.io/datatypes` 包导入）
- 示例：`AccountInfo datatypes.JSON gorm:"column:account_info;type:jsonb;comment:收款账户信息" json:"account_info"`
- 不使用 `pq.StringArray` 或其他 PostgreSQL 特定类型
### ❌ Java 风格（禁止）
- 过度抽象（不必要的接口、工厂）
- Getter/Setter 方法
- 深层继承层次
- 异常处理（panic/recover）
- 类型前缀（IService、AbstractBase、ServiceImpl）
**GORM 模型结构规范:**
## 测试要求
- **所有业务实体模型必须嵌入 `gorm.Model` 和 `BaseModel`**：
- `gorm.Model` 提供：`ID`（主键）、`CreatedAt`、`UpdatedAt`、`DeletedAt`（软删除支持）
- `BaseModel` 提供：`Creator`、`Updater`（审计字段）
- 禁止手动定义 `ID`、`CreatedAt`、`UpdatedAt`、`DeletedAt` 字段
- 示例：
```go
type IotCard struct {
gorm.Model
BaseModel `gorm:"embedded"`
// 业务字段...
}
```
- **日志表和只追加（append-only）表不需要软删除和审计字段**：
- 这类表只定义 `ID` 和 `CreatedAt`，不嵌入 `gorm.Model` 或 `BaseModel`
- 示例：`DataUsageRecord`（流量使用记录）
- 示例：
```go
type DataUsageRecord struct {
ID uint `gorm:"column:id;primaryKey;comment:流量使用记录ID" json:"id"`
IotCardID uint `gorm:"column:iot_card_id;index;not null;comment:IoT卡ID" json:"iot_card_id"`
CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间" json:"created_at"`
}
```
- 核心业务逻辑（Service 层）测试覆盖率 ≥ 90%
- 所有 API 端点必须有集成测试
- 使用 table-driven tests
- 单元测试 < 100ms，集成测试 < 1s
**表名命名规范:**
## 性能要求
- **所有表名必须使用 `tb_` 前缀 + 单数形式**：
- 示例：`tb_iot_card`（不是 `iot_cards`）
- 示例：`tb_package`（不是 `packages`）
- 示例：`tb_order`（不是 `orders`）
- **必须实现 `TableName()` 方法显式指定表名**：
```go
func (IotCard) TableName() string {
return "tb_iot_card"
}
```
- 禁止依赖 GORM 的自动表名推断（避免复数形式导致的不一致）
- API P95 响应时间 < 200ms
- API P99 响应时间 < 500ms
- 数据库查询 < 50ms
- 列表查询必须分页（默认 20，最大 100）
- 避免 N+1 查询，使用批量操作
**索引和约束规范:**
## 文档要求
- **外键字段必须添加 `index` 标签**：
- 示例：`CarrierID uint gorm:"column:carrier_id;index;not null;comment:运营商ID" json:"carrier_id"`
- 提高关联查询性能
- **唯一索引必须支持软删除兼容性**：
- 添加 `where:deleted_at IS NULL` 条件，确保软删除后的记录不影响唯一性约束
- 示例：`gorm:"column:iccid;type:varchar(50);uniqueIndex:idx_iot_card_iccid,where:deleted_at IS NULL;not null;comment:ICCID" json:"iccid"`
- 这样同一个 ICCID 的卡可以多次创建/删除而不违反唯一性约束
- **复合索引命名规范**：
- 使用 `idx_{table}_{field1}_{field2}` 格式
- 示例：`uniqueIndex:idx_device_sim_binding_device_slot,where:deleted_at IS NULL`
- 禁止定义数据库级别的外键约束（Foreign Key Constraints）
- 每个功能在 `docs/{feature-id}/` 创建总结文档
- 文档文件名和内容使用中文
- 同步更新 README.md
- 为导出的函数、类型编写文档注释
**完整模型示例:**
## 函数复杂度
标准业务实体模型（带软删除和审计字段）：
```go
type IotCard struct {
gorm.Model // 提供 ID, CreatedAt, UpdatedAt, DeletedAt
BaseModel `gorm:"embedded"` // 提供 Creator, Updater
ICCID string `gorm:"column:iccid;type:varchar(50);uniqueIndex:idx_iot_card_iccid,where:deleted_at IS NULL;not null;comment:ICCID(唯一标识)" json:"iccid"`
CarrierID uint `gorm:"column:carrier_id;index;not null;comment:运营商ID" json:"carrier_id"`
CostPrice int64 `gorm:"column:cost_price;type:bigint;default:0;comment:成本价(分为单位)" json:"cost_price"`
DistributePrice int64 `gorm:"column:distribute_price;type:bigint;default:0;comment:分销价(分为单位)" json:"distribute_price"`
Status int `gorm:"column:status;type:int;default:1;not null;comment:状态 1-未激活 2-已激活 3-已停用" json:"status"`
}
- 函数长度 ≤ 100 行（核心逻辑建议 ≤ 50 行）
- `main()` 函数只做编排，不含具体实现
- 遵循单一职责原则
func (IotCard) TableName() string {
return "tb_iot_card"
}
```
## 访问日志
日志表模型（不需要软删除和审计）：
```go
type DataUsageRecord struct {
ID uint `gorm:"column:id;primaryKey;comment:流量使用记录ID" json:"id"`
IotCardID uint `gorm:"column:iot_card_id;index;not null;comment:IoT卡ID" json:"iot_card_id"`
DataUsageMB int64 `gorm:"column:data_usage_mb;type:bigint;not null;comment:流量使用量(MB)" json:"data_usage_mb"`
DataIncreaseMB int64 `gorm:"column:data_increase_mb;type:bigint;default:0;comment:相比上次的增量(MB)" json:"data_increase_mb"`
CheckTime time.Time `gorm:"column:check_time;not null;comment:检查时间" json:"check_time"`
CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间" json:"created_at"`
}
- 所有 HTTP 请求记录到 `access.log`
- 记录完整的请求/响应（限制 50KB）
- 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
- 使用 JSON 格式，配置自动轮转
func (DataUsageRecord) TableName() string {
return "tb_data_usage_record"
}
```
## OpenSpec 工作流
包含 JSONB 字段的模型：
```go
type Order struct {
gorm.Model
BaseModel `gorm:"embedded"`
OrderNo string `gorm:"column:order_no;type:varchar(100);uniqueIndex:idx_order_no,where:deleted_at IS NULL;not null;comment:订单号" json:"order_no"`
Amount int64 `gorm:"column:amount;type:bigint;not null;comment:订单金额(分为单位)" json:"amount"`
CarrierOrderData datatypes.JSON `gorm:"column:carrier_order_data;type:jsonb;comment:运营商订单原始数据" json:"carrier_order_data"`
Status int `gorm:"column:status;type:int;default:1;not null;comment:状态 1-待支付 2-已支付 3-已完成" json:"status"`
}
创建提案前的检查清单：
func (Order) TableName() string {
return "tb_order"
}
```
1. ✅ 技术栈合规
2. ✅ 架构分层正确
3. ✅ 使用统一错误处理
4. ✅ 常量定义在 pkg/constants/
5. ✅ Go 惯用法（非 Java 风格）
6. ✅ 包含测试计划
7. ✅ 性能考虑
8. ✅ 文档更新计划
9. ✅ 中文优先
**设计理由:**
1. **灵活性**：业务逻辑完全在代码中控制，不受数据库约束限制
2. **性能**：无外键约束意味着无数据库层面的引用完整性检查开销
3. **简单直接**：显式的关联数据查询使数据流向清晰可见
4. **可控性**：开发者完全掌控何时查询关联数据、查询哪些关联数据
5. **可维护性**：数据库 schema 更简单，迁移更容易
6. **分布式友好**：在微服务和分布式数据库场景下更容易扩展
7. **一致性**：统一的字段命名和类型定义提高代码可读性和可维护性
8. **可理解性**：中文注释让数据库结构一目了然，便于团队协作和新人上手
---
### 错误处理规范
**统一错误处理:**
- 所有 API 错误响应必须使用统一的 JSON 格式（通过 `pkg/errors/` 全局 ErrorHandler）
- 所有 Handler 层错误必须通过返回 `error` 传递给全局 ErrorHandler，禁止手动构造错误响应
- 所有业务错误必须使用 `pkg/errors.New()` 或 `pkg/errors.Wrap()` 创建 `AppError`，并指定错误码
- 所有错误码必须在 `pkg/errors/codes.go` 中统一定义和管理
**Panic 处理:**
- 所有 Panic 必须被 Recover 中间件自动捕获，转换为 500 错误响应
- 禁止在业务代码中主动 `panic`（除非遇到不可恢复的编程错误）
- 禁止在 Handler 中直接使用 `c.Status().JSON()` 返回错误响应
**错误日志:**
- 所有错误日志必须包含完整的请求上下文（Request ID、路径、方法、参数等）
- 5xx 服务端错误必须自动脱敏，只返回通用错误消息，原始错误仅记录到日志
- 4xx 客户端错误可以返回具体业务错误消息（如"用户名已存在"）
**错误码分类:**
- `0`: 成功
- `1000-1999`: 客户端错误（4xx HTTP 状态码，日志级别 Warn）
- `2000-2999`: 服务端错误（5xx HTTP 状态码，日志级别 Error）
---
### 访问日志规范
**核心要求:**
- 所有 HTTP 请求必须被记录到 `access.log`，无例外
- 访问日志必须记录完整的请求参数（query 参数 + request body）
- 访问日志必须记录完整的响应参数（response body）
- 请求/响应 body 必须限制大小为 50KB，超过部分截断并标注 `... (truncated)`
- 访问日志必须通过统一的 Logger 中间件（`pkg/logger/Middleware()`）记录
- 任何中间件的短路返回（认证失败、限流拒绝、参数验证失败等）禁止绕过访问日志
**必需字段:**
访问日志必须包含以下字段：
- `method`: HTTP 方法
- `path`: 请求路径
- `query`: Query 参数字符串
- `status`: HTTP 状态码
- `duration_ms`: 请求耗时（毫秒）
- `request_id`: 请求唯一 ID
- `ip`: 客户端 IP
- `user_agent`: 用户代理
- `user_id`: 用户 ID（认证后有值，否则为空）
- `request_body`: 请求体（限制 50KB）
- `response_body`: 响应体（限制 50KB）
**日志配置:**
- 访问日志应该使用 JSON 格式，便于日志分析和监控
- 访问日志文件必须配置自动轮转（基于大小或时间）
**设计理由:**
完整的访问日志是系统可观测性的基础，对于问题排查、安全审计、性能分析、合规要求和用户行为分析至关重要。
---
### 数据库迁移规范
**迁移工具:**
项目使用 **golang-migrate** 进行数据库迁移管理。
**基本命令:**
```bash
# 查看当前迁移版本
make migrate-version
# 执行所有待迁移
make migrate-up
# 回滚上一次迁移
make migrate-down
# 创建新迁移文件
make migrate-create
# 然后输入迁移名称，例如: add_user_email
```
**迁移文件命名规范:**
- 格式: `{序号}_{描述}.{up|down}.sql`
- 序号: 6位数字，从 000001 开始
- 描述: 小写英文，用下划线分隔
- up: 应用迁移（向前）
- down: 回滚迁移（向后）
**迁移执行流程（必须遵守）:**
当创建迁移文件后，**必须**执行以下验证步骤：
1. **执行迁移**: `make migrate-up`
2. **验证迁移状态**: `make migrate-version` (确认版本号已更新且 dirty=false)
3. **使用 PostgreSQL MCP 验证数据库结构**:
- 字段是否正确创建
- 类型是否符合预期
- 默认值是否正确
- 注释是否存在
4. **验证查询功能**: 编写临时脚本测试新字段的查询功能
5. **更新 Model**: 在 `internal/model/` 中添加对应字段
6. **清理测试数据**: 如果插入了测试数据，记得清理
**迁移失败处理:**
如果迁移执行失败，数据库会被标记为 dirty 状态：
```bash
# 1. 检查错误原因
make migrate-version # 如果显示 dirty=true，说明迁移失败
# 2. 使用 PostgreSQL MCP 连接数据库
# 检查失败的迁移是否部分执行，手动清理或完成迁移
# 3. 清除 dirty 标记（通过临时 Go 脚本）
UPDATE schema_migrations SET dirty = false WHERE version = {失败的版本号};
# 4. 修复迁移文件中的错误
# 5. 重新执行迁移
make migrate-up
```
**使用 PostgreSQL MCP 访问数据库:**
项目配置了 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 脚本插入
**迁移最佳实践:**
1. **向后兼容**: 添加字段时使用 `DEFAULT` 或允许 NULL；删除字段前确保代码已不再使用
2. **原子性**: 每个迁移文件只做一件事；复杂变更拆分成多个迁移
3. **可回滚**: down.sql 必须能完整回滚 up.sql 的所有变更
4. **注释完整**: 迁移文件顶部说明变更原因；关键 SQL 添加行内注释；数据库字段使用 COMMENT 添加说明
5. **测试数据**: 不要在迁移文件中插入业务数据；可以插入配置数据或枚举值；测试数据用临时脚本处理
---
### 文档规范
**文档结构要求:**
- 每个功能完成后必须在 `docs/` 目录创建总结文档
- 总结文档路径必须遵循规范：`docs/{feature-id}/` 对应 `specs/{feature-id}/`
- 总结文档文件名必须使用中文命名（例如：`功能总结.md`、`使用指南.md`、`架构说明.md`）
- 总结文档内容必须使用中文编写
- 每次添加新功能总结文档时必须同步更新 `README.md`
**README.md 更新要求:**
- README.md 中的功能描述必须简短精炼，让首次接触项目的开发者能快速了解
- README.md 的功能描述应该控制在 2-3 句话以内
- 使用中文，便于中文开发者快速理解
- 提供到详细文档的链接
- 按功能模块分组（如"核心功能"、"中间件"、"业务模块"等）
文档结构示例：
```
specs/001-fiber-middleware-integration/ # 功能规划文档（设计阶段）
docs/001-fiber-middleware-integration/ # 功能总结文档（完成阶段）
├── 功能总结.md
├── 使用指南.md
└── 架构说明.md
```
---
## Recent Changes
- 005-framework-cleanup-refactor: Added Go 1.25.4 + Fiber v2.x (HTTP), GORM v1.25.x (ORM), Asynq v0.24.x (任务队列), Viper (配置), Zap + Lumberjack.v2 (日志), sonic (JSON), Validator
- 004-rbac-data-permission: Added Go 1.25.4 + Fiber v2.x (HTTP 框架), GORM v1.25.x (ORM), Viper (配置管理), Zap + Lumberjack.v2 (日志), sonic (JSON 序列化), Asynq v0.24.x (异步任务队列), golang-migrate (数据库迁移)
- 004-rbac-data-permission: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
<!-- MANUAL ADDITIONS START -->
1.永远用中文交互,注释以及文档也要使用中文(必须)
<!-- MANUAL ADDITIONS END -->
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`