Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e3e7e028e8edc8dc516187a1eef8a43be82d1fdc
AIclinicalresearch/docs/04-开发规范/04-API路由总览.md
HaHafeng e3e7e028e8 feat(platform): Complete platform infrastructure implementation and verification 
Platform Infrastructure - 8 Core Modules Completed:
- Storage Service (LocalAdapter + OSSAdapter stub)
- Logging System (Winston + JSON format)
- Cache Service (MemoryCache + Redis stub)
- Async Job Queue (MemoryQueue + DatabaseQueue stub)
- Health Check Endpoints (liveness/readiness/detailed)
- Database Connection Pool (with Serverless optimization)
- Environment Configuration Management
- Monitoring Metrics (DB connections/memory/API)

Key Features:
- Adapter Pattern for zero-code environment switching
- Full backward compatibility with legacy modules
- 100% test coverage (all 8 modules verified)
- Complete documentation (11 docs updated)

Technical Improvements:
- Fixed duplicate /health route registration issue
- Fixed TypeScript interface export (export type)
- Installed winston dependency
- Added structured logging with context support
- Implemented graceful shutdown for Serverless
- Added connection pool optimization for SAE

Documentation Updates:
- Platform infrastructure planning (04-骞冲彴鍩虹璁炬柦瑙勫垝.md)
- Implementation report (2025-11-17-骞冲彴鍩虹璁炬柦瀹炴柦瀹屾垚鎶ュ憡.md)
- Verification report (2025-11-17-骞冲彴鍩虹璁炬柦楠岃瘉鎶ュ憡.md)
- Git commit guidelines (06-Git鎻愪氦瑙勮寖.md) - Added commit frequency rules
- Updated 3 core architecture documents

Code Statistics:
- New code: 2,532 lines
- New files: 22
- Updated files: 130+
- Test pass rate: 100% (8/8 modules)

Deployment Readiness:
- Local environment: 鉁?Ready
- Cloud environment: 馃攧 Needs OSS/Redis dependencies

Next Steps:
- Ready to start ASL module development
- Can directly use storage/logger/cache/jobQueue

Tested: Local verification 100% passed
Related: #Platform-Infrastructure
2025-11-18 08:00:41 +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