8a0792500e
Some checks failed
部署管理后台 / 🧪 测试和构建 (push) Failing after 1m5s
部署管理后台 / 🔒 安全扫描 (push) Has been skipped
部署前端网站 / 🧪 测试和构建 (push) Failing after 2m0s
部署管理后台 / 🚀 部署到生产环境 (push) Has been skipped
部署后端服务 / 🚀 构建并部署 (push) Has been skipped
部署后端服务 / 🧪 测试后端 (push) Failing after 3m15s
部署前端网站 / 🚀 部署到生产环境 (push) Has been skipped
部署管理后台 / 🔄 回滚部署 (push) Has been skipped
部署后端服务 / 🔄 回滚部署 (push) Has been skipped
🚀 主要功能: - 创建前端公共展示API (/api/v1/public/*) - 创建前端用户认证API (/api/v1/auth/*) - 创建管理后台完整API (/admin/*) - 实现双重认证体系设计 📋 新增文件: - api/desc/frontend/public.api - 前端公共接口定义 - api/desc/frontend/auth.api - 前端认证接口定义 - 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 - 仪表板统计接口 🔧 更新文件: - api/desc/common.api - 扩展类型定义支持前端和管理后台 - api/desc/photography.api - 更新为前端主入口 - etc/photographyapi-api.yaml - 修复中间件配置 📚 文档: - docs/API_SEPARATION_DESIGN.md - 接口隔离设计方案 - docs/API_REFACTORING_TASKS.md - 详细任务规划 - docs/COMPLETED_TASKS_ARCHIVE.md - 已完成任务归档 ✨ 特性亮点: - 前端和管理后台权限完全隔离 - 优化的数据结构去除敏感信息 - 完整的CRUD和统计功能 - 支持批量操作和高级筛选 - 详细的仪表板分析功能
223 lines
6.4 KiB
Markdown
223 lines
6.4 KiB
Markdown
# 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 # 仪表板
|
|
```
|
|
|
|
## 🎯 优势与收益
|
|
|
|
### 安全性提升
|
|
- **权限隔离**: 前端和管理后台权限完全分离
|
|
- **认证强化**: 管理员采用更强的认证机制
|
|
- **接口隔离**: 降低安全风险
|
|
|
|
### 性能优化
|
|
- **缓存策略**: 前端接口支持高效缓存
|
|
- **数据精简**: 前端只返回必要数据
|
|
- **负载均衡**: 可以独立扩展不同服务
|
|
|
|
### 开发效率
|
|
- **职责清晰**: 前端和后台开发团队分工明确
|
|
- **版本控制**: 可以独立版本管理
|
|
- **部署灵活**: 支持独立部署和扩展
|
|
|
|
---
|
|
|
|
**请确认此设计方案是否符合您的需求，我将根据您的反馈进行调整和实施。** |