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

- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards
- 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills
- 添加 Skills 触发表格，说明各规范的加载时机
- 优化规范文档结构，提升可维护性和可读性

CLAUDE.md

@@ -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:"用户名"`
-   
-   // ❌ 错误
-   Username string `json:"username"` // 用户名
-   ```
+| 类型 | 技术 |
+|------|------|
+| 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+ |
 
-2. **枚举字段必须列出所有可能值（使用中文）**
-   ```go
-   UserType int `json:"user_type" description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
-   Status   int `json:"status" description:"状态 (0:禁用, 1:启用)"`
-   ```
+**禁止:**
+- 直接使用 `database/sql`（必须通过 GORM）
+- 使用 `net/http` 替代 Fiber
+- 使用 `encoding/json` 替代 sonic（除非必要）
 
-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`