# 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）