speckit使用规则更新

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%。