Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8137e3cde2f6e115de0e922334ff1d196dc9d502
AIclinicalresearch/docs/04-开发规范/04-API路由总览.md
HaHafeng 66255368b7 feat(admin): Add user management and upgrade to module permission system 
Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational
2026-01-16 13:42:10 +08:00

406 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
Reference in New Issue View Git Blame Copy Permalink