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 定义文件重构
- [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