# 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      # 获取操作日志
```

## 🔒 权限管理设计

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

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

## 🛡️ 认证系统设计

### 双重认证体系
1. **前端认证**: 基于普通用户的轻量级认证
2. **管理员认证**: 基于管理员的强认证

### JWT Token 隔离
```yaml
前端 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       # 仪表板
```

## 🎯 优势与收益

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

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

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

---

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