refactor: align framework cleanup with new bootstrap flow

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2025-11-19 12:47:25 +08:00
parent 39d14ec093
commit d66323487b
67 changed files with 3020 additions and 3992 deletions
--- a/openspec/AGENTS.md
+++ b/openspec/AGENTS.md
@@ -0,0 +1,826 @@
+# 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/<id>/`.
+3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
+4. Run `openspec validate <id> --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 <change-id> --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 <spec-id> --type spec` (use `--json` for filters)
+  - Change: `openspec show <change-id> --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 <change-id> [--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/<capability>/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/<capability>/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 <change-id> [--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. ✅ **代码审查**: 代码已通过团队审查