226 lines
8.6 KiB
Markdown
226 lines
8.6 KiB
Markdown
<!--
|
||
SYNC IMPACT REPORT - Constitution Amendment
|
||
============================================
|
||
Version Change: INITIAL → 1.0.0
|
||
Date: 2025-11-10
|
||
|
||
NEW PRINCIPLES ESTABLISHED:
|
||
- I. Tech Stack Adherence (Fiber 生态系统)
|
||
- II. Code Quality Standards (代码质量标准)
|
||
- III. Testing Standards (测试标准)
|
||
- IV. User Experience Consistency (用户体验一致性)
|
||
- V. Performance Requirements (性能要求)
|
||
|
||
SECTIONS ADDED:
|
||
- Development Workflow (开发工作流程)
|
||
- Quality Gates (质量关卡)
|
||
|
||
TEMPLATES REQUIRING UPDATES:
|
||
✅ .specify/templates/plan-template.md - Constitution Check section aligned
|
||
✅ .specify/templates/spec-template.md - Requirements section aligned with principles
|
||
✅ .specify/templates/tasks-template.md - Task organization reflects quality gates
|
||
|
||
FOLLOW-UP ACTIONS:
|
||
- None - all placeholders resolved
|
||
|
||
RATIONALE:
|
||
Initial constitution establishment for 君鸿卡管系统 project. Major version 1.0.0
|
||
as this is the first formal governance document defining core development principles.
|
||
-->
|
||
|
||
# 君鸿卡管系统 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 格式：
|
||
```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
|