Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11676f2840ebd0e5139972d5809149995c712670
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

12 KiB
Raw Blame History

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设计（待创建）

认证相关

端点 方法 说明 认证
/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设计

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设计（待创建）

对话管理

端点 方法 说明 认证
/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设计

项目管理

端点 方法 说明 认证
/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设计（待创建）

知识库管理

端点 方法 说明 认证
/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设计（待创建）

审查任务

端点 方法 说明 认证
/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设计

用户管理 ⭐

端点 方法 说明 认证
/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设计规范
  3. 使用API设计模板

场景3：查看全局API架构

  1. 阅读本文档（快速了解所有端点）
  2. 查看架构设计全景图

🔗 相关文档

规范：

模板：

数据库：

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

Reference in New Issue View Git Blame Copy Permalink