HaHafeng
e785969e54
Summary: - Implement L2 Statistical Validator (CI-P consistency, T-test reverse) - Implement L2.5 Consistency Forensics (SE Triangle, SD>Mean check) - Add error/warning severity classification with tolerance thresholds - Support 5+ CI formats parsing (parentheses, brackets, 95% CI prefix) - Complete Python forensics service (types, config, validator, extractor) V2.0 Development Progress (Week 2 Day 6): - Day 1-5: Python service setup, Word table extraction, L1 arithmetic validator - Day 6: L2 StatValidator + L2.5 consistency forensics (promoted from V2.1) Test Results: - Unit tests: 4/4 passed (CI-P, SE Triangle, SD>Mean, T-test) - Real document tests: 5/5 successful, 2 reasonable WARNINGs Status: Day 6 completed, ready for Day 7 (Skills Framework) Co-authored-by: Cursor <cursoragent@cursor.com>
190 lines
8.1 KiB
Markdown
190 lines
8.1 KiB
Markdown
# **RVW V2.0 MVP 产品需求文档 (PRD)**
|
||
|
||
**项目名称：** RVW 智能审稿系统 V2.0 (Intelligent Review Engine)
|
||
|
||
**核心战役：** "数据侦探" (Data Forensics) \+ "柔性架构" (Skills Architecture)
|
||
|
||
**文档版本：** v1.0 (Draft)
|
||
|
||
**优先级：** P0
|
||
|
||
**面向对象：** 产品经理、后端工程师、Python 工程师、前端工程师
|
||
|
||
## **1\. 项目背景与目标 (Background & Goals)**
|
||
|
||
### **1.1 背景**
|
||
|
||
当前的 RVW 模块（v3.2）是一个基于 LLM 的“文档阅读器”，能较好地完成稿约规范性和方法学评估。然而，在面对**中文核心期刊**（对政治安全和数据造假的零容忍）和**高水平英文期刊**（对学术深度的要求）时，系统存在以下痛点：
|
||
|
||
1. **数据验证能力缺失**：无法识别表格中的数据造假（如 P 值捏造、合计错误）。
|
||
2. **架构僵化**：无法针对不同期刊配置不同的审稿流程（如 A 期刊查政治，B 期刊查数据）。
|
||
3. **PDF 解析瓶颈**：复杂表格在 PDF 中识别率低，导致计算不可行。
|
||
|
||
### **1.2 核心目标**
|
||
|
||
本期项目采用 **“垂直切片 (Vertical Slice)”** 策略，不追求大而全，而是集中兵力攻克核心技术壁垒。
|
||
|
||
1. **业务目标**：实现对 **Word 稿件** 中表格数据的\*\*“审计级”验证\*\*，包括算术自洽性和基础统计复核。
|
||
2. **架构目标**：落地 **Skills (技能)** 架构，将审稿能力原子化，为未来扩展（如政治审查、竞品对标）奠定底座。
|
||
3. **交付物**：一个能自动提取 Word 表格、计算数据错误、并在前端高亮显示的 MVP 版本。
|
||
|
||
## **2\. 用户画像与场景 (User Stories)**
|
||
|
||
| 用户角色 | 典型场景 | 期望结果 |
|
||
| :---- | :---- | :---- |
|
||
| **期刊初审编辑** | 收到一篇包含 5 个表格的 Word 稿件，怀疑作者捏造了 P 值。 | 上传稿件后，系统自动高亮 Table 1 中的 3 处算术错误，并提示 Table 2 的 P 值与数据不符（计算值 0.04 vs 报告值 0.8）。 |
|
||
| **系统管理员** | 需要为医学类期刊配置“强制数据检查”，为社科类期刊配置“仅文本检查”。 | 能够在后台通过 Profile 配置文件，灵活组合不同的 Skill（技能）。 |
|
||
| **开发人员** | 需要快速新增一个“图片查重”功能。 | 能够开发一个新的 Skill 并注册到系统，无需修改核心审稿逻辑代码。 |
|
||
|
||
## **3\. MVP 范围定义 (Scope)**
|
||
|
||
为了确保 3 周内上线，我们严格划定 MVP 边界：
|
||
|
||
| 维度 | ✅ MVP 包含 (In Scope) | ❌ MVP 不包含 (Out of Scope) |
|
||
| :---- | :---- | :---- |
|
||
| **文件格式** | **Word (.docx, .doc)** 优先 | PDF, 图片扫描件 |
|
||
| **表格类型** | **三线表** (Standard Tables) | 跨页断裂表、极其复杂的嵌套表 |
|
||
| **验证深度** | **L1 (算术)** \+ **L2 (基础 P 值)** | L3 (回归逻辑), L4 (跨表一致性) |
|
||
| **Skill 数量** | **DataForensicsSkill** (数据侦探) | 政治审查、竞品对标、方法学检查 |
|
||
| **架构改造** | **Skill Interface**, **Profile Config** | 动态 Profile 管理 UI, 计费系统 |
|
||
| **前端交互** | **静态报告** (新增数据验证 Tab) | 交互式 Chat, 在线修改表格 |
|
||
|
||
## **4\. 详细功能需求 (Functional Requirements)**
|
||
|
||
### **4.1 核心功能：数据侦探 (Data Forensics)**
|
||
|
||
#### **FR-1: Word 表格精准提取**
|
||
|
||
* **输入**：Word 文档流。
|
||
* **逻辑**：
|
||
* 识别文档中的所有表格对象。
|
||
* **关键：合并单元格处理**。对于 Merge Cells，必须采用 **Forward Fill (向前填充)** 策略。
|
||
* *Case*: 表头 "Group A" 跨了两列，提取后的 DataFrame 这两列的表头都应为 "Group A"。
|
||
* **关联 Caption**：自动向前回溯，提取表格上方的 "Table X. xxxx" 作为表格标题。
|
||
* **输出**：结构化的 JSON 数据（包含每个单元格的值、坐标）。
|
||
|
||
#### **FR-2: L1 算术自洽性验证**
|
||
|
||
* **逻辑**：Python 后端对提取的 DataFrame 进行计算。
|
||
* **Sum Check**：识别 "Total" 列，验证是否等于其他列之和。
|
||
* **Percentage Check**：识别 n (%) 格式，验证 n/N 是否等于 %。
|
||
* **容错**：允许 ±0.1% 的舍入误差。
|
||
|
||
#### **FR-3: L2 统计学复核**
|
||
|
||
* **逻辑**：针对 T 检验和卡方检验的逆向验证。
|
||
* **识别**：从表头或单元格中提取 Mean ± SD 或 n (%)。
|
||
* **计算**：调用 scipy.stats 计算 P 值。
|
||
* **比对**：将计算出的 P 值与表中报告的 P 值比对。
|
||
* **阈值**：差异 \> 0.05 视为重大错误（Error），0.01-0.05 视为警告（Warning）。
|
||
|
||
### **4.2 架构功能：Skills 引擎**
|
||
|
||
#### **FR-4: Skill 接口标准**
|
||
|
||
* 系统必须定义统一的 Skill 接口：
|
||
interface Skill {
|
||
id: string;
|
||
run(context: DocumentContext, config: any): Promise\<SkillResult\>;
|
||
}
|
||
|
||
#### **FR-5: Profile 配置驱动**
|
||
|
||
* 审稿流程不再硬编码。
|
||
* 系统读取 journal\_profile.json，其中定义了 skills: \["DataForensicsSkill"\]。
|
||
* Worker 根据配置依次调度 Skill。
|
||
|
||
## **5\. 技术架构与实现 (Technical Architecture)**
|
||
|
||
### **5.1 数据流图 (Data Flow)**
|
||
|
||
graph LR
|
||
Word\[Word稿件\] \--\> Python\[Python Microservice\]
|
||
Python \--"1.提取表格\\n2.Pandas计算"--\> Result\[JSON验证结果\]
|
||
Result \--\> Node\[Node.js Backend\]
|
||
Node \--"封装为"--\> Skill\[DataForensicsSkill\]
|
||
Skill \--\> DB\[Postgres (rvw\_schema)\]
|
||
DB \--\> UI\[前端报告页\]
|
||
|
||
### **5.2 Python 服务升级 (python-extraction)**
|
||
|
||
* **新增库**：python-docx, pandas, scipy, libreoffice (Docker内)。
|
||
* **新增接口**：POST /api/v1/forensics/analyze\_docx。
|
||
* **核心类**：
|
||
* DocxTableExtractor: 负责 DOM 解析和清洗。
|
||
* StatValidator: 负责数学计算。
|
||
|
||
### **5.3 Node.js 后端升级**
|
||
|
||
* **目录结构**：
|
||
* modules/rvw/skills/core/: 存放基础接口 (Skill, SkillRegistry)。
|
||
* modules/rvw/skills/library/: 存放具体实现 (DataForensicsSkill)。
|
||
* **数据库变更**：
|
||
* ReviewTask 表增加 contextData (Json) 字段，用于存储 Skill 的输出。
|
||
|
||
### **5.4 前端升级 (frontend-v2)**
|
||
|
||
* **TaskDetail**：新增一个 Tab "数据验证 (Data Forensics)"。
|
||
* **展示组件**：
|
||
* 左侧：渲染还原后的 HTML 表格。
|
||
* 右侧：错误列表（点击错误项，表格中对应单元格高亮变红）。
|
||
|
||
## **6\. 实施路线图 (Roadmap)**
|
||
|
||
我们采用 **3 周冲刺** 计划。
|
||
|
||
### **Week 1: 攻克算力 (Python & Word)**
|
||
|
||
* **目标**：Python API 能跑通，准确提取 Word 表格并算出错误。
|
||
* **关键任务**：
|
||
1. 集成 LibreOffice 实现 doc 转 docx。
|
||
2. 编写 DocxTableExtractor (重点解决合并单元格)。
|
||
3. 编写 StatValidator。
|
||
|
||
### **Week 2: 架构封装 (Node.js)**
|
||
|
||
* **目标**：后端代码 Skills 化，不再写死逻辑。
|
||
* **关键任务**：
|
||
1. 定义 TypeScript Skill 接口。
|
||
2. 实现 DataForensicsSkill (调用 Python)。
|
||
3. 改造 ReviewService 使用 Profile 配置。
|
||
|
||
### **Week 3: 前端与交付**
|
||
|
||
* **目标**：用户可见。
|
||
* **关键任务**：
|
||
1. 开发数据验证报告 UI。
|
||
2. 全链路联调测试。
|
||
3. 部署上线。
|
||
|
||
## **7\. 验收标准 (Acceptance Criteria)**
|
||
|
||
1. **准确性**：上传一份标准的临床三线表 Word 文档，表格数据提取准确率需达到 **99%**（无错行错列）。
|
||
2. **验证能力**：
|
||
* 能检出明显的 Sum 错误（如 50+50=90）。
|
||
* 能检出明显的 P 值错误（如两组数据差异巨大但 P=0.8）。
|
||
3. **稳定性**：处理 100 页的 Word 文档不超时（或有合理的异步处理机制）。
|
||
4. **架构规范**：后端代码中不存在硬编码的审稿逻辑，必须通过 Skill 模式调用。
|
||
|
||
## **8\. 附录：数据结构示例**
|
||
|
||
**Python 返回的 JSON 格式：**
|
||
|
||
{
|
||
"tables": \[
|
||
{
|
||
"id": "tbl\_0",
|
||
"caption": "Table 1\. Baseline Characteristics",
|
||
"issues": \[
|
||
{
|
||
"severity": "ERROR",
|
||
"cell\_ref": "R3C4",
|
||
"message": "Calculated P-value (0.03) differs from reported (0.85)",
|
||
"evidence": { "calc": 0.03, "report": 0.85 }
|
||
}
|
||
\],
|
||
"data": \[ ...二维数组... \]
|
||
}
|
||
\]
|
||
}
|