junhong_cmp_fiber/openspec/changes/refactor-framework-cleanup/proposal.md

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

• 这是框架搭建阶段，无生产数据需要迁移
• 示例代码删除不影响任何现有功能