photography/backend/docs/API_REFACTORING_TASKS.md

API 接口改造任务规划

📋 项目概述

本文档详细规划了前端页面和管理后台 API 接口隔离改造的所有任务，确保两套系统拥有独立的认证体系和权限管理。

🎯 改造目标

• 前端API: /api/v1/public/* + /api/v1/auth/* (公共展示 + 轻量认证)
• 管理后台API: /admin/* (完整管理功能 + 强认证)
• 权限隔离: 两套独立的认证和权限系统
• 性能优化: 前端专注展示，后台专注管理

🏗️ 总体架构

当前架构:
├── /api/v1/users      (混合用途)
├── /api/v1/photos     (混合用途)
├── /api/v1/categories (混合用途)
└── /api/v1/auth       (混合认证)

目标架构:
├── /api/v1/public/    (前端展示)
├── /api/v1/auth/      (前端认证)
└── /admin/            (管理后台)

---

📊 任务分解

🔧 阶段一：后端 API 改造 (Backend)

1. API 定义文件重构

• 1.1 创建前端公共接口定义文件

  • 创建 api/desc/frontend/public.api
  • 定义照片展示接口类型
  • 定义分类展示接口类型
  • 定义精选照片、最新照片接口
  • 优化返回数据结构 (去除敏感信息)

• 1.2 创建前端认证接口定义文件

  • 创建 api/desc/frontend/auth.api
  • 定义前端用户登录/注册接口
  • 定义前端用户信息接口
  • 设计轻量级认证流程

• 1.3 创建管理后台接口定义文件

  • 创建 api/desc/admin.api 主入口文件
  • 创建 api/desc/admin/auth.api 管理员认证
  • 创建 api/desc/admin/users.api 用户管理
  • 创建 api/desc/admin/photos.api 照片管理
  • 创建 api/desc/admin/categories.api 分类管理
  • 创建 api/desc/admin/dashboard.api 仪表板统计

• 1.4 更新公共类型定义

  • 扩展 common.api 添加管理后台专用类型
  • 添加前端展示专用类型
  • 定义双重认证相关类型
  • 添加权限控制相关类型

2. 路由和处理器重构

• 2.1 创建前端公共接口处理器

  • 创建 internal/handler/frontend/ 目录
  • 实现公共照片列表处理器
  • 实现公共分类列表处理器
  • 实现精选照片处理器
  • 实现最新照片处理器
  • 优化查询性能和缓存

• 2.2 创建管理后台接口处理器

  • 创建 internal/handler/admin/ 目录
  • 实现管理员认证处理器
  • 实现用户管理处理器
  • 实现照片管理处理器
  • 实现分类管理处理器
  • 实现仪表板统计处理器

• 2.3 更新路由配置

  • 更新 internal/handler/routes.go
  • 配置前端公共路由组
  • 配置管理后台路由组
  • 设置不同的路由前缀
  • 配置中间件应用策略

3. 业务逻辑层重构

• 3.1 创建前端业务逻辑

  • 创建 internal/logic/frontend/ 目录
  • 实现公共照片查询逻辑
  • 实现公共分类查询逻辑
  • 实现前端认证逻辑
  • 优化查询性能和数据过滤

• 3.2 创建管理后台业务逻辑

  • 创建 internal/logic/admin/ 目录
  • 实现管理员认证逻辑
  • 实现用户管理逻辑
  • 实现照片管理逻辑
  • 实现分类管理逻辑
  • 实现仪表板统计逻辑

• 3.3 权限控制逻辑

  • 实现双重认证中间件
  • 实现管理员权限验证
  • 实现前端用户权限验证
  • 添加审计日志功能

4. 数据层优化

• 4.1 优化数据模型

  • 为前端查询添加索引优化
  • 为管理后台查询添加索引优化
  • 优化分页查询性能
  • 添加缓存支持

• 4.2 数据访问层隔离

  • 创建前端专用数据访问方法
  • 创建管理后台专用数据访问方法
  • 实现数据过滤和权限控制
  • 优化查询效率

5. 认证系统重构

• 5.1 实现双重认证系统

  • 重构 JWT 生成和验证
  • 实现前端轻量级认证
  • 实现管理员强认证
  • 配置不同的 Token 策略

• 5.2 中间件系统升级

  • 更新认证中间件
  • 实现权限控制中间件
  • 添加访问日志中间件
  • 优化 CORS 配置

6. 配置和部署

• 6.1 更新配置文件

  • 更新 etc/photographyapi-api.yaml
  • 配置双重认证参数
  • 配置缓存策略
  • 配置日志级别

• 6.2 代码生成和构建

  • 使用 goctl 重新生成代码
  • 更新 Makefile 构建脚本
  • 修复编译错误
  • 运行单元测试

---

🎨 阶段二：前端页面 API 对接 (Frontend)

1. API 客户端重构

• 1.1 创建前端 API 客户端

  • 创建 frontend/lib/api/public.ts
  • 实现照片展示 API 调用
  • 实现分类展示 API 调用
  • 实现精选照片 API 调用
  • 实现最新照片 API 调用

• 1.2 更新认证客户端

  • 更新 frontend/lib/api/auth.ts
  • 适配新的认证接口
  • 实现前端用户登录
  • 实现前端用户注册
  • 更新 Token 处理逻辑

2. 页面组件更新

• 2.1 更新照片展示组件

  • 更新照片列表组件
  • 更新照片详情组件
  • 更新照片网格组件
  • 适配新的数据结构

• 2.2 更新分类展示组件

  • 更新分类列表组件
  • 更新分类筛选组件
  • 适配新的数据结构

• 2.3 更新认证相关组件

  • 更新登录表单组件
  • 更新注册表单组件
  • 更新用户信息组件
  • 适配新的认证流程

3. 状态管理更新

• 3.1 更新数据状态管理

  • 更新照片数据状态
  • 更新分类数据状态
  • 更新认证状态
  • 优化缓存策略

• 3.2 更新 API 错误处理

  • 实现统一错误处理
  • 更新错误提示组件
  • 添加重试机制
  • 优化用户体验

4. 性能优化

• 4.1 实现数据预取

  • 实现照片数据预取
  • 实现分类数据预取
  • 优化首屏加载速度

• 4.2 实现缓存策略

  • 实现客户端缓存
  • 实现增量更新
  • 优化网络请求

---

🔧 阶段三：管理后台 API 对接 (Admin)

1. API 客户端重构

• 1.1 创建管理后台 API 客户端

  • 创建 admin/src/api/admin.ts
  • 实现管理员认证 API
  • 实现用户管理 API
  • 实现照片管理 API
  • 实现分类管理 API
  • 实现仪表板统计 API

• 1.2 实现强认证客户端

  • 创建 admin/src/api/auth.ts
  • 实现管理员登录
  • 实现 Token 刷新
  • 实现权限验证
  • 添加双重认证支持

2. 管理界面组件

• 2.1 用户管理界面

  • 更新用户列表组件
  • 更新用户编辑组件
  • 更新用户创建组件
  • 实现用户状态管理
  • 实现头像上传功能

• 2.2 照片管理界面

  • 更新照片列表组件
  • 更新照片编辑组件
  • 更新照片上传组件
  • 实现批量操作功能
  • 实现精选照片设置

• 2.3 分类管理界面

  • 更新分类列表组件
  • 更新分类编辑组件
  • 更新分类创建组件
  • 实现分类排序功能

• 2.4 仪表板界面

  • 创建统计数据组件
  • 创建分析图表组件
  • 创建操作日志组件
  • 实现实时数据更新

3. 权限控制系统

• 3.1 实现页面权限控制

  • 实现路由权限守卫
  • 实现组件权限控制
  • 实现功能权限验证
  • 添加权限提示界面

• 3.2 实现操作权限控制

  • 实现操作按钮权限控制
  • 实现 API 调用权限验证
  • 实现数据访问权限控制
  • 添加权限异常处理

4. 数据管理优化

• 4.1 实现数据表格优化

  • 实现高性能数据表格
  • 实现虚拟滚动
  • 实现数据筛选和排序
  • 优化大数据量展示

• 4.2 实现表单优化

  • 实现表单验证
  • 实现表单数据缓存
  • 实现表单提交优化
  • 添加表单错误处理

---

🧪 测试和验证

1. 后端测试

• 1.1 单元测试

  • 测试前端公共接口
  • 测试管理后台接口
  • 测试认证系统
  • 测试权限控制

• 1.2 集成测试

  • 测试 API 接口集成
  • 测试数据库集成
  • 测试认证集成
  • 测试权限集成

2. 前端测试

• 2.1 组件测试

  • 测试前端页面组件
  • 测试管理后台组件
  • 测试认证组件
  • 测试权限组件

• 2.2 端到端测试

  • 测试完整用户流程
  • 测试管理后台流程
  • 测试认证流程
  • 测试权限流程

3. 性能测试

• 3.1 API 性能测试

  • 测试接口响应时间
  • 测试并发处理能力
  • 测试缓存效果
  • 测试数据库性能

• 3.2 前端性能测试

  • 测试页面加载速度
  • 测试组件渲染性能
  • 测试数据更新性能
  • 测试用户交互响应

---

📋 里程碑和时间规划

🎯 里程碑 1: 后端 API 定义完成 ✅

完成时间: 2025-07-11

• ✅ API 定义文件重构 (已完成)
• ⏳ 路由和处理器重构 (下一步)
• ⏳ 业务逻辑层重构 (下一步)
• ⏳ 认证系统重构 (下一步)

🎯 里程碑 2: 前端页面适配完成

预计时间: 2-3 天

• ✅ API 客户端重构
• ✅ 页面组件更新
• ✅ 状态管理更新
• ✅ 性能优化

🎯 里程碑 3: 管理后台适配完成

预计时间: 3-4 天

• ✅ API 客户端重构
• ✅ 管理界面组件
• ✅ 权限控制系统
• ✅ 数据管理优化

🎯 里程碑 4: 测试和上线

预计时间: 2-3 天

• ✅ 全面测试
• ✅ 性能优化
• ✅ 部署上线
• ✅ 监控和维护

---

🔥 优先级说明

🚨 高优先级 (P0)

• 后端 API 定义文件重构
• 认证系统重构
• 路由和处理器重构

⚡ 中优先级 (P1)

• 前端页面 API 对接
• 管理后台 API 对接
• 权限控制系统

🔧 低优先级 (P2)

• 性能优化
• 缓存策略
• 监控和日志

---

📞 风险控制

🚨 潜在风险

1. 数据兼容性: 新旧 API 数据结构变化
2. 认证迁移: 用户认证状态迁移
3. 性能影响: 重构可能影响系统性能
4. 测试覆盖: 确保所有功能正常

🛡️ 应对措施

1. 灰度发布: 逐步切换到新 API
2. 数据备份: 改造前完整备份
3. 回滚方案: 准备快速回滚机制
4. 全面测试: 确保功能完整性

---

📝 文档更新时间: {当前时间}
📋 文档版本: v1.0
👥 负责人: Development Team