# OpenSpec Configuration
# https://github.com/Fission-AI/OpenSpec

schema: spec-driven

# 项目上下文 - 注入到所有 artifacts（proposal, specs, design, tasks）
context: |
  ## 项目概述
  junhong_cmp_fiber 是一个基于 Go + Fiber 的企业级中后台管理系统（Content Management Platform），
  专注于物联网卡和号卡的全生命周期管理，支持代理商体系和分佣结算。

  ## 核心技术栈
  - **后端框架**: Go 1.25.4 + Fiber v2.x（HTTP）+ GORM v1.25.x（ORM）
  - **数据存储**: PostgreSQL 14+ + Redis 6.0+
  - **基础设施**: Asynq v0.24.x（任务队列）+ Viper（配置）+ Zap（日志）
  - **JSON 序列化**: sonic（优先），encoding/json（必要时）
  - **验证**: Validator

  ## 架构分层（严格遵守）
  ```
  Handler → Service → Store → Model
  ```
  - **Handler**: 仅处理 HTTP 请求/响应，参数验证，无业务逻辑
  - **Service**: 所有业务逻辑，支持跨模块调用
  - **Store**: 统一数据访问，支持事务
  - **Model**: 数据结构和 DTO

  ## 核心约束
  - ❌ 禁止使用 `database/sql` 直接调用（必须用 GORM）
  - ❌ 禁止使用 `net/http` 替代 Fiber
  - ❌ 禁止使用外键约束和 GORM 关联关系（foreignKey, hasMany, belongsTo）
  - ✅ 表关联通过 ID 字段手动维护，代码层显式查询
  - ✅ Go 惯用模式：扁平化包结构、小接口、组合优于继承、显式错误返回
  - ✅ 遵循 gofmt、Effective Go、Go Code Review Comments

  ## 语言要求
  - 交互、注释、文档、日志、错误消息：中文
  - 变量名、函数名、类型名：英文（Go 命名规范）
  - Git commit：中文

  ## 性能要求
  - API P95 < 200ms，P99 < 500ms
  - 数据库查询 < 50ms
  - 列表查询必须分页（默认 20，最大 100）

  ## 测试要求
  - 核心业务逻辑测试覆盖率 ≥ 90%
  - 所有 API 端点必须有集成测试
  - 使用 table-driven tests

# 每个 artifact 的特定规则
rules:
  proposal:
    - 必须检查技术栈合规性（Fiber、GORM、Viper、Zap、Asynq）
    - 必须说明架构分层（Handler → Service → Store → Model）
    - 必须包含测试计划和性能考虑
    - 文档使用中文，代码命名使用英文
    - 包含功能 ID（如 feature-001-xxx）

  specs:
    - API 规格必须定义统一响应格式 {code, message, data, timestamp}
    - 错误码在 pkg/errors/ 中定义，使用双语错误消息
    - 数据模型禁止使用外键和 GORM 关联，关联通过 ID 维护
    - 必须明确数据权限规则（基于用户类型和店铺层级）
    - Redis key 必须使用函数生成：Redis{Module}{Purpose}Key(params...)

  design:
    - 严格遵循 Handler → Service → Store → Model 分层
    - 必须说明依赖注入方式（结构体字段注入）
    - 必须包含事务处理设计（如涉及多表操作）
    - 必须定义常量在 pkg/constants/（禁止硬编码）
    - 异步任务使用 Asynq，必须支持重试和幂等性
    - 性能敏感操作必须考虑 Redis 缓存

  tasks:
    - tasks.md 是契约，不可擅自变更
    - 禁止跳过任务、合并任务、简化任务（除非获得许可）
    - 必须逐项完成并标记状态
    - 每个任务必须包含验证步骤（单元测试、集成测试、lsp_diagnostics）
    - 数据库变更必须包含迁移文件（使用 golang-migrate）
    - 新增 Handler 必须更新文档生成器（cmd/api/docs.go 和 cmd/gendocs/main.go）