Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete documentation system (250+ files)

Browse Source 
- System architecture and design documentation
- Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST)
- ASL module complete design (quality assurance, tech selection)
- Platform layer and common capabilities docs
- Development standards and API specifications
- Deployment and operations guides
- Project management and milestone tracking
- Architecture implementation reports
- Documentation templates and guides
This commit is contained in:
HaHafeng
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
Download Patch File Download Diff File Expand all files Collapse all files

393
docs/04-开发规范/04-API路由总览.md Normal file
View File

@@ -0,0 +1,393 @@
# 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