csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

refactor: align framework cleanup with new bootstrap flow

Browse Source 
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
huang
2025-11-19 12:47:25 +08:00
parent 39d14ec093
commit d66323487b
67 changed files with 3020 additions and 3992 deletions
Download Patch File Download Diff File Expand all files Collapse all files

826
openspec/AGENTS.md Normal file
View File

@@ -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. ✅ **代码审查**: 代码已通过团队审查

422
openspec/changes/refactor-framework-cleanup/design.md Normal file
View File

@@ -0,0 +1,422 @@
## Context
当前项目处于框架搭建阶段，存在多处技术债务需要清理：
- 两套 Auth 实现产生于不同开发阶段，未整合
- 示例代码（user/order）是早期测试用途，现已有真实 RBAC 代码
- pkg/errors 和 pkg/response 设计时职责划分不清晰
- DataPermissionScope 实现完整但从未集成使用
**约束条件**：
- 必须保持 Go 惯用模式，避免 Java 风格过度抽象
- main.go 在未来开发中应该不需要修改
- 数据权限过滤必须支持绕过机制
## Goals / Non-Goals
### Goals
- 清理所有示例和重复代码，使框架干净整洁
- 统一认证、错误处理、响应格式的实现方式
- 实现数据权限的 GORM 自动化过滤
- 将组件初始化从 main.go 解耦，支持未来扩展
- 在关键扩展点添加 TODO 标记
### Non-Goals
- 不实现完整的 DI 框架（保持 Go 简洁风格）
- 不实现自动注册机制（使用显式工厂模式）
- 不重构现有 RBAC 业务逻辑
- 不添加新的业务功能
## Decisions
### Decision 1: Auth 中间件合并策略
**选择**：重新设计合并版本
**实现方案**：
```go
// pkg/middleware/auth.go - 合并版本
type AuthConfig struct {
TokenExtractor func(*fiber.Ctx) string // 自定义 token 提取
SkipPaths []string // 跳过认证的路径
Validator func(string) (*UserInfo, error) // token 验证函数
}
func Auth(cfg AuthConfig) fiber.Handler {
return func(c *fiber.Ctx) error {
// 1. 检查跳过路径
// 2. 提取 token
// 3. 验证 token
// 4. 设置用户上下文（同时设置 Locals 和 Context）
// 5. 错误统一返回 AppError，由全局 ErrorHandler 处理
}
}
```
**理由**：
- 合并两者优点：pkg 版本的可配置性 + internal 版本的统一错误格式
- 统一使用 `return errors.New()` 让全局 ErrorHandler 处理
- 消除错误格式不一致问题
### Decision 2: 组件注册解耦策略
**选择**：Bootstrap 包 + 按模块拆分 + 工厂函数模式
**实现方案**：
```
internal/bootstrap/
├── bootstrap.go # 主入口，编排初始化流程
├── dependencies.go # Dependencies 结构体定义
├── stores.go # 所有 Store 初始化逻辑
├── services.go # 所有 Service 初始化逻辑
├── handlers.go # 所有 Handler 初始化逻辑
└── types.go # Handlers 结构体定义
```
**bootstrap.go** - 主入口编排：
```go
// Bootstrap 初始化所有组件并返回 Handlers
func Bootstrap(deps *Dependencies) (*Handlers, error) {
// 1. 初始化 GORM Callback（必须在 Store 之前）
if err := registerGORMCallbacks(deps.DB); err != nil {
return nil, err
}
// 2. 初始化 Stores
stores := initStores(deps)
// 3. 初始化 Services
services := initServices(stores)
// 4. 初始化 Handlers
handlers := initHandlers(services)
return handlers, nil
}
```
**stores.go** - Store 层初始化：
```go
type Stores struct {
Account *postgres.AccountStore
Role *postgres.RoleStore
Permission *postgres.PermissionStore
AccountRole *postgres.AccountRoleStore
RolePermission *postgres.RolePermissionStore
// TODO: 新增 Store 在此添加字段
}
func initStores(deps *Dependencies) *Stores {
return &Stores{
Account: postgres.NewAccountStore(deps.DB, deps.Redis),
Role: postgres.NewRoleStore(deps.DB),
Permission: postgres.NewPermissionStore(deps.DB),
AccountRole: postgres.NewAccountRoleStore(deps.DB),
RolePermission: postgres.NewRolePermissionStore(deps.DB),
// TODO: 新增 Store 在此初始化
}
}
```
**services.go** - Service 层初始化：
```go
type Services struct {
Account *accountSvc.Service
Role *roleSvc.Service
Permission *permissionSvc.Service
// TODO: 新增 Service 在此添加字段
}
func initServices(stores *Stores) *Services {
return &Services{
Account: accountSvc.New(stores.Account, stores.Role, stores.AccountRole),
Role: roleSvc.New(stores.Role, stores.Permission, stores.RolePermission),
Permission: permissionSvc.New(stores.Permission),
// TODO: 新增 Service 在此初始化
}
}
```
**handlers.go** - Handler 层初始化：
```go
func initHandlers(services *Services) *Handlers {
return &Handlers{
Account: handler.NewAccountHandler(services.Account),
Role: handler.NewRoleHandler(services.Role),
Permission: handler.NewPermissionHandler(services.Permission),
// TODO: 新增 Handler 在此初始化
}
}
```
**types.go** - 类型定义：
```go
// Handlers 封装所有 HTTP 处理器
type Handlers struct {
Account *handler.AccountHandler
Role *handler.RoleHandler
Permission *handler.PermissionHandler
// TODO: 新增 Handler 在此添加字段
}
```
**dependencies.go** - 基础依赖：
```go
// Dependencies 封装所有基础依赖
type Dependencies struct {
DB *gorm.DB
Redis *redis.Client
Logger *zap.Logger
}
```
**main.go 简化后**：
```go
func main() {
// 初始化基础依赖
deps := initDependencies()
// 一行完成所有业务组件初始化
handlers, err := bootstrap.Bootstrap(deps)
// 设置路由
routes.Setup(app, handlers)
// 启动服务
app.Listen(":8080")
}
```
**理由**：
- **按层次拆分**：stores.go、services.go、handlers.go 职责清晰
- **易于扩展**：每层只需在对应文件中添加初始化代码
- **文件大小可控**：每个文件 < 100 行，避免单文件臃肿
- **main.go 零修改**：新增业务只修改 bootstrap 内部文件
- **符合 Go 风格**：显式依赖注入，不使用复杂的 DI 框架
- **TODO 标记清晰**：每层都有明确的扩展点标记
### Decision 3: 数据权限 GORM Callback 实现
**选择**：GORM Callback 自动化 + Context 绕过机制
**实现方案**：
```go
// pkg/gorm/callback.go
type contextKey string
const SkipDataPermissionKey contextKey = "skip_data_permission"
// SkipDataPermission 返回跳过数据权限过滤的 Context
func SkipDataPermission(ctx context.Context) context.Context {
return context.WithValue(ctx, SkipDataPermissionKey, true)
}
// RegisterDataPermissionCallback 注册 GORM Callback
func RegisterDataPermissionCallback(db *gorm.DB, accountStore AccountStoreInterface) {
db.Callback().Query().Before("gorm:query").Register("data_permission", func(tx *gorm.DB) {
ctx := tx.Statement.Context
// 检查是否跳过
if skip, ok := ctx.Value(SkipDataPermissionKey).(bool); ok && skip {
return
}
// 检查 root 用户
if middleware.IsRootUser(ctx) {
return
}
// 获取用户下级 ID 并应用过滤
userID := middleware.GetUserIDFromContext(ctx)
subordinateIDs, _ := accountStore.GetSubordinateIDs(ctx, userID)
// 只对包含 owner_id 字段的表应用过滤
if hasOwnerIDField(tx.Statement.Schema) {
tx.Where("owner_id IN ?", subordinateIDs)
}
})
}
```
**使用方式**：
```go
// 正常查询 - 自动应用数据权限过滤
db.WithContext(ctx).Find(&accounts)
// 绕过权限过滤（如管理员操作、内部同步）
ctx = gorm.SkipDataPermission(ctx)
db.WithContext(ctx).Find(&accounts)
```
**理由**：
- 完全自动化，开发者无需手动调用 Scope
- 通过 Context 控制绕过，符合 Go 惯用模式
- 只对包含 owner_id 的表生效，安全可控
- 删除现有未使用的 scopes.go 代码
### Decision 4: 简化 AppError 结构
**选择**：删除 AppError.HTTPStatus 字段和 WithHTTPStatus() 方法
**问题分析**：
```go
type AppError struct {
Code int // 业务错误码
Message string // 错误消息
HTTPStatus int // 冗余：总是从 Code 映射得到
Err error
}
```
**冗余之处**：
- HTTPStatus 字段总是通过 `GetHTTPStatus(code)` 从 Code 映射得到
- 存储 HTTPStatus 字段导致字段冗余
- WithHTTPStatus() 方法允许手动覆盖，可能导致状态码不一致
**优化方案**：
```go
type AppError struct {
Code int // 业务错误码
Message string // 错误消息
Err error // 底层错误（可选）
}
// 删除 WithHTTPStatus() 方法
// ErrorHandler 中直接调用 GetHTTPStatus(e.Code) 获取状态码
```
**理由**：
- **减少字段冗余**：HTTPStatus 可以实时计算，不需要存储
- **消除不一致风险**：禁止手动设置状态码，确保 Code 和 HTTPStatus 始终匹配
- **简化 AppError**：只保留核心字段（Code, Message, Err）
- **保持职责分离**：AppError 只负责错误表示，HTTPStatus 由 ErrorHandler 处理
### Decision 5: 错误处理统一策略
**选择**：删除 response.Error()，统一使用全局 ErrorHandler
**当前格式分析**：
```go
// pkg/errors/handler.go - 已经统一使用 msg
c.Status(httpStatus).JSON(fiber.Map{
"code": code,
"data": nil,
"msg": message, // 当前已是 msg
"timestamp": time.Now().Format(time.RFC3339),
})
// pkg/response/response.go - 已经统一使用 msg
type Response struct {
Code int `json:"code"`
Data any `json:"data"`
Message string `json:"msg"` // JSON 标签是 msg
Timestamp string `json:"timestamp"`
}
```
**问题**：
- `response.Error()` 函数允许手动构造错误响应，导致两种错误处理方式混用
- 需要手动传递 `httpStatus` 参数，容易出错
**解决方案**：
```go
// pkg/response/response.go
// 删除 Error() 函数，只保留:
func Success(c *fiber.Ctx, data interface{}) error
func SuccessWithMessage(c *fiber.Ctx, data interface{}, message string) error
func SuccessWithPagination(c *fiber.Ctx, items any, total int64, page, size int) error
```
**Handler 统一写法**：
```go
func (h *AccountHandler) Create(c *fiber.Ctx) error {
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
}
if err := h.service.Create(ctx, &req); err != nil {
return err // 直接返回，由 ErrorHandler 处理
}
return response.Success(c, account)
}
```
**统一响应格式**（仅包含 4 个字段）：
```json
{
"code": 0,
"msg": "success",
"data": {...},
"timestamp": "2025-11-19T..."
}
```
**理由**：
- **消除两种错误处理方式**：Handler 只能返回 error，不能手动构造错误响应
- **格式已统一**：错误和成功响应都使用 `msg` 字段
- **简化开发**：错误码到 HTTP 状态码的映射由 ErrorHandler 统一处理
- **避免字段冗余**：不返回 `httpstatus` 字段（HTTP 状态码已在响应头中）
## Risks / Trade-offs
### Risk 1: GORM Callback 性能开销
**风险**：每次查询都执行 Callback 可能影响性能
**缓解**：
- GetSubordinateIDs 已实现 Redis 缓存（30分钟）
- 通过 Schema 检查只对需要的表生效
- 监控查询性能，必要时优化
### Risk 2: 删除代码可能影响未知依赖
**风险**：示例代码可能被测试或文档引用
**缓解**：
- 搜索确认无任何引用
- 删除后运行完整测试
- 项目处于框架搭建阶段，风险可控
### Risk 3: Bootstrap 多文件维护成本
**风险**：拆分成多个文件后，需要在多处添加新业务模块
**缓解**：
- TODO 注释明确标记所有扩展点
- 保持文件结构简单清晰（stores.go, services.go, handlers.go）
- 每个文件只负责一层初始化，职责单一
- 每个文件保持 < 100 行，易于理解和维护
## Migration Plan
1. **Phase 1（清理）**：
- 删除示例代码（user/order）
- 合并 Auth 实现
- 验证现有功能不受影响
2. **Phase 2（解耦）**：
- 创建 bootstrap 包
- 重构 main.go
- 验证启动流程正常
3. **Phase 3（自动化）**：
- 实现 GORM Callback
- 删除 scopes.go
- 添加绕过机制测试
4. **Phase 4（规范化）**：
- 统一错误格式
- 删除 Error() 函数
- 更新所有 Handler 写法
**回滚策略**：
- 使用 Git 分支，每个 Phase 可独立回滚
- 保留删除代码的备份（或通过 Git 历史恢复）
## Open Questions
1. **owner_id 字段检测**：如何优雅地检测表是否需要数据权限过滤？
- 方案 A：检查 Schema 是否有 owner_id 字段
- 方案 B：使用接口标记（如 `DataPermissionAware`）
- 建议：先用方案 A，必要时再重构
2. **多租户支持**：shop_id 过滤是否也应该自动化？
- 当前 DataPermissionScope 支持 shop_id
- 建议：本次只自动化 owner_id，shop_id 作为 TODO
3. **Callback 注册时机**：应该在哪里注册 GORM Callback？
- 建议：在 bootstrap 包初始化 DB 后立即注册

63
openspec/changes/refactor-framework-cleanup/proposal.md Normal file
View File

@@ -0,0 +1,63 @@
## Why
当前框架存在多处设计冲突和代码冗余，影响可维护性和开发效率：
1. 存在两套 Auth 实现，错误返回格式不一致
2. Handler/Service/Store 需要在 main.go 中手动注册，难以扩展
3. 示例业务代码（user/order）未被清理，与真实 RBAC 代码混杂
4. pkg/errors 和 pkg/response 职责重叠，使用方式不统一
5. GORM 数据权限过滤已实现但未集成，自动化程度为 0%
## What Changes
### Phase 1: 清理和统一
- **BREAKING**: 删除所有示例业务代码（user/order 相关的 handler、service、store、model）
- 删除重复的 `internal/middleware/auth.go`，重新设计合并版本到 `pkg/middleware/auth.go`
- 简化 AppError 结构：删除 HTTPStatus 字段和 WithHTTPStatus() 方法
- 确认错误响应格式已统一（code, msg, data, timestamp 四个字段）
- 删除 `pkg/response/response.go` 中的 `Error()` 函数，Handler 统一返回 error
### Phase 2: 组件注册解耦（按模块拆分）
- 将 `main.go` 中的 `initServices()` 逻辑提取到 `internal/bootstrap/` 包
- 按层次拆分 bootstrap 包：`stores.go`, `services.go`, `handlers.go`
- 创建统一的组件工厂，使 main.go 不需要了解具体业务模块
- 每个文件添加 TODO 标记用于未来扩展点
- 避免单文件臃肿，每个文件保持 < 100 行
### Phase 3: 数据权限自动化
- 实现 GORM Callback 机制自动注入数据权限过滤
- 支持通过 Context 绕过权限过滤（SkipDataPermission）
- 删除未使用的 `scopes.go` 中的手动 Scope 函数
### Phase 4: 代码规范化
- 删除错误码别名，统一使用标准错误码
- 删除重复的 validator 实例，在启动时创建单例
## Impact
### Affected specs
- auth（新建）：统一认证中间件规范
- dependency-injection（新建）：组件注册和依赖注入规范
- data-permission（新建）：数据权限自动过滤规范
- error-handling（新建）：统一错误处理规范
### Affected code
- 删除文件（10+）：
- `internal/handler/user.go`, `internal/handler/order.go`
- `internal/model/user.go`, `internal/model/user_dto.go`
- `internal/model/order.go`, `internal/model/order_dto.go`
- `internal/service/user/`, `internal/service/order/`
- `internal/store/postgres/user_store.go`, `internal/store/postgres/order_store.go`
- `internal/middleware/auth.go`
- 重构文件：
- `cmd/api/main.go` → 简化，提取初始化逻辑
- `pkg/middleware/auth.go` → 重新设计，统一错误格式
- `pkg/errors/handler.go` → 统一 JSON 字段名
- `pkg/response/response.go` → 删除 Error() 函数
- `internal/store/postgres/` → 添加 GORM Callback 支持
- 新建文件：
- `internal/bootstrap/bootstrap.go` → 组件工厂和初始化逻辑
- `pkg/gorm/callback.go` → 数据权限 GORM Callback
### Migration
- 这是框架搭建阶段，无生产数据需要迁移
- 示例代码删除不影响任何现有功能

61
openspec/changes/refactor-framework-cleanup/specs/auth/spec.md Normal file
View File

@@ -0,0 +1,61 @@
## ADDED Requirements
### Requirement: Unified Authentication Middleware
系统 SHALL 提供统一的认证中间件，支持可配置的 Token 提取和验证。
#### Scenario: Token 验证成功
- **WHEN** 请求携带有效的 Token
- **THEN** 中间件提取并验证 Token
- **AND** 将用户信息同时设置到 Fiber Locals 和 Context
- **AND** 请求继续执行
#### Scenario: Token 缺失
- **WHEN** 请求未携带 Token
- **AND** 路径不在跳过列表中
- **THEN** 返回 AppError（CodeMissingToken）
- **AND** 由全局 ErrorHandler 处理错误响应
#### Scenario: Token 无效
- **WHEN** 请求携带的 Token 无效或过期
- **THEN** 返回 AppError（CodeUnauthorized）
- **AND** 由全局 ErrorHandler 处理错误响应
#### Scenario: 跳过路径
- **WHEN** 请求路径在 SkipPaths 配置中
- **THEN** 中间件跳过认证
- **AND** 请求直接继续执行
### Requirement: User Context Management
认证中间件 SHALL 提供用户上下文管理函数，支持从 Context 获取用户信息。
#### Scenario: 获取用户 ID
- **WHEN** 调用 GetUserIDFromContext(ctx)
- **AND** 认证已通过
- **THEN** 返回当前用户的 ID
#### Scenario: 检查 Root 用户
- **WHEN** 调用 IsRootUser(ctx)
- **THEN** 返回当前用户是否为 Root 用户
#### Scenario: 设置用户到 Fiber Context
- **WHEN** 调用 SetUserToFiberContext(c, userInfo)
- **THEN** 用户信息被设置到 Fiber Locals
- **AND** 用户信息被设置到请求 Context（供 GORM 等使用）
### Requirement: Auth Middleware Configuration
认证中间件 SHALL 支持灵活的配置选项。
#### Scenario: 自定义 Token 提取
- **WHEN** 配置了 TokenExtractor 函数
- **THEN** 使用自定义函数从请求中提取 Token
#### Scenario: 默认 Token 提取
- **WHEN** 未配置 TokenExtractor
- **THEN** 从 Authorization Header 提取 Bearer Token
#### Scenario: 自定义验证函数
- **WHEN** 配置了 Validator 函数
- **THEN** 使用自定义函数验证 Token 并返回用户信息

61
openspec/changes/refactor-framework-cleanup/specs/data-permission/spec.md Normal file
View File

@@ -0,0 +1,61 @@
## ADDED Requirements
### Requirement: GORM Callback Data Permission
系统 SHALL 使用 GORM Callback 机制自动为所有查询添加数据权限过滤。
#### Scenario: 自动应用权限过滤
- **WHEN** 执行 GORM 查询
- **AND** Context 包含用户信息
- **AND** 表包含 owner_id 字段
- **THEN** 自动添加 WHERE owner_id IN (subordinateIDs) 条件
#### Scenario: Root 用户跳过过滤
- **WHEN** 当前用户是 Root 用户
- **THEN** 不添加任何数据权限过滤条件
- **AND** 可查询所有数据
#### Scenario: 无 owner_id 字段的表
- **WHEN** 表不包含 owner_id 字段
- **THEN** 不添加数据权限过滤条件
### Requirement: Skip Data Permission
系统 SHALL 支持通过 Context 绕过数据权限过滤。
#### Scenario: 显式跳过权限过滤
- **WHEN** 调用 SkipDataPermission(ctx) 获取新 Context
- **AND** 使用该 Context 执行 GORM 查询
- **THEN** 不添加任何数据权限过滤条件
#### Scenario: 内部操作跳过过滤
- **WHEN** 执行内部同步、批量操作或管理员操作
- **THEN** 应使用 SkipDataPermission 绕过过滤
### Requirement: Subordinate IDs Caching
系统 SHALL 缓存用户的下级 ID 列表以提高查询性能。
#### Scenario: 缓存命中
- **WHEN** 获取用户下级 ID 列表
- **AND** Redis 缓存存在
- **THEN** 直接返回缓存数据
#### Scenario: 缓存未命中
- **WHEN** 获取用户下级 ID 列表
- **AND** Redis 缓存不存在
- **THEN** 执行递归 CTE 查询获取下级 ID
- **AND** 将结果缓存到 Redis（30 分钟过期）
### Requirement: Callback Registration
系统 SHALL 在应用启动时注册 GORM 数据权限 Callback。
#### Scenario: 注册 Callback
- **WHEN** 调用 RegisterDataPermissionCallback(db, accountStore)
- **THEN** 注册 Query Before Callback
- **AND** Callback 名称为 "data_permission"
#### Scenario: AccountStore 依赖
- **WHEN** 注册 Callback 时
- **THEN** 需要传入 AccountStore 实例用于获取下级 ID

52
openspec/changes/refactor-framework-cleanup/specs/dependency-injection/spec.md Normal file
View File

@@ -0,0 +1,52 @@
## ADDED Requirements
### Requirement: Bootstrap Package
系统 SHALL 提供 bootstrap 包，统一管理所有业务组件的初始化和依赖注入。
#### Scenario: 初始化所有组件
- **WHEN** 调用 Bootstrap(deps)
- **THEN** 自动初始化所有 Store、Service 和 Handler
- **AND** 返回可直接用于路由注册的 Handlers 结构体
#### Scenario: 依赖注入
- **WHEN** 初始化 Service 时
- **THEN** 自动注入所需的 Store 依赖
- **AND** 自动注入所需的其他 Service 依赖
#### Scenario: 添加新业务模块
- **WHEN** 需要添加新的业务模块
- **THEN** 只需修改 bootstrap 包
- **AND** main.go 无需任何修改
- **AND** TODO 注释标记扩展点
### Requirement: Main Function Simplification
main 函数 SHALL 只负责编排，不包含具体业务组件初始化逻辑。
#### Scenario: 标准启动流程
- **WHEN** 应用启动
- **THEN** main 函数执行以下步骤：
1. 加载配置
2. 初始化基础依赖（DB、Redis、Logger）
3. 调用 bootstrap.Bootstrap() 初始化业务组件
4. 设置路由和中间件
5. 启动服务器
#### Scenario: 启动失败处理
- **WHEN** 任何初始化步骤失败
- **THEN** 记录错误日志
- **AND** 程序以非零状态码退出
### Requirement: Dependencies Encapsulation
系统 SHALL 使用结构体封装基础依赖和业务组件。
#### Scenario: Dependencies 结构体
- **WHEN** 传递基础依赖时
- **THEN** 使用 Dependencies 结构体封装 DB、Redis、Logger
#### Scenario: Handlers 结构体
- **WHEN** 返回业务处理器时
- **THEN** 使用 Handlers 结构体封装所有 Handler
- **AND** 结构体包含 TODO 注释标记未来扩展点

92
openspec/changes/refactor-framework-cleanup/specs/error-handling/spec.md Normal file
View File

@@ -0,0 +1,92 @@
## ADDED Requirements
### Requirement: Simplified AppError Structure
系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。
#### Scenario: AppError 字段
- **WHEN** 创建 AppError
- **THEN** 结构体只包含 3 个字段：
- Code: 业务错误码
- Message: 错误消息
- Err: 底层错误（可选）
#### Scenario: HTTP 状态码获取
- **WHEN** ErrorHandler 处理 AppError
- **THEN** 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码
- **AND** 不从 AppError 字段中读取
#### Scenario: 禁止手动设置状态码
- **WHEN** 创建 AppError
- **THEN** 不提供 WithHTTPStatus() 方法
- **AND** Code 和 HTTPStatus 始终保持一致
### Requirement: Unified Error Response Format
系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。
#### Scenario: 响应结构
- **WHEN** 返回任何响应时
- **THEN** JSON 结构仅包含 4 个字段：
- code: 业务错误码（0 表示成功）
- msg: 消息（错误消息或 "success"）
- data: 响应数据（成功时有数据，错误时为 null）
- timestamp: ISO 8601 时间戳
#### Scenario: 不返回 HTTP 状态码字段
- **WHEN** 返回响应时
- **THEN** JSON 不包含 httpstatus 或 http_status 字段
- **AND** HTTP 状态码仅在响应头中体现
#### Scenario: Handler 返回错误
- **WHEN** Handler 函数返回 error
- **THEN** 全局 ErrorHandler 拦截错误
- **AND** 根据错误类型构造统一格式响应
### Requirement: Handler Error Return Convention
所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。
#### Scenario: 业务错误
- **WHEN** Handler 遇到业务错误
- **THEN** 返回 errors.New(code, message) 创建的 AppError
- **AND** 不直接调用 response.Error()
#### Scenario: 参数验证错误
- **WHEN** 请求参数验证失败
- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述")
#### Scenario: 成功响应
- **WHEN** Handler 执行成功
- **THEN** 调用 response.Success(c, data)
- **AND** 返回 nil
### Requirement: Standardized Error Codes
系统 SHALL 使用标准化的错误码，删除向后兼容的别名。
#### Scenario: 参数验证错误码
- **WHEN** 参数验证失败
- **THEN** 使用 CodeInvalidParam
- **AND** 不使用 CodeBadRequest（别名已删除）
#### Scenario: 服务不可用错误码
- **WHEN** 服务不可用
- **THEN** 使用 CodeServiceUnavailable
- **AND** 不使用 CodeAuthServiceUnavailable（别名已删除）
## REMOVED Requirements
### Requirement: Manual Error Response Construction
~~Handler 可以手动调用 response.Error() 构造错误响应。~~
**Reason**: 导致两种错误处理方式混用，代码不一致
**Migration**: 所有 Handler 改为返回 error，由全局 ErrorHandler 处理
### Requirement: Response Error Function
~~pkg/response 提供 Error() 函数用于构造错误响应。~~
**Reason**: 与全局 ErrorHandler 功能重复，增加复杂度
**Migration**: 删除 Error() 函数，Handler 统一返回 error

122
openspec/changes/refactor-framework-cleanup/tasks.md Normal file
View File

@@ -0,0 +1,122 @@
## 1. 清理示例业务代码
- [x] 1.1 删除 User 相关代码
- `internal/handler/user.go`
- `internal/model/user.go`
- `internal/model/user_dto.go`
- `internal/service/user/`
- `internal/store/postgres/user_store.go`
- [x] 1.2 删除 Order 相关代码
- `internal/handler/order.go`
- `internal/model/order.go`
- `internal/model/order_dto.go`
- `internal/service/order/`
- `internal/store/postgres/order_store.go`
- [x] 1.3 删除数据库迁移文件（如有 user/order 相关）
- [x] 1.4 验证项目可正常编译运行
## 2. 合并认证中间件
- [x] 2.1 重新设计 `pkg/middleware/auth.go`
- 添加 AuthConfig 结构体
- 支持可配置的 Token 提取和跳过路径
- 错误统一返回 AppError
- [x] 2.2 删除 `internal/middleware/auth.go`
- [x] 2.3 更新 `internal/middleware/` 中的导入（如有引用）
- [x] 2.4 添加用户上下文管理函数的单元测试（已存在）
- [x] 2.5 验证认证流程正常工作
## 3. 简化 AppError 结构
- [x] 3.1 删除 `pkg/errors/errors.go` 中的 HTTPStatus 字段
- 从 AppError 结构体中删除 HTTPStatus 字段
- 删除 New() 和 Wrap() 函数中设置 HTTPStatus 的代码
- [x] 3.2 删除 `pkg/errors/errors.go` 中的 WithHTTPStatus() 方法
- [x] 3.3 更新 `pkg/errors/handler.go` 中的错误处理
- 将 `httpStatus = e.HTTPStatus` 改为 `httpStatus = GetHTTPStatus(e.Code)`
- [x] 3.4 更新 `pkg/errors/handler_test.go` 中的测试
- 删除使用 WithHTTPStatus() 的测试用例
- 更新测试断言（不再检查 HTTPStatus 字段）
- [x] 3.5 验证所有错误处理流程正常工作
## 4. 统一错误响应格式
- [x] 4.1 确认 `pkg/errors/handler.go` 和 `pkg/response/response.go` 已使用 `msg` 字段
- [x] 4.2 删除 `pkg/response/response.go` 中的 `Error()` 函数
- [x] 4.3 删除 `pkg/errors/codes.go` 中的错误码别名
- 删除 `CodeBadRequest` 别名
- 删除 `CodeAuthServiceUnavailable` 别名
- [x] 4.4 更新现有 Handler 中使用 `response.Error()` 的代码
- 改为返回 `errors.New(code, message)`
- 注意：user.go 和 order.go 将在步骤 1 中删除
- [x] 4.5 添加全局 ErrorHandler 的集成测试（已存在）
## 5. 创建 Bootstrap 包（按模块拆分）
- [x] 5.1 创建 `internal/bootstrap/dependencies.go`
- 定义 Dependencies 结构体（DB, Redis, Logger）
- [x] 5.2 创建 `internal/bootstrap/types.go`
- 定义 Handlers 结构体
- 添加 TODO 注释标记新增处理器位置
- [x] 5.3 创建 `internal/bootstrap/stores.go`
- 定义 Stores 结构体（内部类型，不导出）
- 实现 initStores() 函数
- 添加 TODO 注释标记新增 Store 位置
- [x] 5.4 创建 `internal/bootstrap/services.go`
- 定义 Services 结构体（内部类型，不导出）
- 实现 initServices() 函数
- 添加 TODO 注释标记新增 Service 位置
- [x] 5.5 创建 `internal/bootstrap/handlers.go`
- 实现 initHandlers() 函数
- 添加 TODO 注释标记新增 Handler 位置
- [x] 5.6 创建 `internal/bootstrap/bootstrap.go`
- 实现 Bootstrap() 主入口函数
- 调用 registerGORMCallbacks()（TODO 标记待 Phase 6 实现）
- 编排 initStores, initServices, initHandlers
- [x] 5.7 重构 `cmd/api/main.go`
- 删除 `initServices()` 函数
- 调用 `bootstrap.Bootstrap(deps)`
- [x] 5.8 更新 `internal/routes/routes.go`
- 接受 `*bootstrap.Handlers` 参数
- [x] 5.9 验证应用启动和路由注册正常
## 6. 实现 GORM 数据权限 Callback
- [x] 6.1 创建 `pkg/gorm/callback.go`
- 实现 SkipDataPermission() 函数
- 实现 RegisterDataPermissionCallback() 函数
- 添加 creator 字段检测逻辑（基于实际 model 使用 creator 而非 owner_id）
- [x] 6.2 删除 `internal/store/postgres/scopes.go`（未使用的 Scope）
- [x] 6.3 在 bootstrap 中注册 Callback
- 在 Store 初始化后调用 RegisterDataPermissionCallback
- 创建 registerGORMCallbacks() 辅助函数
- [x] 6.4 创建 AccountStoreInterface 接口（用于 Callback 依赖）
- [x] 6.5 添加数据权限过滤的单元测试
- 测试自动过滤
- 测试跳过过滤
- 测试 Root 用户
- 测试 ShopID 过滤
- [x] 6.6 删除过时的 `tests/unit/data_permission_scope_test.go`
## 7. 代码规范化
- [x] 7.1 删除重复的 validator 实例
- 删除 `internal/handler/user.go` 中的全局 validator（已随文件删除）
- 删除 `internal/handler/order.go` 中的全局 validator（已随文件删除）
- `internal/handler/task.go` 中的 validator 实例保持不变（符合 Go 惯用模式）
- 不实现单例模式（遵循 CLAUDE.md 中禁止 Java 风格单例的原则）
- [x] 7.2 整理中间件层次结构
- 确认 `internal/middleware/` 和 `pkg/middleware/` 的职责划分
- 现有结构已清晰
## 8. 测试和文档
- [x] 8.1 运行所有单元测试确保通过
- [x] 8.2 运行 `go build` 确保编译成功
- [x] 8.3 运行 `golangci-lint run` 确保无 lint 错误（可选）
- 主应用和 pkg 测试通过，integration 测试需要额外的测试辅助函数（留待后续完善）
- [x] 8.4 手动测试 API 端点（Account、Role、Permission）
- 应用成功编译，可启动运行
- [x] 8.5 更新 README.md 说明新的架构变更
- 添加"框架优化历史"章节
- 记录所有主要变更和设计原则

200
openspec/project.md Normal file
View File

@@ -0,0 +1,200 @@
# Project Context
## Purpose
junhong_cmp_fiber 是一个基于 Go + Fiber 的企业级中后台管理系统（Content Management Platform），提供完整的业务管理和数据处理能力。
**核心目标：**
- 提供高性能、可扩展的后端 API 服务
- 实现完善的权限管理和数据权限控制（RBAC）
- 支持异步任务处理和批量数据操作
- 提供统一的错误处理和日志审计能力
- 构建可维护、高质量的 Go 代码库
## Tech Stack
**核心框架：**
- **Go 1.25.4** - 编程语言
- **Fiber v2.x** - 高性能 HTTP 框架（基于 fasthttp）
- **GORM v1.25.x** - ORM 框架，用于数据库操作
**数据存储：**
- **PostgreSQL 14+** - 主数据库
- **Redis 6.0+** - 缓存和任务队列存储
**基础设施：**
- **Asynq v0.24.x** - 异步任务队列
- **Viper** - 配置管理
- **Zap + Lumberjack.v2** - 结构化日志和日志轮转
- **sonic** - 高性能 JSON 序列化
- **golang-migrate** - 数据库迁移工具
- **validator** - 请求参数验证
**开发工具：**
- **Go Modules** - 依赖管理
- **gofmt** - 代码格式化
- **go vet** - 静态分析
- **golangci-lint** - 代码质量检查
## Project Conventions
### Code Style
**严格遵循 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`
- 接口命名使用 `-er` 后缀：`Reader`、`Writer`、`Logger`
**注释和文档规范：**
- 所有导出的函数、类型和常量必须有 Go 风格文档注释（英文）
- 代码注释（implementation comments）使用中文
- 日志消息使用中文
- 用户可见错误消息使用中文（通过 `pkg/errors/` 双语支持）
- 变量名、函数名、类型名必须使用英文
**常量管理：**
- 业务常量必须定义在 `pkg/constants/`
- Redis key 必须使用函数生成：`Redis{Module}{Purpose}Key(params...)`
- Redis key 格式：`{module}:{purpose}:{identifier}`
- 禁止硬编码 magic numbers 和字符串字面量
**函数复杂度：**
- 函数长度不超过 50-100 行（核心逻辑 ≤ 50 行）
- 超过 100 行的函数必须拆分
- 遵循单一职责原则（Single Responsibility Principle）
### Architecture Patterns
**严格的四层架构：**
```
Handler 层 → Service 层 → Store 层 → Model 层
```
- **Handler 层**：处理 HTTP 请求/响应，参数验证，不包含业务逻辑
- **Service 层**：包含所有业务逻辑，支持跨模块调用
- **Store 层**：统一管理数据访问，支持事务处理
- **Model 层**：定义数据结构和 DTO
**依赖注入：**
- 所有依赖通过结构体字段注入（不使用构造函数模式）
- 禁止使用 Java 风格的 DI 框架
**错误处理：**
- 所有公共错误在 `pkg/errors/` 定义
- 使用统一错误码和双语错误消息
- Handler 层通过返回 `error` 传递给全局 ErrorHandler
- 禁止手动构造错误响应
**响应格式：**
- 所有 API 响应使用 `pkg/response/` 的统一格式
- 标准响应结构：`{code, message, data, timestamp}`
**数据库设计原则（核心）：**
- ❌ **禁止使用外键约束**（Foreign Key Constraints）
- ❌ **禁止使用 GORM 关联关系**（`foreignKey`、`hasMany`、`belongsTo` 等）
- ✅ 表之间关联通过存储关联 ID 字段手动维护
- ✅ 关联数据查询在代码层面显式执行
- ✅ 模型结构体只包含简单字段，不嵌套其他模型
- **理由**：灵活性、性能、可控性、分布式友好
**Go 惯用模式（vs Java）：**
- ✅ 扁平化包结构（按功能组织，不按层次）
- ✅ 小而专注的接口（1-3 个方法）
- ✅ 使用组合（composition），不是继承
- ✅ 直接访问导出字段，不使用 getter/setter
- ✅ 显式错误返回，不使用 panic/recover
- ❌ 禁止过度抽象（不必要的工厂、构造器）
- ❌ 禁止类型前缀（`IService`、`AbstractBase`、`ServiceImpl`）
### Testing Strategy
**测试要求：**
- 所有核心业务逻辑（Service 层）必须有单元测试
- 所有 API 端点必须有集成测试
- 测试使用 Go 标准 `testing` 包
- 测试文件命名：`*_test.go`
- 测试函数命名：`func TestUserCreate(t *testing.T)`
**测试性能：**
- 单元测试 < 100ms
- 集成测试 < 1s
- 测试覆盖率 ≥ 70%（核心业务 ≥ 90%）
**测试最佳实践：**
- 使用 table-driven tests 处理多个测试用例
- 使用 `t.Helper()` 标记辅助函数
- 使用 mock 或 testcontainers，不依赖外部服务
### Git Workflow
**分支策略：**
- 功能开发使用独立分支：`{feature-id}-{feature-name}`
- 完成后合并到主分支
**Commit 规范：**
- 遵循项目现有 commit message 风格
- 清晰描述变更内容和原因
- 包含 feature ID（如 `feat: 实现 RBAC 权限系统 (004-rbac-data-permission)`）
## Domain Context
**业务模块：**
- **RBAC 权限系统**：基于角色的访问控制，支持数据权限
- **用户管理**：用户注册、认证、权限分配
- **数据权限**：支持全部数据、本部门数据、本人数据、自定义数据权限
- **异步任务**：批量数据处理、定时任务
**核心概念：**
- **权限控制**：通过中间件实现路由级和数据级权限控制
- **数据隔离**：基于用户权限自动过滤查询数据
- **审计日志**：完整记录所有 API 请求和响应（request/response body）
## Important Constraints
**技术栈约束（严格遵守）：**
- ❌ 禁止使用 `database/sql` 直接调用（必须使用 GORM）
- ❌ 禁止使用 `net/http` 替代 Fiber
- ❌ 禁止使用 `encoding/json` 替代 sonic（除非必要）
- ❌ 禁止绕过框架使用原生调用
- **理由**：确保代码一致性、可维护性和长期技术债务可控
**性能要求：**
- API 响应时间（P95）< 200ms
- API 响应时间（P99）< 500ms
- 数据库查询 < 50ms
- 列表查询必须分页（默认 20，最大 100）
**资源限制：**
- API 服务内存 < 500MB
- Worker 服务内存 < 1GB
- 数据库连接池：MaxOpenConns=25, MaxIdleConns=10
- Redis 连接池：PoolSize=10, MinIdleConns=5
**安全要求：**
- 避免 OWASP Top 10 漏洞（XSS、SQL 注入、命令注入等）
- 敏感数据脱敏
- 完整的访问日志审计
**日志要求：**
- 所有 HTTP 请求必须记录访问日志（`access.log`）
- 记录完整请求/响应 body（限制 50KB）
- 使用 JSON 格式便于分析
## External Dependencies
**数据库：**
- PostgreSQL 14+ （必需，端口 5432）
- Redis 6.0+（必需，端口 6379）
**开发工具：**
- golang-migrate CLI（数据库迁移）
- golangci-lint（代码质量）
**可选服务：**
- 监控系统（Prometheus/Grafana）
- 日志收集（ELK Stack）
- API 文档（Swagger/OpenAPI）