HaHafeng
ba464082cb
Summary: - Harden RVW prompt protocol handling and methodology review flow with 20-checkpoint coverage, divide-and-conquer execution, and timeout tuning - Update RVW frontend methodology report rendering to show real structured outputs and grouped checkpoint sections - Include pending backend/frontend updates across IIT admin, SSA, extraction forensics, and related integration files - Sync system and RVW status documentation, deployment checklist, and RVW architecture/plan docs Validation: - Verified lint diagnostics for touched RVW backend/frontend files show no new errors - Kept backup dump files and local test artifacts untracked Made-with: Cursor
22 KiB
22 KiB
RVW稿件审查模块 - 当前状态与开发指南
文档版本： v6.2
创建日期： 2026-01-07
最后更新： 2026-03-13
维护者： 开发团队
当前状态： 🚀 V3.0.2 "方法学稳定性增强" 进行中（分治并行 + 20检查点覆盖 + 展示口径收敛）
文档目的： 快速了解RVW模块状态，为新AI助手提供上下文🎉 V3.0 进展（2026-03-07）：
- ✅ LLM 数据核查：DataForensicsSkill 增加 LLM 验证通道，规则验证兜底，独立 60s 超时
- ✅ 临床专业评估：新增 ClinicalAssessmentSkill，基于 FINER 标准的研究选题系统评估
- ✅ PromptService 集成：RVW_DATA_VALIDATION + RVW_CLINICAL 两个 Prompt 可在运营管理端配置
- ✅ 稳定性增强：SkillExecutor 使用 Promise.allSettled 实现并行故障隔离
- ✅ 部分完成支持：新增
partial_completed状态 +errorDetails字段，部分模块失败仍展示成功结果- ✅ 前端 4 Tab 报告：稿约规范性 / 方法学 / 数据验证 / 临床评估，Word 导出全覆盖
⚡ V3.0.1 增强（2026-03-10）：
- ✅ 4模块受控并行：DataForensics 与 Editorial/Methodology/Clinical 同组并行，
maxConcurrency=4控制并发上限- ✅ 增量结果持久化：每个 Skill 完成即写入任务中间结果，
getTaskDetail返回模块级reviewProgress- ✅ 先出先看：TaskDetail 在审查中即可展示已完成模块（无需等待全流程结束）
- ✅ Word 导出修复：补齐“数据验证”章节，导出汇总 + 表格明细 + 该表问题列表
🆕 V3.0.2 进展（2026-03-13）：
- ✅ 方法学 Prompt 动静分离收敛：业务提示词继续走运营管理端，系统协议负责结构化输出
- ✅ 20检查点结构化增强：方法学结果新增
checkpoints（id 1-20，状态与发现可追踪）- ✅ 方法学分治并行评估（A/B/C）：按 1-9 / 10-14 / 15-20 三段并行，降低整包超时概率
- ✅ 规则汇总器合并结果：统一生成
overall_score/summary/conclusion/checkpoints/parts，并保留降级兜底- ✅ 前端展示口径统一：方法学报告按“三大项->检查点”展示，去除重复占位文案并显示真实LLM内容
V2.0 进展回顾：
- ✅ L1 算术验证 + L2 统计验证 + L2.5 一致性取证
- ✅ Skills 核心框架（types, registry, executor, profile）
- ✅ DataForensicsSkill + EditorialSkill + MethodologySkill
- ✅ ReviewWorker 改造 + 前端数据验证 Tab
📊 模块概览
基本信息
| 项目 | 信息 |
|---|---|
| 模块名称 | RVW - 稿件审查系统 (Review) |
| 模块定位 | 智能期刊审稿辅助系统（可独立销售） |
| 商业价值 | ⭐⭐⭐⭐⭐ 极高 |
| 独立性 | ⭐⭐⭐⭐⭐ 极高（用户群完全不同） |
| 目标用户 | 期刊初审编辑 |
| 开发状态 | 🚀 V3.0.2 进行中：方法学分治并行 + 20检查点覆盖展示 + 超时优化 |
核心目标
打造一个**"开箱即用"**的智能审稿工具。编辑上传稿件，系统自动运行多维检查（规范性+方法学+数据验证+临床评估），输出可供参考的审稿报告。
核心指标：上传到出报告 < 3分钟（4模块并行）；规范性问题检出率 > 80%
功能规格
核心AI能力（已完成 ✅）
-
稿约规范性评估（11项标准）
- 文题字数、摘要结构、参考文献、图片DPI等
- 基于《中华医学超声杂志》稿约标准
-
方法学评估（3部分，20个检查点）
- 科研设计评估（9个检查点）
- 统计学方法描述评估（5个检查点）
- 统计分析评估（6个检查点）
-
数据验证（V2.0 规则 + V3.0 LLM 双通道）
- L1 算术验证：行列加总、百分比计算
- L2 统计验证：CI↔P 一致性、T检验、卡方检验
- L2.5 一致性取证：SE三角验证、SD>Mean检查
- LLM 智能核查：批量表格发给 LLM 核查（独立 60s 超时，失败降级为纯规则验证）
-
临床专业评估（V3.0 新增）
- 基于 FINER 标准（可行性/创新性/伦理性/相关性）
- 研究问题明确性评估（PICO 完整性）
- 创新性 + 临床价值 + 科学性 + 可行性多维分析
- Prompt 可在运营管理端配置（RVW_CLINICAL）
-
综合评分 + PICO提取
- 规范性分数（0-100）
- 方法学状态（🔴错误 🟡存疑 🟢通过）
- PICO结构化提取（P/I/C/O）
交互功能（✅ 已完成）
| 功能 | 旧版本 | 新版本 | 状态 |
|---|---|---|---|
| 单文件上传 | ✅ | ✅ | ✅ 已完成 |
| 批量上传 | ❌ | ✅ | ✅ 已完成 |
| 审稿工作台（宽表） | ❌ | ✅ | ✅ 已完成 |
| 智能体选择 | 自动 | 用户可选 | ✅ 已完成 |
| 批量操作 | ❌ | ✅ | ✅ 已完成 |
| 状态筛选 | ❌ | ✅ | ✅ 已完成 |
| 历史归档 | ❌ | ✅ | ⏸️ 数据库已支持，UI暂缓 |
| 系统设置 | ❌ | ✅ | ⏸️ 暂不开发 |
| 登录页面 | ❌ | ⏸️ | ⏸️ 复用平台登录 |
| PICO卡片 | ❌ | ✅ | ⏸️ 数据库已支持，UI暂缓 |
🏗️ 架构状态
✅ 已完成迁移（Modules）
后端（✅ 已完成）：
backend/src/modules/rvw/
├── routes/index.ts # v2 API路由（/api/v2/rvw）
├── controllers/reviewController.ts # 控制器（含批量操作、智能体选择）
├── services/
│ ├── reviewService.ts # 核心服务（任务创建、执行）
│ ├── editorialService.ts # 稿约规范性评估
│ ├── methodologyService.ts # 方法学评估
│ ├── clinicalService.ts # 🆕 V3.0 临床专业评估服务
│ └── utils.ts # 工具函数
├── workers/
│ └── reviewWorker.ts # pg-boss异步任务处理（V2.0 Skills集成 + V3.0 partial_completed + V3.0.1 增量落库）
├── skills/ # V2.0 Skills 架构
│ ├── core/ # 核心框架（types, registry, executor[allSettled]等）
│ ├── library/ # Skill 实现（Forensics[+LLM], Editorial, Methodology, 🆕Clinical）
│ └── index.ts # 模块入口
├── types/index.ts # TypeScript类型定义（含 partial_completed 状态）
└── __tests__/ # API测试脚本
前端（✅ 已完成）：
frontend-v2/src/modules/rvw/
├── index.tsx # 模块入口
├── api/index.ts # API接口
├── types/index.ts # 类型定义
├── styles/index.css # 样式文件
├── pages/
│ └── Dashboard.tsx # 审稿工作台（任务列表、筛选）
└── components/
├── Header.tsx # 页头（上传按钮）
├── Sidebar.tsx # 侧边栏导航
├── TaskTable.tsx # 任务列表表格（支持 partial_completed 状态）
├── TaskDetail.tsx # 任务详情（进度条+增量展示+Word导出+部分完成警告）
├── EditorialReport.tsx # 稿约规范性报告
├── MethodologyReport.tsx # 方法学评估报告
├── ForensicsReport.tsx # 数据验证报告（含 LLM 核查结果）
├── ClinicalReport.tsx # 🆕 V3.0 临床专业评估报告
├── AgentModal.tsx # 智能体选择弹窗（4 个维度）
└── ScoreRing.tsx # 评分环组件
旧版本（保留兼容）：
backend/src/legacy/
├── routes/reviewRoutes.ts # v1 API路由（保留）
├── controllers/reviewController.ts
└── services/reviewService.ts
Prompt（文件 + PromptService 数据库双通道）：
backend/prompts/
├── review_editorial_system.txt # 稿约评估（266行）
└── review_methodology_system.txt # 方法学评估（257行）
数据库 prompt_templates 表（运营管理端可配置）：
├── RVW_DATA_VALIDATION # 🆕 V3.0 数据验证 LLM 核查 Prompt
└── RVW_CLINICAL # 🆕 V3.0 临床专业评估 Prompt
数据库（✅ 已完成）：
- ReviewTask表已添加新字段：selectedAgents, editorialScore, methodologyScore, methodologyStatus, picoExtract, isArchived, archivedAt
- 🆕 V3.0 新增 error_details JSONB 字段（Skill 级失败详情，支持 partial_completed 状态）
- ✅ Schema已迁移到 rvw_schema（2026-01-10完成）
📋 开发进度
| Phase | 任务 | 状态 | 完成日期 |
|---|---|---|---|
| Phase 1 | 后端模块迁移与扩展 | ✅ 已完成 | 2026-01-07 |
| Phase 2 | 数据库字段扩展 | ✅ 已完成 | 2026-01-07 |
| Phase 3 | 前端重构（frontend-v2） | ✅ 已完成 | 2026-01-07 |
| Phase 4 | 集成测试与Bug修复 | ✅ 已完成 | 2026-01-10 |
| Phase 5 | 报告导出（Word） | ✅ 已完成 | 2026-01-10 |
| Phase 6 | Schema隔离迁移 | ✅ 已完成 | 2026-01-10 |
| Phase 7 | 系统设置与归档 | ⏸️ 暂缓 | - |
| 总计 | - | 95% | - |
Phase 1-5 完成内容
后端（Phase 1）：
- ✅ 创建
backend/src/modules/rvw/模块结构 - ✅ 迁移并优化 reviewService、editorialService、methodologyService
- ✅ 实现智能体选择（selectedAgents：editorial/methodology/both）
- ✅ 实现批量运行API（batchRunReviewTasks）
- ✅ 替换 console.log 为 logger 服务
- ✅ 注册 v2 API路由（/api/v2/rvw）
- ✅ 实现 pg-boss 异步任务处理（reviewWorker）
数据库（Phase 2）：
- ✅ 添加 selectedAgents 字段（String[]）
- ✅ 添加 editorialScore 字段（Float?）
- ✅ 添加 methodologyScore 字段（Float?）- 2026-01-10新增
- ✅ 添加 methodologyStatus 字段（String?）
- ✅ 添加 picoExtract 字段（Json?）
- ✅ 添加 isArchived、archivedAt 字段（归档支持）
- ✅ 使用 prisma db push 同步到数据库
前端（Phase 3）：
- ✅ 创建
frontend-v2/src/modules/rvw/模块目录结构 - ✅ 实现 Dashboard 页面（任务列表、筛选、批量操作）
- ✅ 实现 TaskDetail 组件（审稿进度条、实时状态轮询）
- ✅ 实现 EditorialReport 组件（稿约规范性评估报告）
- ✅ 实现 MethodologyReport 组件（方法学评估报告）
- ✅ 实现 AgentModal 组件（智能体选择弹窗）
- ✅ 注册到 moduleRegistry.ts
集成测试与Bug修复（Phase 4）：
- ✅ 修复方法学分数不显示问题（列表页显示"warn"而不是分数）
- ✅ 修复只选方法学时详情页不显示报告问题
- ✅ 修复 activeTab 默认值导致的显示问题
- ✅ 完整测试单智能体和双智能体审稿流程
报告导出（Phase 5）：
- ✅ 安装 docx 和 file-saver 库
- ✅ 实现 Word 文档导出功能
- ✅ 支持结构化报告（标题、基本信息表格、稿约规范性、方法学评估）
- ✅ 问题和建议使用不同颜色标记
Schema隔离迁移（Phase 6）：
- ✅ 将 review_tasks 表从 public 迁移到 rvw_schema
- ✅ 更新 Prisma schema 中的 @@schema 指令
- ✅ 重新生成 Prisma Client
- ✅ 验证所有查询和关联正常工作
详细任务清单见：RVW模块迁移计划
🔧 技术依赖
复用的平台能力
| 能力 | 位置 | 用途 |
|---|---|---|
| LLM网关 | @/common/llm/LLMFactory |
AI评估（稿约/方法学/数据核查/临床评估） |
| PromptService | @/common/prompt |
🆕 V3.0 Prompt 管理（灰度预览、运营端配置） |
| 文档处理 | ExtractionClient |
Word/PDF文本提取 |
| 存储 | @/common/storage |
文件存储（OSS/本地） |
| 日志 | @/common/logging |
结构化日志 |
| 任务队列 | jobQueue |
异步任务处理（pg-boss） |
LLM模型
| 模型 | 用途 | 说明 |
|---|---|---|
| DeepSeek-V3 | 默认 | 性价比高，推理能力强 |
| DeepSeek-R1 | 备选 | 深度推理 |
| Qwen3-72B | 备选 | 中文理解好 |
📚 相关文档
需求文档
- 智能期刊审稿系统MVP PRD
- 智能审稿V7原型 - 可直接浏览器打开
开发文档
- 迁移计划（v2.0整合版） ⬅️ 主要开发文档
参考文档
- 现有系统技术摸底报告 - Line 578-748
- 云原生开发规范
- 系统架构分层设计
Prompt文件
🎯 快速开始
访问审稿模块
-
启动后端
cd backend npm run dev -
启动前端（新版 frontend-v2）
cd frontend-v2 npm run dev -
访问审稿页面
- 打开
http://localhost:3000 - 点击顶部导航栏的 "预审稿" 标签
- 或直接访问
http://localhost:3000/rvw
- 打开
-
测试流程
- 点击"上传稿件"按钮
- 选择Word/PDF文档（≤5MB）
- 选择智能体（稿约规范性/方法学/两者都选）
- 点击"运行"按钮
- 等待AI评估完成（约1-2分钟）
- 查看评估报告
API测试（新版 v2 API）
### 获取任务列表
GET http://localhost:3001/api/v2/rvw/tasks
### 按状态筛选
GET http://localhost:3001/api/v2/rvw/tasks?status=pending
### 上传稿件
POST http://localhost:3001/api/v2/rvw/tasks
Content-Type: multipart/form-data
# file: 文件
# selectedAgents: ["editorial", "methodology"]
### 运行单个任务
POST http://localhost:3001/api/v2/rvw/tasks/{{taskId}}/run
Content-Type: application/json
{"selectedAgents": ["editorial", "methodology"]}
### 批量运行任务
POST http://localhost:3001/api/v2/rvw/tasks/batch-run
Content-Type: application/json
{"taskIds": ["id1", "id2"], "selectedAgents": ["editorial"]}
### 获取任务详情
GET http://localhost:3001/api/v2/rvw/tasks/{{taskId}}
### 获取报告
GET http://localhost:3001/api/v2/rvw/tasks/{{taskId}}/report
旧版API（保持兼容）
### 上传稿件（旧API）
POST http://localhost:3001/api/v1/review/upload
Content-Type: multipart/form-data
⚠️ 注意事项
对新AI助手
- ✅ V3.0 已完成：4 维审查 + 稳定性增强 + partial_completed 支持
- ✅ 已集成到 frontend-v2：通过顶部导航栏"预审稿"进入
- ✅ v2 API 已就绪：/api/v2/rvw/* 路由可用
- ✅ 遵循云原生规范：使用 logger 服务替代 console.log
- ✅ PromptService 集成：RVW_DATA_VALIDATION + RVW_CLINICAL Prompt 可在运营管理端配置
- ✅ 并行故障隔离：SkillExecutor 使用 Promise.allSettled，单个 Skill 崩溃不影响其他
- ⚠️ 保留旧API：v1路由保持兼容，支持旧前端
已完成改造
| 问题 | 改造前 | 改造后 | 状态 |
|---|---|---|---|
| 日志 | console.log | logger服务 | ✅ 已完成 |
| 用户认证 | Mock用户ID | getUserId(request) | ✅ 已完成 |
| 智能体选择 | 自动 | 用户可选 | ✅ 已完成 |
| 批量操作 | 无 | batchRunReviewTasks | ✅ 已完成 |
待后续改造
| 问题 | 当前 | 目标 | 优先级 |
|---|---|---|---|
| Schema位置 | ✅ rvw_schema | - | ✅ 已完成 |
| 任务处理 | ✅ pg-boss | - | ✅ 已完成 |
| 报告导出 | ✅ Word (.docx) | PDF优化 | P3 |
📈 验收标准
根据MVP PRD，验收标准如下：
-
流程通：用户能成功上传5个PDF，勾选双模型运行，等待3分钟内，状态全部变为"已完成"
-
报告准：
- 上传一篇故意删掉"摘要结论"的稿件，规范性智能体必须报错
- 上传一篇故意混淆"t检验"和"卡方检验"的稿件，方法学智能体必须报"存疑"或"错误"
-
无崩溃：连续上传20个文件，系统不卡死，不白屏
🚀 未来规划
✅ 已完成（2026-01-07 ~ 2026-01-10）- V1.x
- 架构迁移到 modules/rvw（后端）
- 架构迁移到 modules/rvw（前端 frontend-v2）
- 整合MVP新功能（批量上传、工作台、智能体选择）
- 云原生改造（logger服务）
- v2 API 路由注册
- 数据库字段扩展
- pg-boss异步任务处理（2026-01-10）
- Word报告导出（2026-01-10）
- 方法学分数显示修复（2026-01-10）
- 单智能体审稿显示修复（2026-01-10）
- Schema迁移到 rvw_schema（2026-01-10）
🚀 V2.0 "数据侦探" 开发进度（2026-02-12 ~ 进行中）
| 阶段 | 任务 | 状态 | 完成日期 |
|---|---|---|---|
| Week 1 Day 1 | Python 服务搭建 | ✅ 已完成 | 2026-02-12 |
| Week 1 Day 2 | Word 表格提取 + 特殊符号 | ✅ 已完成 | 2026-02-13 |
| Week 1 Day 3 | L1 算术验证器 | ✅ 已完成 | 2026-02-14 |
| Week 1 Day 4 | 数据结构设计 | ✅ 已完成 | 2026-02-15 |
| Week 1 Day 5 | API 集成 | ✅ 已完成 | 2026-02-16 |
| Week 2 Day 6 | L2 统计验证器 + L2.5 一致性取证 | ✅ 已完成 | 2026-02-17 |
| Week 2 Day 7 | Skills 核心框架 | ✅ 已完成 | 2026-02-18 |
| Week 2 Day 8 | DataForensicsSkill | ✅ 已完成 | 2026-02-18 |
| Week 2 Day 9 | EditorialSkill 封装 | ✅ 已完成 | 2026-02-18 |
| Week 2 Day 10 | ReviewWorker 改造 | ✅ 已完成 | 2026-02-18 |
| Week 3 | 统计验证扩展 + 用户体验优化 | ✅ 已完成 | 2026-02-18 |
| Week 4 | 功能测试 + Bug 修复 | 📋 待开始 | - |
V2.0 核心功能（已完成）：
- L1 算术验证：行列加总、百分比验证
- L2 统计验证：CI↔P 一致性、T检验逆向、卡方检验（含 subrow 精确高亮）
- L2.5 一致性取证（终审提权）：SE三角验证、SD>Mean检查
- Skills 架构：Skill Registry、Skill Executor、Journal Profiles
- 负号归一化：6 种 Unicode 负号变体支持
- 文件格式提示：PDF/.doc 无法数据验证的用户提示
Week 3 完成内容（2026-02-18）：
- ✅ 负号归一化（防止 float() 崩溃）
- ✅ T 检验验证增强（智能样本量提取）
- ✅ SE 三角验证增强（subrow 支持）
- ✅ CI vs P 值验证增强（subrow 支持）
- ✅ 前端翻译映射更新（6 种新 IssueType）
- ✅ 文件格式提示（Header、ReportDetail、TaskDetail）
🚀 V3.0 "智能审稿增强" 开发进度（2026-03-07）
| 任务 | 状态 | 说明 |
|---|---|---|
| LLM 数据核查通道 | ✅ 已完成 | DataForensicsSkill 增加 LLM 验证，独立 60s 超时，规则验证兜底 |
| RVW_DATA_VALIDATION Prompt | ✅ 已完成 | PromptService 集成，运营管理端可配置 |
| 临床专业评估 Skill | ✅ 已完成 | ClinicalAssessmentSkill，基于 FINER 标准 |
| RVW_CLINICAL Prompt | ✅ 已完成 | PromptService 集成，运营管理端可配置 |
| SkillExecutor Promise.allSettled | ✅ 已完成 | 并行 Skill 故障隔离，单个崩溃不影响其他 |
| partial_completed 状态 | ✅ 已完成 | 新增任务状态 + error_details JSONB 字段 |
| reviewWorker 写入 errorDetails | ✅ 已完成 | 记录每个失败/超时 Skill 的名称和原因 |
| 前端 4 Tab 报告 | ✅ 已完成 | 稿约规范性/方法学/数据验证/临床评估 |
| 前端 partial_completed UI | ✅ 已完成 | 琥珀色警告横幅 + 列表"部分完成"标签 |
| Word 导出覆盖临床评估 | ✅ 已完成 | 导出报告包含临床专业评估章节 |
⚡ V3.0.1 "性能与体验增强" 开发进度（2026-03-10）
| 任务 | 状态 | 说明 |
|---|---|---|
| DataForensics 并入并行组 | ✅ 已完成 | 与 Editorial/Methodology/Clinical 同组并行执行 |
| 并发上限控制 | ✅ 已完成 | Executor 支持按 maxConcurrency 分批并行 |
| 模块完成即持久化 | ✅ 已完成 | Worker 通过 onSkillComplete 增量写入 contextData |
| 任务详情增量返回 | ✅ 已完成 | getTaskDetail 返回模块结果与 reviewProgress |
| 前端先出先看 | ✅ 已完成 | 审查过程中实时展示已完成 Tab |
| Word 导出补齐数据验证 | ✅ 已完成 | 导出包含数据验证汇总、表格明细、该表问题列表 |
🆕 V3.0.2 "方法学稳定性增强" 开发进度（2026-03-13）
| 任务 | 状态 | 说明 |
|---|---|---|
方法学 checkpoints 扩展 |
✅ 已完成 | 结果结构支持 20 检查点逐项状态与发现 |
| 方法学前端展示收敛 | ✅ 已完成 | 采用“三大项分组 + 检查点明细”，移除重复占位展示 |
| 方法学分治并行评估 | ✅ 已完成 | A/B/C 三段并行执行（1-9/10-14/15-20） |
| 方法学规则汇总器 | ✅ 已完成 | 合并分段结果并统一结论；分段失败可降级 |
| 方法学超时窗口扩展 | ✅ 已完成 | MethodologySkill 超时从 5min 调整到 8min |
| 快速模式开关（后续） | ⏳ 规划中 | 长文档自动降耗与更短输出预算 |
后续版本（V3.1+）
- 全面移除评分机制（只列问题，不打分）
- 单模块重试机制（partial_completed → 重试失败模块）
- ANOVA 验证（多组比较）
- 配对 T 检验验证
- 非参数检验（Mann-Whitney、Wilcoxon）
- .doc 格式支持（Pandoc 方案评估）
- Profile 管理 UI（期刊配置界面）
- PDF报告导出优化
- PICO卡片UI实现
- 历史归档UI实现
- 独立产品打包
文档版本： v6.2
最后更新： 2026-03-13
当前状态： 🚀 V3.0.2 "方法学稳定性增强" 进行中（分治并行 + 20检查点覆盖 + 展示口径收敛）
下一步： V3.0.2 收尾验证（超时率/覆盖率） + V3.1 单模块重试与评分策略优化