# API路由总览

> **目的：** 提供所有API端点的快速索引，便于查找和避免路由冲突  
> **详细设计：** 请查看各模块的 `02-API设计.md`  
> **基础URL：** `http://localhost:3001/api/v1`  
> **最后更新：** 2025-11-06

---

## 📋 路由命名规范

### 路径格式
```
/api/v{version}/{module}/{resource}/{id?}/{action?}

示例：
/api/v1/literature/projects           # 获取文献项目列表
/api/v1/literature/projects/123       # 获取ID=123的项目
/api/v1/literature/projects/123/export  # 导出项目
```

### 模块名称规范

| 模块代码 | 路由前缀 | 说明 |
|---------|---------|------|
| 平台基础层 | `/auth`, `/users`, `/admin` | 认证、用户、管理 |
| LLM网关 | `/llm` | LLM调用 |
| AIA | `/chat`, `/agents` | AI智能问答 |
| ASL | `/literature` | AI智能文献 |
| PKB | `/knowledge-bases`, `/kb` | 个人知识库 |
| DC | `/data-cleaning` | 数据清洗 |
| SSA | `/analysis` | 智能统计分析 |
| ST | `/tools` | 统计工具 |
| RVW | `/review` | 稿件审查 |
| ADMIN | `/admin` | 运营管理端 |

---

## 🔐 认证与用户管理（/api/v1/auth, /api/v1/users）

**状态：** ✅ 已实现  
**详细设计：** [UAM/02-API设计](../01-平台基础层/01-用户与权限中心(UAM)/02-API设计.md)（待创建）

### 认证相关

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/auth/register` | POST | 用户注册 | ❌ |
| `/api/v1/auth/login` | POST | 用户登录 | ❌ |
| `/api/v1/auth/logout` | POST | 用户登出 | ✅ |
| `/api/v1/auth/refresh` | POST | 刷新Token | ✅ |
| `/api/v1/auth/profile` | GET | 获取当前用户信息 | ✅ |
| `/api/v1/auth/profile` | PUT | 更新当前用户信息 | ✅ |

### 用户管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/users` | GET | 用户列表（分页） | ✅ ADMIN |
| `/api/v1/users/:id` | GET | 用户详情 | ✅ ADMIN |
| `/api/v1/users/:id` | PUT | 更新用户 | ✅ ADMIN |
| `/api/v1/users/:id` | DELETE | 删除用户 | ✅ ADMIN |

---

## 🤖 LLM大模型网关（/api/v1/llm）

**状态：** ❌ 待实现（P0优先级）  
**详细设计：** [LLM网关/02-API设计](../02-通用能力层/01-LLM大模型网关/02-API设计.md)

### LLM调用

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/llm/chat` | POST | LLM对话（非流式） | ✅ |
| `/api/v1/llm/chat/stream` | POST | LLM对话（流式SSE） | ✅ |
| `/api/v1/llm/quota` | GET | 查询当前用户配额 | ✅ |
| `/api/v1/llm/usage` | GET | 查询使用统计 | ✅ |
| `/api/v1/llm/models` | GET | 获取可用模型列表 | ✅ |

---

## 💬 AI智能问答（/api/v1/chat, /api/v1/agents）

**状态：** ✅ 已实现  
**详细设计：** [AIA/02-API设计](../03-业务模块/AIA-AI智能问答/02-API设计.md)（待创建）

### 对话管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/chat/conversations` | GET | 对话列表 | ✅ |
| `/api/v1/chat/conversations` | POST | 创建对话 | ✅ |
| `/api/v1/chat/conversations/:id` | GET | 对话详情 | ✅ |
| `/api/v1/chat/conversations/:id` | DELETE | 删除对话 | ✅ |
| `/api/v1/chat/conversations/:id/messages` | GET | 对话消息列表 | ✅ |
| `/api/v1/chat/conversations/:id/messages` | POST | 发送消息 | ✅ |

### 智能体管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/agents` | GET | 智能体列表（12个） | ✅ |
| `/api/v1/agents/:id` | GET | 智能体详情 | ✅ |

---

## 📖 AI智能文献（/api/v1/literature）

**状态：** ⏳ 设计中（P0优先级）  
**详细设计：** [ASL/02-API设计](../03-业务模块/ASL-AI智能文献/02-API设计.md)

### 项目管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/literature/projects` | GET | 文献项目列表 | ✅ |
| `/api/v1/literature/projects` | POST | 创建文献项目 | ✅ |
| `/api/v1/literature/projects/:id` | GET | 项目详情 | ✅ |
| `/api/v1/literature/projects/:id` | PUT | 更新项目 | ✅ |
| `/api/v1/literature/projects/:id` | DELETE | 删除项目 | ✅ |

### 文献筛选（标题摘要初筛）⭐

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/literature/projects/:id/items/import` | POST | 导入CSV文件 | ✅ |
| `/api/v1/literature/projects/:id/pico` | POST | 配置PICO标准 | ✅ |
| `/api/v1/literature/projects/:id/pico` | GET | 获取PICO配置 | ✅ |
| `/api/v1/literature/projects/:id/screening/title` | POST | 执行标题摘要初筛 | ✅ |
| `/api/v1/literature/projects/:id/screening/status` | GET | 查询筛选进度 | ✅ |
| `/api/v1/literature/projects/:id/screening/results` | GET | 获取筛选结果 | ✅ |
| `/api/v1/literature/projects/:id/screening/export` | POST | 导出Excel | ✅ |

### 文献筛选（全文复筛）

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/literature/projects/:id/screening/fulltext` | POST | 执行全文筛选 | ✅ |
| `/api/v1/literature/projects/:id/screening/fulltext/status` | GET | 查询进度 | ✅ |

---

## 📚 个人知识库（/api/v1/knowledge-bases）

**状态：** ✅ 已实现  
**详细设计：** [PKB/02-API设计](../03-业务模块/PKB-个人知识库/02-API设计.md)（待创建）

### 知识库管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/knowledge-bases` | GET | 知识库列表 | ✅ |
| `/api/v1/knowledge-bases` | POST | 创建知识库 | ✅ |
| `/api/v1/knowledge-bases/:id` | GET | 知识库详情 | ✅ |
| `/api/v1/knowledge-bases/:id` | PUT | 更新知识库 | ✅ |
| `/api/v1/knowledge-bases/:id` | DELETE | 删除知识库 | ✅ |

### 文档管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/knowledge-bases/:id/documents` | GET | 文档列表 | ✅ |
| `/api/v1/knowledge-bases/:id/documents` | POST | 上传文档 | ✅ |
| `/api/v1/knowledge-bases/:id/documents/:docId` | GET | 文档详情 | ✅ |
| `/api/v1/knowledge-bases/:id/documents/:docId` | DELETE | 删除文档 | ✅ |

### RAG问答

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/knowledge-bases/:id/chat` | POST | 知识库问答 | ✅ |
| `/api/v1/knowledge-bases/:id/search` | GET | 语义检索 | ✅ |

---

## 🧹 数据清洗整理（/api/v1/data-cleaning）

**状态：** ⏳ 规划中（P1优先级）  
**详细设计：** 待设计

### 清洗项目

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/data-cleaning/projects` | GET | 清洗项目列表 | ✅ |
| `/api/v1/data-cleaning/projects` | POST | 创建清洗项目 | ✅ |
| `/api/v1/data-cleaning/projects/:id` | GET | 项目详情 | ✅ |

### ETL配置

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/data-cleaning/projects/:id/etl` | POST | 配置ETL规则 | ✅ |
| `/api/v1/data-cleaning/projects/:id/execute` | POST | 执行清洗任务 | ✅ |

---

## 📊 智能统计分析（/api/v1/analysis）

**状态：** ⏳ 规划中（P2优先级）  
**详细设计：** 待设计

### 分析项目

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/analysis/projects` | GET | 分析项目列表 | ✅ |
| `/api/v1/analysis/projects` | POST | 创建分析项目 | ✅ |
| `/api/v1/analysis/projects/:id/execute` | POST | 执行分析 | ✅ |

---

## 🔧 统计分析工具（/api/v1/tools）

**状态：** ⏳ 规划中（P2优先级）  
**详细设计：** 待设计

### 工具调用

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/tools` | GET | 工具列表（100+） | ✅ |
| `/api/v1/tools/:id` | GET | 工具详情 | ✅ |
| `/api/v1/tools/:id/execute` | POST | 执行工具 | ✅ |

---

## 📄 稿件审查系统（/api/v1/review）

**状态：** ✅ 已实现（独立系统）  
**详细设计：** [RVW/02-API设计](../03-业务模块/RVW-稿件审查系统/02-API设计.md)（待创建）

### 审查任务

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/review/tasks` | GET | 审查任务列表 | ✅ |
| `/api/v1/review/tasks` | POST | 创建审查任务 | ✅ |
| `/api/v1/review/tasks/:id` | GET | 任务详情 | ✅ |
| `/api/v1/review/tasks/:id/execute` | POST | 执行审查 | ✅ |
| `/api/v1/review/tasks/:id/report` | GET | 生成报告（PDF） | ✅ |

---

## 🛠️ 运营管理端（/api/v1/admin）

**状态：** ⏳ 规划中（P1优先级）  
**详细设计：** [ADMIN/02-API设计](../03-业务模块/ADMIN-运营管理端/02-API设计.md)

### 用户管理 ⭐

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/users` | GET | 用户列表 | ✅ ADMIN |
| `/api/v1/admin/users/:id` | GET | 用户详情 | ✅ ADMIN |
| `/api/v1/admin/users/:id` | PUT | 更新用户 | ✅ ADMIN |
| `/api/v1/admin/users/:id/plan` | PUT | 修改套餐 | ✅ ADMIN |
| `/api/v1/admin/users/:id/disable` | POST | 禁用用户 | ✅ ADMIN |

### Feature Flag管理 ⭐

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/feature-flags` | GET | Flag列表 | ✅ ADMIN |
| `/api/v1/admin/feature-flags` | POST | 创建Flag | ✅ ADMIN |
| `/api/v1/admin/feature-flags/:id` | PUT | 更新Flag | ✅ ADMIN |
| `/api/v1/admin/users/:id/flags` | GET | 用户Flag | ✅ ADMIN |
| `/api/v1/admin/users/:id/flags` | PUT | 更新用户Flag | ✅ ADMIN |

### LLM模型管理 ⭐

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/llm/models` | GET | 模型列表 | ✅ ADMIN |
| `/api/v1/admin/llm/models` | POST | 添加模型 | ✅ ADMIN |
| `/api/v1/admin/llm/models/:id` | PUT | 更新模型 | ✅ ADMIN |
| `/api/v1/admin/llm/usage` | GET | LLM使用统计 | ✅ ADMIN |
| `/api/v1/admin/llm/cost-analysis` | GET | 成本分析 | ✅ ADMIN |

### Prompt管理

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/prompts` | GET | Prompt列表 | ✅ ADMIN |
| `/api/v1/admin/prompts` | POST | 创建Prompt | ✅ ADMIN |
| `/api/v1/admin/prompts/:id` | PUT | 更新Prompt | ✅ ADMIN |

### 日志查询

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/logs` | GET | 日志列表 | ✅ ADMIN |
| `/api/v1/admin/logs/errors` | GET | 错误日志 | ✅ ADMIN |
| `/api/v1/admin/logs/operations` | GET | 操作日志 | ✅ ADMIN |

### 数据报表

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/admin/reports/overview` | GET | 总览数据 | ✅ ADMIN |
| `/api/v1/admin/reports/users` | GET | 用户活跃度 | ✅ ADMIN |
| `/api/v1/admin/reports/features` | GET | 功能使用率 | ✅ ADMIN |
| `/api/v1/admin/reports/llm` | GET | LLM统计 | ✅ ADMIN |

---

## 📊 路由统计

### 按模块统计

| 模块 | 端点数量 | 状态 |
|------|---------|------|
| 认证与用户 | 10 | ✅ 已实现 |
| LLM网关 | 5 | ❌ 待实现 |
| AI智能问答 | 8 | ✅ 已实现 |
| AI智能文献 | 15 | ⏳ 设计中 |
| 个人知识库 | 10 | ✅ 已实现 |
| 数据清洗 | 5 | ⏳ 规划中 |
| 智能统计分析 | 3 | ⏳ 规划中 |
| 统计工具 | 3 | ⏳ 规划中 |
| 稿件审查 | 5 | ✅ 已实现 |
| 运营管理端 | 20 | ⏳ 规划中 |
| **总计** | **~85** | - |

---

## ⚠️ 路由冲突检查

### 潜在冲突

**❌ 避免冲突：**
```
# 错误：模块名称冲突
/api/v1/admin/users    # 管理端的用户管理
/api/v1/users          # 平台层的用户管理

# 正确：明确区分
/api/v1/auth/profile   # 当前用户信息
/api/v1/admin/users    # 管理端用户CRUD
```

---

## 🔍 快速查找指南

### 场景1：查找某个模块的所有API
1. 在上面的表格中找到对应模块
2. 点击"详细设计"链接
3. 查看该模块的完整API文档

### 场景2：设计新API端点
1. 查看本文档，确保路由不冲突
2. 参考[API设计规范](./02-API设计规范.md)
3. 使用[API设计模板](../_templates/API设计-模板.md)

### 场景3：查看全局API架构
1. 阅读本文档（快速了解所有端点）
2. 查看[架构设计全景图](../00-系统总体设计/08-架构设计全景图.md)

---

## 🔗 相关文档

**规范：**
- [API设计规范](./02-API设计规范.md) ⭐ 必读
- [认证与授权规范](./02-API设计规范.md#认证与授权)

**模板：**
- [API设计模板](../_templates/API设计-模板.md)

**数据库：**
- [数据库全局视图](./03-数据库全局视图.md)

---

**最后更新：** 2025-11-06  
**维护人：** 技术架构师  
**版本：** v1.0














