diff --git a/READEME.md b/READEME.md index 6a240cd..3657a33 100644 --- a/READEME.md +++ b/READEME.md @@ -122,3 +122,302 @@ go run cmd/worker/main.go - **直接实现**:避免不必要的接口抽象 - **统一管理**:依赖集中初始化,避免参数传递 - **职责分离**:API 和 Worker 独立部署,便于扩展 + +--- + +## 开发流程 (Speckit) + +本项目使用 Speckit 规范化功能开发流程,确保代码质量、测试覆盖和架构一致性。 + +### 项目宪章 (Constitution) + +项目遵循 `.specify/memory/constitution.md` 定义的核心原则: + +1. **技术栈遵守**:严格使用 Fiber + GORM + Viper + Zap + Asynq,禁止原生调用快捷方式 +2. **代码质量标准**:遵循 Handler → Service → Store → Model 分层架构 +3. **测试标准**:70%+ 测试覆盖率,核心业务 90%+ +4. **用户体验一致性**:统一 JSON 响应格式、RESTful API、双语错误消息 +5. **性能要求**:API P95 < 200ms,P99 < 500ms,合理使用批量操作和异步任务 + +详细原则和规则请参阅宪章文档。 + +### Speckit 命令使用 + +#### 1. 创建功能规范 + +```bash +/speckit.specify "功能描述" +``` + +**用途**:从自然语言描述创建结构化的功能规范文档 + +**输出**:`specs/###-feature-name/spec.md` + +**包含内容**: +- 用户故事和测试场景(按优先级排序 P1/P2/P3) +- 功能需求(FR-001, FR-002...) +- 技术需求(基于宪章自动生成) +- 成功标准 + +**示例**: +```bash +/speckit.specify "实现代理商分佣计算和结算功能,支持多级代理商分佣规则" +``` + +--- + +#### 2. 明确规范细节 + +```bash +/speckit.clarify +``` + +**用途**:识别规范中的不明确区域,提出最多 5 个针对性问题并将答案编码回规范 + +**使用场景**: +- 功能需求模糊或有歧义 +- 需要澄清技术实现细节 +- 边界条件不清楚 + +**输出**:更新 `spec.md`,消除歧义和不确定性 + +--- + +#### 3. 生成实现计划 + +```bash +/speckit.plan +``` + +**用途**:基于功能规范执行完整的实现规划工作流 + +**输出**:`specs/###-feature-name/` 目录下生成: +- `plan.md` - 实现计划(技术上下文、宪章检查、项目结构) +- `research.md` - Phase 0 技术调研 +- `data-model.md` - Phase 1 数据模型设计 +- `quickstart.md` - Phase 1 快速开始指南 +- `contracts/` - Phase 1 API 契约定义 + +**关键检查**: +- ✅ 宪章符合性检查(技术栈、架构、测试、性能) +- ✅ 项目结构规划(Go 模块组织) +- ✅ 复杂度跟踪和说明 + +--- + +#### 4. 生成任务列表 + +```bash +/speckit.tasks +``` + +**用途**:从设计文档生成依赖排序的可执行任务列表 + +**输入**: +- `spec.md`(必需 - 用户故事) +- `plan.md`(必需 - 技术规划) +- `research.md`、`data-model.md`、`contracts/`(可选) + +**输出**:`specs/###-feature-name/tasks.md` + +**任务组织**: +- Phase 1: Setup(项目初始化) +- Phase 2: Foundational(基础设施 - 阻塞所有用户故事) +- Phase 3+: 按用户故事优先级组织(US1/P1, US2/P2...) +- Phase N: Polish & Quality Gates(质量关卡) + +**任务特性**: +- `[P]` 标记可并行执行的任务 +- `[US1]` 标记任务所属用户故事 +- 包含精确文件路径 +- 包含依赖关系说明 + +--- + +#### 5. 执行实现 + +```bash +/speckit.implement +``` + +**用途**:执行 `tasks.md` 中定义的所有任务,完成功能实现 + +**执行流程**: +1. 按阶段顺序处理任务(Setup → Foundational → User Stories → Polish) +2. 每个用户故事独立实现和测试 +3. 自动运行质量关卡检查 + +**质量关卡**(自动执行): +- `go test ./...` - 所有测试通过 +- `gofmt -l .` - 代码格式化 +- `go vet ./...` - 静态检查 +- `golangci-lint run` - 代码质量检查 +- `go test -cover ./...` - 测试覆盖率验证 + +--- + +#### 6. 一致性分析 + +```bash +/speckit.analyze +``` + +**用途**:执行非破坏性的跨文档一致性和质量分析 + +**检查内容**: +- spec.md、plan.md、tasks.md 之间的一致性 +- 宪章符合性验证 +- 任务完整性和依赖正确性 +- 测试覆盖计划是否充分 + +**使用时机**: +- 生成 tasks.md 之后 +- 开始实现之前 +- 发现文档不一致时 + +--- + +#### 7. 生成自定义检查清单 + +```bash +/speckit.checklist "检查项要求" +``` + +**用途**:为当前功能生成自定义检查清单 + +**示例**: +```bash +/speckit.checklist "生成代码审查清单,包括安全性、性能和 Fiber 最佳实践" +``` + +--- + +#### 8. 更新项目宪章 + +```bash +/speckit.constitution "宪章更新说明" +``` + +**用途**:创建或更新项目宪章,并保持所有依赖模板同步 + +**使用场景**: +- 首次建立项目开发原则 +- 修订现有原则 +- 添加新的质量标准 + +**自动同步**: +- 更新 `plan-template.md` 的宪章检查部分 +- 更新 `spec-template.md` 的技术需求部分 +- 更新 `tasks-template.md` 的质量关卡部分 + +--- + +### 完整开发工作流示例 + +```bash +# 1. 创建功能规范 +/speckit.specify "实现 SIM 卡批量状态同步功能,支持定时任务和手动触发" + +# 2. 明确模糊需求(如有必要) +/speckit.clarify + +# 3. 生成实现计划(包含技术调研和设计) +/speckit.plan + +# 4. 分析一致性(可选,验证规划质量) +/speckit.analyze + +# 5. 生成任务列表 +/speckit.tasks + +# 6. 再次分析一致性(推荐) +/speckit.analyze + +# 7. 执行实现 +/speckit.implement + +# 8. 代码审查和合并 +# - 验证宪章符合性 +# - 确保所有测试通过 +# - 检查代码覆盖率 +``` + +--- + +### 最佳实践 + +#### 功能开发 +- ✅ 总是从 `/speckit.specify` 开始,明确需求 +- ✅ 使用 `/speckit.clarify` 消除歧义,避免返工 +- ✅ 在 `/speckit.plan` 后检查宪章符合性 +- ✅ 使用 `/speckit.analyze` 在实现前验证计划质量 + +#### 代码质量 +- ✅ 严格遵循 Handler → Service → Store → Model 分层 +- ✅ 所有业务逻辑必须有单元测试(90%+ 覆盖) +- ✅ 所有 API 端点必须有集成测试 +- ✅ 使用 GORM 而不是 `database/sql` +- ✅ 使用 Fiber 而不是 `net/http` +- ✅ 使用 sonic 而不是 `encoding/json` + +#### 测试 +- ✅ 测试文件与源文件同目录(`*_test.go`) +- ✅ 使用 Go 标准 testing 包 +- ✅ 测试独立可运行(使用 mock 或 testcontainers) +- ✅ 单元测试 < 100ms,集成测试 < 1s + +#### 性能 +- ✅ 批量操作使用 GORM 的批量方法 +- ✅ 耗时操作使用 Asynq 异步任务 +- ✅ 列表 API 必须分页(默认 20,最大 100) +- ✅ 确保数据库索引支持查询 + +#### API 设计 +- ✅ 使用统一 JSON 响应格式(code/message/data/timestamp) +- ✅ 错误消息中英文双语 +- ✅ 时间字段使用 ISO 8601 格式 +- ✅ 金额字段使用整数(分) + +--- + +### 文档结构 + +``` +.specify/ +├── memory/ +│ └── constitution.md # 项目宪章(开发核心原则) +└── templates/ + ├── spec-template.md # 功能规范模板 + ├── plan-template.md # 实现计划模板 + ├── tasks-template.md # 任务列表模板 + └── checklist-template.md # 检查清单模板 + +specs/ +└── ###-feature-name/ # 功能文档目录 + ├── spec.md # 功能规范 + ├── plan.md # 实现计划 + ├── research.md # 技术调研 + ├── data-model.md # 数据模型 + ├── quickstart.md # 快速开始 + ├── contracts/ # API 契约 + └── tasks.md # 任务列表 +``` + +--- + +### 常见问题 + +**Q: 为什么要使用 Speckit?** +A: Speckit 确保团队遵循统一的开发流程,减少沟通成本,提高代码质量和可维护性。 + +**Q: 可以跳过某些步骤吗?** +A: 不推荐。每个步骤都有明确目的,跳过可能导致需求不清、架构不合理或测试不足。 + +**Q: 如何处理紧急修复?** +A: 小型修复可以简化流程,但仍需遵循宪章原则(技术栈、测试、代码质量)。 + +**Q: 宪章可以修改吗?** +A: 可以,使用 `/speckit.constitution` 修改。修改需要团队共识,并会自动同步所有模板。 + +**Q: 测试覆盖率达不到 70% 怎么办?** +A: 核心业务逻辑必须达到 90%+。工具函数、简单的 getter/setter 可以适当放宽,但总体必须 > 70%。