photography/backend/docs/API_SEPARATION_DESIGN.md

API 接口隔离设计方案

📋 概述

为了实现管理后台和前端页面的权限隔离，将 API 接口按照使用场景进行分离设计。两套接口体系拥有独立的认证系统和权限管理。

🏗️ 整体架构

/api/v1/                    # 前端页面 API (公共展示)
├── public/                 # 公共接口 (无需认证)
│   ├── photos              # 照片展示接口
│   ├── categories          # 分类展示接口
│   └── health              # 健康检查
└── auth/                   # 前端认证 (用户登录/注册)
    ├── login
    └── register

/admin/                     # 管理后台 API (管理功能)
├── auth/                   # 管理员认证
│   ├── login
│   └── refresh
├── users/                  # 用户管理
├── photos/                 # 照片管理
├── categories/             # 分类管理
└── dashboard/              # 仪表板统计

🎨 前端页面 API 设计

特点

• 无需认证：主要用于展示，提供公共访问
• 只读操作：只提供数据查询，不涉及修改
• 高性能：支持缓存，优化加载速度
• SEO友好：支持静态生成所需的数据

接口列表

🏥 健康检查

GET /api/v1/health

📸 照片接口

GET /api/v1/public/photos           # 获取照片列表 (支持分页、筛选)
GET /api/v1/public/photos/:id       # 获取照片详情
GET /api/v1/public/photos/featured  # 获取精选照片
GET /api/v1/public/photos/recent    # 获取最新照片

🏷️ 分类接口

GET /api/v1/public/categories       # 获取分类列表
GET /api/v1/public/categories/:id   # 获取分类详情
GET /api/v1/public/categories/:id/photos  # 获取分类下的照片

🔐 用户认证 (前端用户)

POST /api/v1/auth/login            # 前端用户登录
POST /api/v1/auth/register         # 前端用户注册
POST /api/v1/auth/logout           # 前端用户登出
GET  /api/v1/auth/profile          # 获取用户信息 (需要认证)

🔧 管理后台 API 设计

特点

• 强认证：所有接口都需要管理员权限
• 完整CRUD：支持创建、读取、更新、删除操作
• 权限控制：基于角色的访问控制
• 审计日志：记录所有管理操作

接口列表

🔐 管理员认证

POST /admin/auth/login      # 管理员登录
POST /admin/auth/refresh    # 刷新管理员Token
POST /admin/auth/logout     # 管理员登出
GET  /admin/auth/profile    # 获取管理员信息

👥 用户管理

GET    /admin/users         # 获取用户列表
POST   /admin/users         # 创建用户
GET    /admin/users/:id     # 获取用户详情
PUT    /admin/users/:id     # 更新用户
DELETE /admin/users/:id     # 删除用户
POST   /admin/users/:id/avatar  # 上传用户头像
PUT    /admin/users/:id/status  # 更新用户状态

📸 照片管理

GET    /admin/photos        # 获取照片列表 (管理视图)
POST   /admin/photos        # 上传照片
GET    /admin/photos/:id    # 获取照片详情
PUT    /admin/photos/:id    # 更新照片
DELETE /admin/photos/:id    # 删除照片
PUT    /admin/photos/:id/featured  # 设置精选
POST   /admin/photos/batch  # 批量操作

🏷️ 分类管理

GET    /admin/categories    # 获取分类列表
POST   /admin/categories    # 创建分类
GET    /admin/categories/:id  # 获取分类详情
PUT    /admin/categories/:id  # 更新分类
DELETE /admin/categories/:id  # 删除分类
PUT    /admin/categories/sort # 分类排序

📊 仪表板统计

GET /admin/dashboard/stats     # 获取统计数据
GET /admin/dashboard/analytics # 获取分析数据
GET /admin/dashboard/logs      # 获取操作日志

🔒 权限管理设计

前端用户权限

前端用户 (Frontend User):
  - 权限范围: 只读访问公共内容
  - 认证方式: 可选 JWT (用于个人偏好设置)
  - 访问接口: /api/v1/public/*, /api/v1/auth/*
  - 特殊权限: 无

管理员权限

管理员 (Admin):
  - 权限范围: 完整的后台管理权限
  - 认证方式: 强制 JWT + 双重认证
  - 访问接口: /admin/*
  - 特殊权限: 
    - 用户管理
    - 内容管理
    - 系统配置
    - 数据统计

🛡️ 认证系统设计

双重认证体系

1. 前端认证: 基于普通用户的轻量级认证
2. 管理员认证: 基于管理员的强认证

JWT Token 隔离

前端 Token:
  - 前缀: "Bearer "
  - 有效期: 7天
  - 权限: 基础用户权限
  - 存储: localStorage

管理员 Token:
  - 前缀: "Admin "
  - 有效期: 2小时
  - 权限: 管理员权限
  - 存储: httpOnly Cookie + localStorage

🚀 实施方案

第一阶段: 接口分离

1. 创建新的 API 定义文件
2. 重构现有接口结构
3. 添加路由前缀区分

第二阶段: 认证系统

1. 实现双重认证中间件
2. 创建不同的 JWT 策略
3. 添加权限检查机制

第三阶段: 数据隔离

1. 优化前端接口返回数据
2. 增加管理后台特殊字段
3. 实现缓存策略

📁 文件结构调整

api/desc/
├── common.api              # 公共类型定义
├── photography.api         # 前端主入口文件
├── admin.api               # 管理后台主入口文件
├── frontend/               # 前端 API 定义
│   ├── public.api          # 公共展示接口
│   └── auth.api            # 前端认证接口
└── admin/                  # 管理后台 API 定义
    ├── auth.api            # 管理员认证
    ├── users.api           # 用户管理
    ├── photos.api          # 照片管理
    ├── categories.api      # 分类管理
    └── dashboard.api       # 仪表板

🎯 优势与收益

安全性提升

• 权限隔离: 前端和管理后台权限完全分离
• 认证强化: 管理员采用更强的认证机制
• 接口隔离: 降低安全风险

性能优化

• 缓存策略: 前端接口支持高效缓存
• 数据精简: 前端只返回必要数据
• 负载均衡: 可以独立扩展不同服务

开发效率

• 职责清晰: 前端和后台开发团队分工明确
• 版本控制: 可以独立版本管理
• 部署灵活: 支持独立部署和扩展

---

请确认此设计方案是否符合您的需求，我将根据您的反馈进行调整和实施。