junhong_cmp_fiber/.specify/memory/constitution.md

君鸿卡管系统 Constitution

Core Principles

I. Tech Stack Adherence (技术栈遵守)

规则 (RULES):

• 开发时 MUST 严格遵守项目定义的技术栈：Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL
• MUST NOT 使用原生调用或绕过框架的快捷方式（禁止 database/sql 直接调用、禁止 net/http 替代 Fiber、禁止 encoding/json 替代 sonic）
• 所有 HTTP 路由和中间件 MUST 使用 Fiber 框架
• 所有数据库操作 MUST 通过 GORM 进行
• 所有配置管理 MUST 使用 Viper
• 所有日志记录 MUST 使用 Zap + Lumberjack.v2
• 所有 JSON 序列化 MUST 使用 sonic
• 所有异步任务 MUST 使用 Asynq

理由 (RATIONALE):

一致的技术栈使用确保代码可维护性、团队协作效率和长期技术债务可控。绕过框架的"快捷方式"会导致代码碎片化、难以调试、性能不一致和安全漏洞。框架选择已经过深思熟虑，必须信任并充分利用其生态系统。

---

II. Code Quality Standards (代码质量标准)

规则 (RULES):

• 代码 MUST 遵循项目分层架构：Handler → Service → Store → Model
• Handler 层 MUST ONLY 处理 HTTP 请求/响应，不得包含业务逻辑
• Service 层 MUST 包含所有业务逻辑，支持跨模块调用
• Store 层 MUST 统一管理所有数据访问，支持事务处理
• Model 层 MUST 定义清晰的数据结构和 DTO
• 所有依赖 MUST 通过 Service 和 Store 结构体进行依赖注入
• 所有公共错误 MUST 在 pkg/errors/ 中定义，使用统一错误码
• 所有 API 响应 MUST 使用 pkg/response/ 的统一格式
• MUST 为所有公共函数编写清晰的注释（英文或中文）
• MUST 避免 magic numbers 和 magic strings，使用常量定义

理由 (RATIONALE):

清晰的分层架构和代码组织使代码易于理解、测试和维护。统一的错误处理和响应格式提升 API 一致性和客户端集成体验。依赖注入模式便于单元测试和模块替换。

---

III. Testing Standards (测试标准)

规则 (RULES):

• 所有核心业务逻辑（Service 层）MUST 有单元测试覆盖
• 所有 API 端点 MUST 有集成测试覆盖
• 所有数据库操作 SHOULD 有事务回滚测试
• 测试 MUST 使用 Go 标准测试框架（testing 包）
• 测试文件 MUST 与源文件同目录，命名为 *_test.go
• 测试 MUST 可独立运行，不依赖外部服务（使用 mock 或 testcontainers）
• 单元测试 MUST 在 100ms 内完成
• 集成测试 SHOULD 在 1s 内完成
• 测试覆盖率 SHOULD 达到 70% 以上（核心业务代码必须 90% 以上）

理由 (RATIONALE):

高质量的测试是代码质量的基石。单元测试确保业务逻辑正确性，集成测试确保模块间协作正常。快速的测试执行时间保证开发效率。测试独立性避免环境依赖导致的 flaky tests。

---

IV. User Experience Consistency (用户体验一致性)

规则 (RULES):

• 所有 API 响应 MUST 使用统一的 JSON 格式：

  {
    "code": 0,
    "message": "success",
    "data": {},
    "timestamp": "2025-11-10T15:30:00Z"
  }
  

• 所有错误响应 MUST 包含明确的错误码和错误消息（中英文双语）
• 所有 API 端点 MUST 遵循 RESTful 设计原则
• 所有分页 API MUST 使用统一的分页参数：page、page_size、total
• 所有时间字段 MUST 使用 ISO 8601 格式（RFC3339）
• 所有货币金额 MUST 使用整数表示（分为单位），避免浮点精度问题
• 所有布尔字段 MUST 使用 true/false，不使用 0/1
• API 版本 MUST 通过 URL 路径管理（如 /api/v1/...）

理由 (RATIONALE):

一致的 API 设计降低客户端开发成本，减少集成错误。统一的数据格式和错误处理提升系统可预测性。清晰的时间和金额表示避免常见的数据处理错误。

---

V. Performance Requirements (性能要求)

规则 (RULES):

• API 响应时间（P95）MUST < 200ms（数据库查询 < 50ms）
• API 响应时间（P99）MUST < 500ms
• 批量操作 MUST 使用批量查询/插入，避免 N+1 查询问题
• 所有数据库查询 MUST 有适当的索引支持
• 列表查询 MUST 实现分页，默认 page_size=20，最大 page_size=100
• 异步任务 MUST 用于非实时操作（批量同步、分佣计算等）
• 内存使用（API 服务）SHOULD < 500MB（正常负载）
• 内存使用（Worker 服务）SHOULD < 1GB（正常负载）
• 数据库连接池 MUST 配置合理（MaxOpenConns=25, MaxIdleConns=10, ConnMaxLifetime=5m）
• Redis 连接池 MUST 配置合理（PoolSize=10, MinIdleConns=5）

理由 (RATIONALE):

性能要求确保系统在生产环境下的稳定性和用户体验。批量操作和异步任务避免阻塞主流程。合理的连接池配置平衡性能和资源消耗。明确的性能指标便于监控和优化。

---

Development Workflow (开发工作流程)

分支管理

• MUST 从 main 分支创建功能分支
• 功能分支命名格式：feature/###-brief-description 或 fix/###-brief-description
• MUST 在合并前保持分支与 main 同步（rebase 或 merge）
• 合并到 main MUST 通过 Pull Request 并经过代码审查

提交规范

• 提交信息 MUST 遵循 Conventional Commits 格式：
  • feat: 新功能描述
  • fix: 修复问题描述
  • refactor: 重构描述
  • test: 测试相关
  • docs: 文档更新
  • chore: 构建/工具相关
• 提交信息 SHOULD 简洁明了（中文或英文）

代码审查

• 所有 PR MUST 至少有一人审查通过
• 审查者 MUST 验证：
  • 代码符合本宪章所有原则
  • 测试覆盖充分且通过
  • 无安全漏洞（SQL 注入、XSS、命令注入等）
  • 性能影响可接受

---

Quality Gates (质量关卡)

代码合并前检查

• 所有测试通过（go test ./...）
• 代码格式化（gofmt 或 goimports）
• 代码静态检查通过（go vet 和 golangci-lint）
• 测试覆盖率符合标准
• 无 TODO/FIXME 遗留（或已记录 Issue）
• API 文档已更新（如有 API 变更）
• 数据库迁移文件已创建（如有 schema 变更）

上线前检查

• 所有功能在 staging 环境测试通过
• 性能测试通过（响应时间、内存使用、并发能力）
• 数据库迁移在 staging 环境验证通过
• 监控和告警配置完成
• 回滚方案已准备

---

Governance

本宪章是所有开发实践的最高指导原则，优先级高于个人偏好或临时便利。

修订流程

• 宪章修订 MUST 经过团队讨论并达成共识
• 修订 MUST 包含明确的理由和影响分析
• 修订 MUST 更新版本号（遵循语义化版本）
• 修订 MUST 同步更新相关模板（plan-template.md、spec-template.md、tasks-template.md）

版本策略

• MAJOR: 移除或重新定义核心原则（不兼容变更）
• MINOR: 新增原则或显著扩展指导内容
• PATCH: 澄清说明、措辞优化、错误修正

合规审查

• 所有 PR 审查 MUST 验证是否符合本宪章
• 违反宪章的代码 MUST 在合并前修正
• 任何复杂性增加（新依赖、新架构层）MUST 在设计文档中明确说明必要性

运行时开发指导

开发时参考本宪章确保一致性。如有疑问，优先遵守原则，再讨论例外情况。

---

Version: 1.0.0 | Ratified: 2025-11-10 | Last Amended: 2025-11-10