junhong_cmp_fiber/AGENTS.md

---

junhong_cmp_fiber 项目开发规范

重要: 本文件包含核心规范。详细规范已提取为 Skills，在特定任务时按需加载。

专项规范 Skills（按需加载）

以下规范在相关任务时自动触发，无需手动加载：

任务类型	触发 Skill	说明
创建/修改 DTO 文件	dto-standards	description 标签、枚举字段、验证标签规范
创建/修改 Model 模型	model-standards	GORM 模型结构、字段标签、TableName 规范
注册 API 路由 / 新增 Handler	api-routing	Register() 函数、RouteSpec、文档生成器更新
测试接口/验证数据	db-validation	PostgreSQL MCP 使用方法和验证示例
数据库迁移	db-migration	迁移命令、文件规范、执行流程、失败处理
维护规范文档	doc-management	规范文档流程和维护规则

⚠️ 新增 Handler 时必须同步更新文档生成器

新增 Handler 后，接口不会自动出现在 OpenAPI 文档中。必须手动更新以下两个文件：

// cmd/api/docs.go 和 cmd/gendocs/main.go
handlers := &bootstrap.Handlers{
    // ... 添加新 Handler
    NewHandler: admin.NewXxxHandler(nil),
}

完整检查清单: 参见 docs/api-documentation-guide.md

---

语言要求

必须遵守:

• 永远用中文交互
• 注释必须使用中文
• 文档必须使用中文
• 日志消息必须使用中文
• 用户可见的错误消息必须使用中文
• 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
• GIT提交的commit必须使用中文

技术栈

必须严格遵守，禁止替代方案:

类型	技术
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）
• 使用 net/http 替代 Fiber
• 使用 encoding/json 替代 sonic（除非必要）

架构分层

必须遵循以下分层架构：

Handler → Service → Store → Model

• Handler: 只处理 HTTP 请求/响应，不包含业务逻辑
• Service: 包含所有业务逻辑，支持跨模块调用
• Store: 统一管理所有数据访问，支持事务处理
• Model: 定义数据结构和 DTO

核心原则

错误处理

• 所有错误必须在 pkg/errors/ 中定义
• 使用统一错误码系统
• Handler 层通过返回 error 传递给全局 ErrorHandler

错误报错规范（必须遵守）

• Handler 层禁止直接返回/拼接底层错误信息给客户端（例如 "参数验证失败: "+err.Error()、err.Error()）
• 参数校验失败：对外统一返回 errors.New(errors.CodeInvalidParam)（详细校验错误写日志）
• Service 层禁止对外返回 fmt.Errorf(...)，必须返回 errors.New(...) 或 errors.Wrap(...)
• 约定用法：errors.New(code[, msg])、errors.Wrap(code, err[, msg])

响应格式

• 所有 API 响应使用 pkg/response/ 的统一格式
• 格式: {code, msg, data, timestamp}

常量管理

• 所有常量定义在 pkg/constants/
• Redis key 使用函数生成: Redis{Module}{Purpose}Key(params...)
• 禁止硬编码字符串和 magic numbers
• 必须为所有常量添加中文注释

Go 代码风格

• 使用 gofmt 格式化
• 遵循 Effective Go
• 包名: 简短、小写、单数、无下划线
• 接口命名: 使用 -er 后缀（Reader、Writer、Logger）

数据库设计

核心规则:

• ❌ 禁止建立外键约束
• ❌ 禁止使用 GORM 关联关系标签（foreignKey、hasMany、belongsTo）
• ✅ 关联通过存储 ID 字段手动维护
• ✅ 关联数据在代码层面显式查询

Go 惯用法 vs Java 风格

✅ Go 风格（推荐）

• 扁平化包结构（最多 2-3 层）
• 小而专注的接口（1-3 个方法）
• 直接访问导出字段（不用 getter/setter）
• 组合优于继承
• 显式错误返回和检查

❌ Java 风格（禁止）

• 过度抽象（不必要的接口、工厂）
• Getter/Setter 方法
• 深层继承层次
• 异常处理（panic/recover）
• 类型前缀（IService、AbstractBase、ServiceImpl）

测试要求

• 核心业务逻辑（Service 层）测试覆盖率 ≥ 90%
• 所有 API 端点必须有集成测试
• 使用 table-driven tests
• 单元测试 < 100ms，集成测试 < 1s

⚠️ 测试真实性原则（严格遵守）

测试必须真正验证功能，禁止绕过核心逻辑：

规则	说明
❌ 禁止传递 nil 绕过依赖	如果功能依赖外部服务（如对象存储、第三方 API），测试必须验证该依赖的调用
❌ 禁止只测试部分流程	如果功能包含 A → B → C 三步，不能只测试 B 而跳过 A 和 C
❌ 禁止声称"测试通过"但未验证核心逻辑	测试通过必须意味着功能真正可用
❌ 禁止擅自使用 Mock	尽量使用真实服务进行集成测试，如需使用 Mock 必须先询问用户并获得同意
✅ 必须验证端到端流程	新增功能必须有完整的集成测试覆盖整个调用链
✅ 缺少配置时必须询问	如果测试需要的配置（如 API Key、环境变量）缺失，必须询问用户而非跳过测试

反面案例：

// ❌ 错误：传递 nil 绕过 storageService，只测试了 processImport
handler := NewIotCardImportHandler(db, redis, store1, store2, nil, logger)
result := handler.processImport(ctx, task)  // 跳过了 downloadAndParseCSV

// ✅ 正确：使用真实服务测试完整流程
handler := NewIotCardImportHandler(db, redis, store1, store2, realStorageService, logger)
handler.HandleIotCardImport(ctx, asynqTask)  // 测试完整流程，验证真实上传/下载

测试超时 = 生产超时：

• 集成测试超时意味着生产环境也可能超时
• 发现超时必须排查原因，不能简单跳过或增加超时时间

测试连接管理（必读）

详细规范: docs/testing/test-connection-guide.md

⚠️ 运行测试必须先加载环境变量:

# ✅ 正确
source .env.local && go test -v ./internal/service/xxx/...

# ❌ 错误（会因缺少配置而失败）
go test -v ./internal/service/xxx/...

标准模板:

func TestXxx(t *testing.T) {
    tx := testutils.NewTestTransaction(t)
    rdb := testutils.GetTestRedis(t)
    testutils.CleanTestRedisKeys(t, rdb)
    
    store := postgres.NewXxxStore(tx, rdb)
    // 测试代码...
}

核心函数:

• NewTestTransaction(t): 创建测试事务，自动回滚
• GetTestRedis(t): 获取全局 Redis 连接
• CleanTestRedisKeys(t, rdb): 自动清理测试 Redis 键

集成测试环境（HTTP API 测试）:

func TestAPI_Create(t *testing.T) {
    env := testutils.NewIntegrationTestEnv(t)
    
    t.Run("成功创建", func(t *testing.T) {
        resp, err := env.AsSuperAdmin().Request("POST", "/api/admin/resources", jsonBody)
        require.NoError(t, err)
        assert.Equal(t, 200, resp.StatusCode)
    })
}

• NewIntegrationTestEnv(t): 创建完整测试环境（事务、Redis、App、Token）
• AsSuperAdmin(): 以超级管理员身份请求
• AsUser(account): 以指定账号身份请求

禁止使用（已移除）:

• ❌ SetupTestDB / TeardownTestDB / SetupTestDBWithStore

性能要求

• API P95 响应时间 < 200ms
• API P99 响应时间 < 500ms
• 数据库查询 < 50ms
• 列表查询必须分页（默认 20，最大 100）
• 避免 N+1 查询，使用批量操作

文档要求

• 每个功能在 docs/{feature-id}/ 创建总结文档
• 文档文件名和内容使用中文
• 同步更新 README.md
• 为导出的函数、类型编写文档注释

函数复杂度

• 函数长度 ≤ 100 行（核心逻辑建议 ≤ 50 行）
• main() 函数只做编排，不含具体实现
• 遵循单一职责原则

访问日志

• 所有 HTTP 请求记录到 access.log
• 记录完整的请求/响应（限制 50KB）
• 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
• 使用 JSON 格式，配置自动轮转

OpenSpec 工作流

创建提案前的检查清单：

1. ✅ 技术栈合规
2. ✅ 架构分层正确
3. ✅ 使用统一错误处理
4. ✅ 常量定义在 pkg/constants/
5. ✅ Go 惯用法（非 Java 风格）
6. ✅ 包含测试计划
7. ✅ 性能考虑
8. ✅ 文档更新计划
9. ✅ 中文优先

Code Review 检查清单

错误处理

• Service 层无 fmt.Errorf 对外返回
• Handler 层参数校验不泄露细节
• 错误码使用正确（4xx vs 5xx）
• 错误日志完整（包含上下文）

代码质量

• 遵循 Handler → Service → Store → Model 分层
• 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
• 常量定义在 pkg/constants/
• 使用 Go 惯用法（非 Java 风格）

测试覆盖

• 核心业务逻辑测试覆盖率 ≥ 90%
• 所有 API 端点有集成测试
• 测试验证真实功能（不绕过核心逻辑）

文档和注释

• 所有注释使用中文
• 导出函数/类型有文档注释
• API 路径注释与真实路由一致

越权防护规范

适用场景：任何涉及跨用户、跨店铺、跨企业的资源访问

三层防护机制：

1. 路由层中间件（粗粒度拦截）

   • 用于明显的权限限制（如企业账号禁止访问账号管理）
   • 示例：

     group.Use(func(c *fiber.Ctx) error {
         userType := middleware.GetUserTypeFromContext(c.UserContext())
         if userType == constants.UserTypeEnterprise {
             return errors.New(errors.CodeForbidden, "无权限访问账号管理功能")
         }
         return c.Next()
     })
     

2. Service 层业务检查（细粒度验证）

   • 使用 middleware.CanManageShop(ctx, targetShopID, shopStore) 验证店铺权限
   • 使用 middleware.CanManageEnterprise(ctx, targetEnterpriseID, enterpriseStore, shopStore) 验证企业权限
   • 类型级权限检查（如代理不能创建平台账号）
   • 示例见 internal/service/account/service.go

3. GORM Callback 自动过滤（兜底）

   • 已有实现，自动应用到所有查询
   • 代理用户：WHERE shop_id IN (自己店铺+下级店铺)
   • 企业用户：WHERE enterprise_id = 当前企业ID
   • 无需手动调用

统一错误返回：

• 越权访问统一返回：errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
• 不区分"不存在"和"无权限"，防止信息泄露

审计日志规范

适用场景：任何敏感操作（账号管理、权限变更、数据删除等）

使用方式：

1. Service 层集成审计日志：

   type Service struct {
       store       *Store
       auditService AuditServiceInterface
   }
   
   func (s *Service) SensitiveOperation(ctx context.Context, ...) error {
       // 1. 执行业务操作
       err := s.store.DoSomething(ctx, ...)
       if err != nil {
           return err
       }
   
       // 2. 记录审计日志（异步）
       s.auditService.LogOperation(ctx, &model.OperationLog{
           OperatorID:    middleware.GetUserIDFromContext(ctx),
           OperationType: "operation_type",
           OperationDesc: "操作描述",
           BeforeData:    beforeData,  // 变更前数据
           AfterData:     afterData,   // 变更后数据
           RequestID:     middleware.GetRequestIDFromContext(ctx),
           IPAddress:     middleware.GetIPFromContext(ctx),
           UserAgent:     middleware.GetUserAgentFromContext(ctx),
       })
   
       return nil
   }
   

2. 审计日志字段说明：

   • operator_id, operator_type, operator_name: 操作人信息（必填）
   • target_*: 目标资源信息（可选）
   • operation_type: 操作类型（create/update/delete/assign_roles等）
   • operation_desc: 操作描述（中文，便于查看）
   • before_data, after_data: 变更数据（JSON 格式）
   • request_id, ip_address, user_agent: 请求上下文

3. 异步写入：

   • 审计日志使用 Goroutine 异步写入
   • 写入失败不影响业务操作
   • 失败时记录 Error 日志，包含完整审计信息

示例参考：internal/service/account/service.go

---

⚠️ 任务执行规范（必须遵守）

提案中的 tasks.md 是契约，不可擅自变更：

规则	说明
❌ 禁止跳过任务	每个任务都是经过规划的，不能因为"简单"或"显而易见"而跳过
❌ 禁止简化任务	不能将多个任务合并或简化执行，除非获得明确许可
❌ 禁止自作主张优化	发现可以优化的地方，必须先询问是否可以调整
✅ 必须逐项完成	按照 tasks.md 中的顺序逐一执行并标记完成
✅ 必须询问后变更	如需调整任务（简化/跳过/合并/优化），先询问用户确认

询问示例：

"我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？" "任务 3.1 在当前实现中可能不需要，是否可以跳过？"

详细规范和 OpenSpec 工作流请查看: @/openspec/AGENTS.md