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

1. 清理示例业务代码

• 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
• 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
• 1.3 删除数据库迁移文件（如有 user/order 相关）
• 1.4 验证项目可正常编译运行

2. 合并认证中间件

• 2.1 重新设计 pkg/middleware/auth.go
  • 添加 AuthConfig 结构体
  • 支持可配置的 Token 提取和跳过路径
  • 错误统一返回 AppError
• 2.2 删除 internal/middleware/auth.go
• 2.3 更新 internal/middleware/ 中的导入（如有引用）
• 2.4 添加用户上下文管理函数的单元测试（已存在）
• 2.5 验证认证流程正常工作

3. 简化 AppError 结构

• 3.1 删除 pkg/errors/errors.go 中的 HTTPStatus 字段
  • 从 AppError 结构体中删除 HTTPStatus 字段
  • 删除 New() 和 Wrap() 函数中设置 HTTPStatus 的代码
• 3.2 删除 pkg/errors/errors.go 中的 WithHTTPStatus() 方法
• 3.3 更新 pkg/errors/handler.go 中的错误处理
  • 将 httpStatus = e.HTTPStatus 改为 httpStatus = GetHTTPStatus(e.Code)
• 3.4 更新 pkg/errors/handler_test.go 中的测试
  • 删除使用 WithHTTPStatus() 的测试用例
  • 更新测试断言（不再检查 HTTPStatus 字段）
• 3.5 验证所有错误处理流程正常工作

4. 统一错误响应格式

• 4.1 确认 pkg/errors/handler.go 和 pkg/response/response.go 已使用 msg 字段
• 4.2 删除 pkg/response/response.go 中的 Error() 函数
• 4.3 删除 pkg/errors/codes.go 中的错误码别名
  • 删除 CodeBadRequest 别名
  • 删除 CodeAuthServiceUnavailable 别名
• 4.4 更新现有 Handler 中使用 response.Error() 的代码
  • 改为返回 errors.New(code, message)
  • 注意：user.go 和 order.go 将在步骤 1 中删除
• 4.5 添加全局 ErrorHandler 的集成测试（已存在）

5. 创建 Bootstrap 包（按模块拆分）

• 5.1 创建 internal/bootstrap/dependencies.go
  • 定义 Dependencies 结构体（DB, Redis, Logger）
• 5.2 创建 internal/bootstrap/types.go
  • 定义 Handlers 结构体
  • 添加 TODO 注释标记新增处理器位置
• 5.3 创建 internal/bootstrap/stores.go
  • 定义 Stores 结构体（内部类型，不导出）
  • 实现 initStores() 函数
  • 添加 TODO 注释标记新增 Store 位置
• 5.4 创建 internal/bootstrap/services.go
  • 定义 Services 结构体（内部类型，不导出）
  • 实现 initServices() 函数
  • 添加 TODO 注释标记新增 Service 位置
• 5.5 创建 internal/bootstrap/handlers.go
  • 实现 initHandlers() 函数
  • 添加 TODO 注释标记新增 Handler 位置
• 5.6 创建 internal/bootstrap/bootstrap.go
  • 实现 Bootstrap() 主入口函数
  • 调用 registerGORMCallbacks()（TODO 标记待 Phase 6 实现）
  • 编排 initStores, initServices, initHandlers
• 5.7 重构 cmd/api/main.go
  • 删除 initServices() 函数
  • 调用 bootstrap.Bootstrap(deps)
• 5.8 更新 internal/routes/routes.go
  • 接受 *bootstrap.Handlers 参数
• 5.9 验证应用启动和路由注册正常

6. 实现 GORM 数据权限 Callback

• 6.1 创建 pkg/gorm/callback.go
  • 实现 SkipDataPermission() 函数
  • 实现 RegisterDataPermissionCallback() 函数
  • 添加 creator 字段检测逻辑（基于实际 model 使用 creator 而非 owner_id）
• 6.2 删除 internal/store/postgres/scopes.go（未使用的 Scope）
• 6.3 在 bootstrap 中注册 Callback
  • 在 Store 初始化后调用 RegisterDataPermissionCallback
  • 创建 registerGORMCallbacks() 辅助函数
• 6.4 创建 AccountStoreInterface 接口（用于 Callback 依赖）
• 6.5 添加数据权限过滤的单元测试
  • 测试自动过滤
  • 测试跳过过滤
  • 测试 Root 用户
  • 测试 ShopID 过滤
• 6.6 删除过时的 tests/unit/data_permission_scope_test.go

7. 代码规范化

• 7.1 删除重复的 validator 实例
  • 删除 internal/handler/user.go 中的全局 validator（已随文件删除）
  • 删除 internal/handler/order.go 中的全局 validator（已随文件删除）
  • internal/handler/task.go 中的 validator 实例保持不变（符合 Go 惯用模式）
  • 不实现单例模式（遵循 CLAUDE.md 中禁止 Java 风格单例的原则）
• 7.2 整理中间件层次结构
  • 确认 internal/middleware/ 和 pkg/middleware/ 的职责划分
  • 现有结构已清晰

8. 测试和文档

• 8.1 运行所有单元测试确保通过
• 8.2 运行 go build 确保编译成功
• 8.3 运行 golangci-lint run 确保无 lint 错误（可选）
  • 主应用和 pkg 测试通过，integration 测试需要额外的测试辅助函数（留待后续完善）
• 8.4 手动测试 API 端点（Account、Role、Permission）
  • 应用成功编译，可启动运行
• 8.5 更新 README.md 说明新的架构变更
  • 添加"框架优化历史"章节
  • 记录所有主要变更和设计原则