# 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 定义文件重构 - [x] **1.1** 创建前端公共接口定义文件 - [x] 创建 `api/desc/frontend/public.api` - [x] 定义照片展示接口类型 - [x] 定义分类展示接口类型 - [x] 定义精选照片、最新照片接口 - [x] 优化返回数据结构 (去除敏感信息) - [x] **1.2** 创建前端认证接口定义文件 - [x] 创建 `api/desc/frontend/auth.api` - [x] 定义前端用户登录/注册接口 - [x] 定义前端用户信息接口 - [x] 设计轻量级认证流程 - [x] **1.3** 创建管理后台接口定义文件 - [x] 创建 `api/desc/admin.api` 主入口文件 - [x] 创建 `api/desc/admin/auth.api` 管理员认证 - [x] 创建 `api/desc/admin/users.api` 用户管理 - [x] 创建 `api/desc/admin/photos.api` 照片管理 - [x] 创建 `api/desc/admin/categories.api` 分类管理 - [x] 创建 `api/desc/admin/dashboard.api` 仪表板统计 - [x] **1.4** 更新公共类型定义 - [x] 扩展 `common.api` 添加管理后台专用类型 - [x] 添加前端展示专用类型 - [x] 定义双重认证相关类型 - [x] 添加权限控制相关类型 #### 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