# OpenSpec Instructions Instructions for AI coding assistants using OpenSpec for spec-driven development. ## TL;DR Quick Checklist - Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search) - Decide scope: new capability vs modify existing capability - Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) - Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability - Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement - Validate: `openspec validate [change-id] --strict` and fix issues - Request approval: Do not start implementation until proposal is approved ## Three-Stage Workflow ### Stage 1: Creating Changes Create proposal when you need to: - Add features or functionality - Make breaking changes (API, schema) - Change architecture or patterns - Optimize performance (changes behavior) - Update security patterns Triggers (examples): - "Help me create a change proposal" - "Help me plan a change" - "Help me create a proposal" - "I want to create a spec proposal" - "I want to create a spec" Loose matching guidance: - Contains one of: `proposal`, `change`, `spec` - With one of: `create`, `plan`, `make`, `start`, `help` Skip proposal for: - Bug fixes (restore intended behavior) - Typos, formatting, comments - Dependency updates (non-breaking) - Configuration changes - Tests for existing behavior **Workflow** 1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. 2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. 3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. 4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. ### Stage 2: Implementing Changes Track these steps as TODOs and complete them one by one. 1. **Read proposal.md** - Understand what's being built 2. **Read design.md** (if exists) - Review technical decisions 3. **Read tasks.md** - Get implementation checklist 4. **Implement tasks sequentially** - Complete in order 5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses 6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality 7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved ### Stage 3: Archiving Changes After deployment, create separate PR to: - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` - Update `specs/` if capabilities changed - Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly) - Run `openspec validate --strict` to confirm the archived change passes checks ## Before Any Task **Context Checklist:** - [ ] Read relevant specs in `specs/[capability]/spec.md` - [ ] Check pending changes in `changes/` for conflicts - [ ] Read `openspec/project.md` for conventions - [ ] Run `openspec list` to see active changes - [ ] Run `openspec list --specs` to see existing capabilities **Before Creating Specs:** - Always check if capability already exists - Prefer modifying existing specs over creating duplicates - Use `openspec show [spec]` to review current state - If request is ambiguous, ask 1–2 clarifying questions before scaffolding ### Search Guidance - Enumerate specs: `openspec spec list --long` (or `--json` for scripts) - Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available) - Show details: - Spec: `openspec show --type spec` (use `--json` for filters) - Change: `openspec show --json --deltas-only` - Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs` ## Quick Start ### CLI Commands ```bash # Essential commands openspec list # List active changes openspec list --specs # List specifications openspec show [item] # Display change or spec openspec validate [item] # Validate changes or specs openspec archive [--yes|-y] # Archive after deployment (add --yes for non-interactive runs) # Project management openspec init [path] # Initialize OpenSpec openspec update [path] # Update instruction files # Interactive mode openspec show # Prompts for selection openspec validate # Bulk validation mode # Debugging openspec show [change] --json --deltas-only openspec validate [change] --strict ``` ### Command Flags - `--json` - Machine-readable output - `--type change|spec` - Disambiguate items - `--strict` - Comprehensive validation - `--no-interactive` - Disable prompts - `--skip-specs` - Archive without spec updates - `--yes`/`-y` - Skip confirmation prompts (non-interactive archive) ## Directory Structure ``` openspec/ ├── project.md # Project conventions ├── specs/ # Current truth - what IS built │ └── [capability]/ # Single focused capability │ ├── spec.md # Requirements and scenarios │ └── design.md # Technical patterns ├── changes/ # Proposals - what SHOULD change │ ├── [change-name]/ │ │ ├── proposal.md # Why, what, impact │ │ ├── tasks.md # Implementation checklist │ │ ├── design.md # Technical decisions (optional; see criteria) │ │ └── specs/ # Delta changes │ │ └── [capability]/ │ │ └── spec.md # ADDED/MODIFIED/REMOVED │ └── archive/ # Completed changes ``` ## Creating Change Proposals ### Decision Tree ``` New request? ├─ Bug fix restoring spec behavior? → Fix directly ├─ Typo/format/comment? → Fix directly ├─ New feature/capability? → Create proposal ├─ Breaking change? → Create proposal ├─ Architecture change? → Create proposal └─ Unclear? → Create proposal (safer) ``` ### Proposal Structure 1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique) 2. **Write proposal.md:** ```markdown ## Why [1-2 sentences on problem/opportunity] ## What Changes - [Bullet list of changes] - [Mark breaking changes with **BREAKING**] ## Impact - Affected specs: [list capabilities] - Affected code: [key files/systems] ``` 3. **Create spec deltas:** `specs/[capability]/spec.md` ```markdown ## ADDED Requirements ### Requirement: New Feature The system SHALL provide... #### Scenario: Success case - **WHEN** user performs action - **THEN** expected result ## MODIFIED Requirements ### Requirement: Existing Feature [Complete modified requirement] ## REMOVED Requirements ### Requirement: Old Feature **Reason**: [Why removing] **Migration**: [How to handle] ``` If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability. 4. **Create tasks.md:** ```markdown ## 1. Implementation - [ ] 1.1 Create database schema - [ ] 1.2 Implement API endpoint - [ ] 1.3 Add frontend component - [ ] 1.4 Write tests ``` 5. **Create design.md when needed:** Create `design.md` if any of the following apply; otherwise omit it: - Cross-cutting change (multiple services/modules) or a new architectural pattern - New external dependency or significant data model changes - Security, performance, or migration complexity - Ambiguity that benefits from technical decisions before coding Minimal `design.md` skeleton: ```markdown ## Context [Background, constraints, stakeholders] ## Goals / Non-Goals - Goals: [...] - Non-Goals: [...] ## Decisions - Decision: [What and why] - Alternatives considered: [Options + rationale] ## Risks / Trade-offs - [Risk] → Mitigation ## Migration Plan [Steps, rollback] ## Open Questions - [...] ``` ## Spec File Format ### Critical: Scenario Formatting **CORRECT** (use #### headers): ```markdown #### Scenario: User login success - **WHEN** valid credentials provided - **THEN** return JWT token ``` **WRONG** (don't use bullets or bold): ```markdown - **Scenario: User login** ❌ **Scenario**: User login ❌ ### Scenario: User login ❌ ``` Every requirement MUST have at least one scenario. ### Requirement Wording - Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative) ### Delta Operations - `## ADDED Requirements` - New capabilities - `## MODIFIED Requirements` - Changed behavior - `## REMOVED Requirements` - Deprecated features - `## RENAMED Requirements` - Name changes Headers matched with `trim(header)` - whitespace ignored. #### When to use ADDED vs MODIFIED - ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement. - MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details. - RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name. Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead. Authoring a MODIFIED requirement correctly: 1) Locate the existing requirement in `openspec/specs//spec.md`. 2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios). 3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior. 4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`. Example for RENAMED: ```markdown ## RENAMED Requirements - FROM: `### Requirement: Login` - TO: `### Requirement: User Authentication` ``` ## Troubleshooting ### Common Errors **"Change must have at least one delta"** - Check `changes/[name]/specs/` exists with .md files - Verify files have operation prefixes (## ADDED Requirements) **"Requirement must have at least one scenario"** - Check scenarios use `#### Scenario:` format (4 hashtags) - Don't use bullet points or bold for scenario headers **Silent scenario parsing failures** - Exact format required: `#### Scenario: Name` - Debug with: `openspec show [change] --json --deltas-only` ### Validation Tips ```bash # Always use strict mode for comprehensive checks openspec validate [change] --strict # Debug delta parsing openspec show [change] --json | jq '.deltas' # Check specific requirement openspec show [spec] --json -r 1 ``` ## Happy Path Script ```bash # 1) Explore current state openspec spec list --long openspec list # Optional full-text search: # rg -n "Requirement:|Scenario:" openspec/specs # rg -n "^#|Requirement:" openspec/changes # 2) Choose change id and scaffold CHANGE=add-two-factor-auth mkdir -p openspec/changes/$CHANGE/{specs/auth} printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md # 3) Add deltas (example) cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF' ## ADDED Requirements ### Requirement: Two-Factor Authentication Users MUST provide a second factor during login. #### Scenario: OTP required - **WHEN** valid credentials are provided - **THEN** an OTP challenge is required EOF # 4) Validate openspec validate $CHANGE --strict ``` ## Multi-Capability Example ``` openspec/changes/add-2fa-notify/ ├── proposal.md ├── tasks.md └── specs/ ├── auth/ │ └── spec.md # ADDED: Two-Factor Authentication └── notifications/ └── spec.md # ADDED: OTP email notification ``` auth/spec.md ```markdown ## ADDED Requirements ### Requirement: Two-Factor Authentication ... ``` notifications/spec.md ```markdown ## ADDED Requirements ### Requirement: OTP Email Notification ... ``` ## Best Practices ### Simplicity First - Default to <100 lines of new code - Single-file implementations until proven insufficient - Avoid frameworks without clear justification - Choose boring, proven patterns ### Complexity Triggers Only add complexity with: - Performance data showing current solution too slow - Concrete scale requirements (>1000 users, >100MB data) - Multiple proven use cases requiring abstraction ### Clear References - Use `file.ts:42` format for code locations - Reference specs as `specs/auth/spec.md` - Link related changes and PRs ### Capability Naming - Use verb-noun: `user-auth`, `payment-capture` - Single purpose per capability - 10-minute understandability rule - Split if description needs "AND" ### Change ID Naming - Use kebab-case, short and descriptive: `add-two-factor-auth` - Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-` - Ensure uniqueness; if taken, append `-2`, `-3`, etc. ## Tool Selection Guide | Task | Tool | Why | |------|------|-----| | Find files by pattern | Glob | Fast pattern matching | | Search code content | Grep | Optimized regex search | | Read specific files | Read | Direct file access | | Explore unknown scope | Task | Multi-step investigation | ## Error Recovery ### Change Conflicts 1. Run `openspec list` to see active changes 2. Check for overlapping specs 3. Coordinate with change owners 4. Consider combining proposals ### Validation Failures 1. Run with `--strict` flag 2. Check JSON output for details 3. Verify spec file format 4. Ensure scenarios properly formatted ### Missing Context 1. Read project.md first 2. Check related specs 3. Review recent archives 4. Ask for clarification ## Quick Reference ### Stage Indicators - `changes/` - Proposed, not yet built - `specs/` - Built and deployed - `archive/` - Completed changes ### File Purposes - `proposal.md` - Why and what - `tasks.md` - Implementation steps - `design.md` - Technical decisions - `spec.md` - Requirements and behavior ### CLI Essentials ```bash openspec list # What's in progress? openspec show [item] # View details openspec validate --strict # Is it correct? openspec archive [--yes|-y] # Mark complete (add --yes for automation) ``` Remember: Specs are truth. Changes are proposals. Keep them in sync. --- # Project-Specific Development Guidelines 以下是本项目的开发规范，所有 AI 助手在创建提案和实现代码时必须遵守。 ## 语言要求 **必须遵守:** - 永远用中文交互 - 注释必须使用中文 - 文档必须使用中文 - 日志消息必须使用中文 - 用户可见的错误消息必须使用中文 - 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范） - Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳 ## 核心开发原则 ### 技术栈遵守 **必须遵守 (MUST):** - 开发时严格遵守项目定义的技术栈：Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL - 禁止使用原生调用或绕过框架的快捷方式（禁止 `database/sql` 直接调用、禁止 `net/http` 替代 Fiber、禁止 `encoding/json` 替代 sonic） - 所有 HTTP 路由和中间件必须使用 Fiber 框架 - 所有数据库操作必须通过 GORM 进行 - 所有配置管理必须使用 Viper - 所有日志记录必须使用 Zap + Lumberjack.v2 - 所有 JSON 序列化优先使用 sonic，仅在必须使用标准库的场景才使用 `encoding/json` - 所有异步任务必须使用 Asynq - 必须使用 Go 官方工具链：`go fmt`、`go vet`、`golangci-lint` - 必须使用 Go Modules 进行依赖管理 **理由:** 一致的技术栈使用确保代码可维护性、团队协作效率和长期技术债务可控。绕过框架的"快捷方式"会导致代码碎片化、难以调试、性能不一致和安全漏洞。 ### 代码质量标准 **架构分层:** - 代码必须遵循项目分层架构：`Handler → Service → Store → Model` - Handler 层只能处理 HTTP 请求/响应，不得包含业务逻辑 - Service 层包含所有业务逻辑，支持跨模块调用 - Store 层统一管理所有数据访问，支持事务处理 - Model 层定义清晰的数据结构和 DTO - 所有依赖通过结构体字段进行依赖注入（不使用构造函数模式） **错误和响应处理:** - 所有公共错误必须在 `pkg/errors/` 中定义，使用统一错误码 - 所有 API 响应必须使用 `pkg/response/` 的统一格式 - 所有常量必须在 `pkg/constants/` 中定义和管理 - 所有 Redis key 必须通过 `pkg/constants/` 中的 Key 生成函数统一管理 **代码注释和文档:** - 必须为所有导出的函数、类型和常量编写 Go 风格的文档注释（`// FunctionName does something...`） - 代码注释（implementation comments）应该使用中文 - 日志消息应该使用中文 - 用户可见的错误消息必须使用中文（通过 `pkg/errors/` 的双语消息支持） - Go 文档注释（doc comments for exported APIs）可以使用英文以保持生态兼容性，但中文注释更佳 - 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范） **Go 代码风格要求:** - 必须使用 `gofmt` 格式化所有代码 - 必须遵循 [Effective Go](https://go.dev/doc/effective_go) 和 [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) - 变量命名必须使用 Go 风格：`userID`（不是 `userId`）、`HTTPServer`（不是 `HttpServer`） - 缩写词必须全部大写或全部小写：`URL`、`ID`、`HTTP`（导出）或 `url`、`id`、`http`（未导出） - 包名必须简短、小写、单数、无下划线：`user`、`order`、`pkg`（不是 `users`、`userService`、`user_service`） - 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Logger`（不是 `ILogger`、`LoggerInterface`） **常量管理规范:** - 业务常量（状态码、类型枚举等）必须定义在 `pkg/constants/constants.go` 或按模块分文件 - Redis key 必须使用函数生成，不允许硬编码字符串拼接 - Redis key 生成函数必须遵循命名规范：`Redis{Module}{Purpose}Key(params...)` - Redis key 格式必须使用冒号分隔：`{module}:{purpose}:{identifier}` - 禁止在代码中直接使用 magic numbers（未定义含义的数字字面量） - 禁止在代码中硬编码字符串字面量（URL、状态码、配置值、业务规则等） - 当相同的字面量值在 3 个或以上位置使用时，必须提取为常量 - 已定义的常量必须被使用，禁止重复硬编码相同的值 **函数复杂度和职责分离:** - 函数长度不得超过合理范围（通常 50-100 行，核心逻辑建议 ≤ 50 行） - 超过 100 行的函数必须拆分为多个小函数，每个函数只负责一件事 - `main()` 函数只做编排（orchestration），不包含具体实现逻辑 - `main()` 函数中的每个初始化步骤应该提取为独立的辅助函数 - 编排函数必须清晰表达流程，避免嵌套的实现细节 - 必须遵循单一职责原则（Single Responsibility Principle） ## Go 语言惯用设计原则 **核心理念：写 Go 味道的代码，不要写 Java 味道的代码** **包组织:** - 包结构必须扁平化，避免深层嵌套（最多 2-3 层） - 包必须按功能组织，不是按层次组织 - 包名必须描述功能，不是类型（`http` 不是 `httputils`、`handlers`）推荐的 Go 风格结构: ``` internal/ ├── user/ # user 功能的所有代码 │ ├── handler.go # HTTP handlers │ ├── service.go # 业务逻辑 │ ├── store.go # 数据访问 │ └── model.go # 数据模型 ├── order/ └── sim/ ``` **接口设计:** - 接口必须小而专注（1-3 个方法），不是大而全 - 接口应该在使用方定义，不是实现方（依赖倒置） - 接口命名应该使用 `-er` 后缀：`Reader`、`Writer`、`Storer` - 禁止使用 `I` 前缀或 `Interface` 后缀 - 禁止创建只有一个实现的接口（除非明确需要抽象） **错误处理:** - 错误必须显式返回和检查，不使用异常（panic/recover） - 错误处理必须紧跟错误产生的代码 - 必须使用 `errors.Is()` 和 `errors.As()` 检查错误类型 - 必须使用 `fmt.Errorf()` 包装错误，保留错误链 - 自定义错误应该实现 `error` 接口 - panic 只能用于不可恢复的程序错误 **结构体和方法:** - 结构体必须简单直接，不是类（class）的替代品 - 禁止为每个字段创建 getter/setter 方法 - 必须直接访问导出的字段（大写开头） - 必须使用组合（composition）而不是继承（inheritance） - 构造函数应该命名为 `New` 或 `NewXxx`，返回具体类型 - 禁止使用构造器模式（Builder Pattern）除非真正需要 **并发模式:** - 必须使用 goroutines 和 channels，不是线程和锁（大多数情况） - 必须使用 `context.Context` 传递取消信号 - 必须遵循"通过通信共享内存，不要通过共享内存通信" - 应该使用 `sync.WaitGroup` 等待 goroutines 完成 - 应该使用 `sync.Once` 确保只执行一次 - 禁止创建线程池类（Go 运行时已处理） **命名约定:** - 变量名必须简短且符合上下文（短作用域用短名字：`i`, `j`, `k`；长作用域用描述性名字） - 缩写词必须保持一致的大小写：`URL`, `HTTP`, `ID`（不是 `Url`, `Http`, `Id`） - 禁止使用匈牙利命名法或类型前缀：`strName`, `arrUsers` - 禁止使用下划线连接（除了测试和包名） - 方法接收者名称应该使用 1-2 个字母的缩写，全文件保持一致 **严格禁止的 Java 风格模式:** 1. ❌ 过度抽象（不需要的接口、工厂、构造器） 2. ❌ Getter/Setter（直接访问导出字段） 3. ❌ 继承层次（使用组合，不是嵌入） 4. ❌ 异常处理（使用错误返回，不是 panic/recover） 5. ❌ 单例模式（使用包级别变量或 `sync.Once`） 6. ❌ 线程池（直接使用 goroutines） 7. ❌ 深层包嵌套（保持扁平结构） 8. ❌ 类型前缀（`IService`, `AbstractBase`, `ServiceImpl`） 9. ❌ Bean 风格（不需要 POJO/JavaBean 模式） 10. ❌ 过度 DI 框架（简单直接的依赖注入） ## 测试标准 **测试要求:** - 所有核心业务逻辑（Service 层）必须有单元测试覆盖 - 所有 API 端点必须有集成测试覆盖 - 所有数据库操作应该有事务回滚测试 - 测试必须使用 Go 标准测试框架（`testing` 包） - 测试文件必须与源文件同目录，命名为 `*_test.go` - 测试函数必须使用 `Test` 前缀：`func TestUserCreate(t *testing.T)` - 基准测试必须使用 `Benchmark` 前缀：`func BenchmarkUserCreate(b *testing.B)` **测试性能要求:** - 测试必须可独立运行，不依赖外部服务（使用 mock 或 testcontainers） - 单元测试必须在 100ms 内完成 - 集成测试应该在 1s 内完成 - 测试覆盖率应该达到 70% 以上（核心业务代码必须 90% 以上） **测试最佳实践:** - 测试必须使用 table-driven tests 处理多个测试用例 - 测试必须使用 `t.Helper()` 标记辅助函数 ## 数据库设计原则 **核心规则:** - 数据库表之间禁止建立外键约束（Foreign Key Constraints） - GORM 模型之间禁止使用 ORM 关联关系（`foreignKey`、`references`、`hasMany`、`belongsTo` 等标签） - 表之间的关联必须通过存储关联 ID 字段手动维护 - 关联数据查询必须在代码层面显式执行，不依赖 ORM 的自动加载或预加载 - 模型结构体只能包含简单字段，不应包含其他模型的嵌套引用 - 数据库迁移脚本禁止包含外键约束定义 - 数据库迁移脚本禁止包含触发器用于维护关联数据 - 时间字段（`created_at`、`updated_at`）的更新必须由 GORM 自动处理，不使用数据库触发器 **设计理由:** 1. **灵活性**：业务逻辑完全在代码中控制，不受数据库约束限制 2. **性能**：无外键约束意味着无数据库层面的引用完整性检查开销 3. **简单直接**：显式的关联数据查询使数据流向清晰可见 4. **可控性**：开发者完全掌控何时查询关联数据、查询哪些关联数据 5. **可维护性**：数据库 schema 更简单，迁移更容易 6. **分布式友好**：在微服务和分布式数据库场景下更容易扩展 ## API 设计规范 **统一响应格式:** 所有 API 响应必须使用统一的 JSON 格式： ```json { "code": 0, "message": "success", "data": {}, "timestamp": "2025-11-10T15:30:00Z" } ``` **API 设计要求:** - 所有错误响应必须包含明确的错误码和错误消息（中英文双语） - 所有 API 端点必须遵循 RESTful 设计原则 - 所有分页 API 必须使用统一的分页参数：`page`、`page_size`、`total` - 所有时间字段必须使用 ISO 8601 格式（RFC3339） - 所有货币金额必须使用整数表示（分为单位），避免浮点精度问题 - 所有布尔字段必须使用 `true`/`false`，不使用 `0`/`1` - API 版本必须通过 URL 路径管理（如 `/api/v1/...`） ## 错误处理规范 **统一错误处理:** - 所有 API 错误响应必须使用统一的 JSON 格式（通过 `pkg/errors/` 全局 ErrorHandler） - 所有 Handler 层错误必须通过返回 `error` 传递给全局 ErrorHandler，禁止手动构造错误响应 - 所有业务错误必须使用 `pkg/errors.New()` 或 `pkg/errors.Wrap()` 创建 `AppError`，并指定错误码 - 所有错误码必须在 `pkg/errors/codes.go` 中统一定义和管理 **Panic 处理:** - 所有 Panic 必须被 Recover 中间件自动捕获，转换为 500 错误响应 - 禁止在业务代码中主动 `panic`（除非遇到不可恢复的编程错误） - 禁止在 Handler 中直接使用 `c.Status().JSON()` 返回错误响应 **错误日志:** - 所有错误日志必须包含完整的请求上下文（Request ID、路径、方法、参数等） - 5xx 服务端错误必须自动脱敏，只返回通用错误消息，原始错误仅记录到日志 - 4xx 客户端错误可以返回具体业务错误消息（如"用户名已存在"） **错误码分类:** - `0`: 成功 - `1000-1999`: 客户端错误（4xx HTTP 状态码，日志级别 Warn） - `2000-2999`: 服务端错误（5xx HTTP 状态码，日志级别 Error） ## 访问日志规范 **核心要求:** - 所有 HTTP 请求必须被记录到 `access.log`，无例外 - 访问日志必须记录完整的请求参数（query 参数 + request body） - 访问日志必须记录完整的响应参数（response body） - 请求/响应 body 必须限制大小为 50KB，超过部分截断并标注 `... (truncated)` - 访问日志必须通过统一的 Logger 中间件（`pkg/logger/Middleware()`）记录 - 任何中间件的短路返回（认证失败、限流拒绝、参数验证失败等）禁止绕过访问日志 **必需字段:** 访问日志必须包含以下字段： - `method`: HTTP 方法 - `path`: 请求路径 - `query`: Query 参数字符串 - `status`: HTTP 状态码 - `duration_ms`: 请求耗时（毫秒） - `request_id`: 请求唯一 ID - `ip`: 客户端 IP - `user_agent`: 用户代理 - `user_id`: 用户 ID（认证后有值，否则为空） - `request_body`: 请求体（限制 50KB） - `response_body`: 响应体（限制 50KB） **日志配置:** - 访问日志应该使用 JSON 格式，便于日志分析和监控 - 访问日志文件必须配置自动轮转（基于大小或时间） ## 性能要求 **性能指标:** - API 响应时间（P95）必须 < 200ms（数据库查询 < 50ms） - API 响应时间（P99）必须 < 500ms - 批量操作必须使用批量查询/插入，避免 N+1 查询问题 - 所有数据库查询必须有适当的索引支持 - 列表查询必须实现分页，默认 `page_size=20`，最大 `page_size=100` - 异步任务必须用于非实时操作（批量同步、分佣计算等） **资源限制:** - 内存使用（API 服务）应该 < 500MB（正常负载） - 内存使用（Worker 服务）应该 < 1GB（正常负载） - 数据库连接池必须配置合理（`MaxOpenConns=25`, `MaxIdleConns=10`, `ConnMaxLifetime=5m`） - Redis 连接池必须配置合理（`PoolSize=10`, `MinIdleConns=5`） **并发处理:** - 并发操作应该使用 goroutines 和 channels（不是线程池模式） - 必须使用 `context.Context` 进行超时和取消控制 - 必须使用 `sync.Pool` 复用频繁分配的对象（如缓冲区） ## 文档规范 **文档结构要求:** - 每个功能完成后必须在 `docs/` 目录创建总结文档 - 总结文档路径必须遵循规范：`docs/{feature-id}/` 对应 `specs/{feature-id}/` - 总结文档文件名必须使用中文命名（例如：`功能总结.md`、`使用指南.md`、`架构说明.md`） - 总结文档内容必须使用中文编写 - 每次添加新功能总结文档时必须同步更新 `README.md` **README.md 更新要求:** - README.md 中的功能描述必须简短精炼，让首次接触项目的开发者能快速了解 - README.md 的功能描述应该控制在 2-3 句话以内 - 使用中文，便于中文开发者快速理解 - 提供到详细文档的链接 - 按功能模块分组（如"核心功能"、"中间件"、"业务模块"等） --- ## 提案创建检查清单在创建 OpenSpec 提案时，请确保： 1. ✅ **技术栈合规**: 提案中的技术选型必须符合项目技术栈要求 2. ✅ **架构分层**: 设计必须遵循 Handler → Service → Store → Model 分层 3. ✅ **错误处理**: 错误处理方案必须使用统一的 `pkg/errors/` 系统 4. ✅ **常量管理**: 新增常量必须定义在 `pkg/constants/` 5. ✅ **Go 风格**: 代码设计必须遵循 Go 惯用法，避免 Java 风格 6. ✅ **测试要求**: 提案必须包含测试计划（单元测试 + 集成测试） 7. ✅ **性能考虑**: 需要考虑性能指标和资源限制 8. ✅ **文档计划**: 提案必须包含文档更新计划 9. ✅ **中文优先**: 所有文档、注释、日志必须使用中文 ## 实现检查清单在实现 OpenSpec 提案时，请确保： 1. ✅ **代码格式**: 所有代码已通过 `gofmt` 格式化 2. ✅ **代码检查**: 所有代码已通过 `go vet` 和 `golangci-lint` 检查 3. ✅ **测试覆盖**: 核心业务逻辑测试覆盖率 ≥ 90% 4. ✅ **性能测试**: API 响应时间符合性能指标要求 5. ✅ **错误处理**: 所有错误已正确处理和记录 6. ✅ **文档更新**: README.md 和功能文档已更新 7. ✅ **迁移脚本**: 数据库变更已创建迁移脚本 8. ✅ **日志记录**: 关键操作已添加访问日志和业务日志 9. ✅ **代码审查**: 代码已通过团队审查