feat(rvw): Implement RVW V2.0 Data Forensics Module - Day 6 StatValidator
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>
This commit is contained in:
125
docs/03-业务模块/RVW-稿件审查系统/00-系统设计/RVW V2.0 开发计划深度审查报告.md
Normal file
125
docs/03-业务模块/RVW-稿件审查系统/00-系统设计/RVW V2.0 开发计划深度审查报告.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# **RVW V2.0 开发计划深度审查报告**
|
||||
|
||||
**审查对象:** RVW V2.0 产品升级开发计划 (v1.0)
|
||||
|
||||
**审查日期:** 2026-02-17
|
||||
|
||||
**审查结论:** ✅ **总体通过 (Approved with Recommendations)**
|
||||
|
||||
**核心评价:** 战略转型精准,MVP 边界清晰,但部分工程细节需补全。
|
||||
|
||||
## **1\. 🟢 值得肯定的亮点 (Strengths)**
|
||||
|
||||
这份计划展现了非常成熟的产品思维和架构能力,以下几点是成功的关键:
|
||||
|
||||
### **1.1 战略级的“降维打击” (Word-First Strategy)**
|
||||
|
||||
* **评价**:这是本计划最明智的决策。放弃死磕 PDF 表格识别(业界公认难题),转而利用投稿环节必然存在的 Word 源文件。
|
||||
* **价值**:这一转变直接将数据提取的准确率上限从 \~70% 提升到了 \~99%,使得“数据审计”在技术上成为了可能。这是典型的“用产品策略解决技术难题”。
|
||||
|
||||
### **1.2 极其克制的 MVP 边界 (Scope Management)**
|
||||
|
||||
* **评价**:明确**不包含** PDF、图片、复杂嵌套表、高级回归验证。
|
||||
* **价值**:3-4 周的周期非常短,只有通过这种“垂直切片 (Vertical Slice)”的方式——只做 Word、只做三线表、只做基础统计——才能确保按时交付一个可用的、高质量的“核弹头”功能,避免陷入泥潭。
|
||||
|
||||
### **1.3 架构的前瞻性 (Skills Architecture)**
|
||||
|
||||
* **评价**:引入 SkillRegistry 和 Profile 配置。
|
||||
* **价值**:这解决了“不同期刊需求打架”的根本矛盾。虽然 MVP 阶段只是硬编码配置,但这套代码结构一旦确立,未来通过数据库动态加载配置(V2.1)将零成本过渡。
|
||||
|
||||
### **1.4 数据验证逻辑的严谨性 (Data Forensics)**
|
||||
|
||||
* **评价**:L1 (算术) 和 L2 (统计) 的逻辑设计非常扎实,特别是“CI 与 P 值一致性检查”,这是抓造假的“黄金法则”,且不需要原始数据,落地性极强。
|
||||
|
||||
## **2\. 🟡 存在的欠缺与风险 (Gaps & Risks)**
|
||||
|
||||
尽管大方向正确,但在落地的工程细节上,还有以下盲点需要注意:
|
||||
|
||||
### **2.1 异步通信机制未明确 (Communication Protocol)**
|
||||
|
||||
* **问题**:计划中提到 Node.js 调用 Python Service,但未明确是**同步 HTTP** 还是**异步队列**。
|
||||
* **风险**:
|
||||
* 如果是同步 HTTP:Word 文档解析 \+ Pandas 计算可能耗时较长(特别是大文档)。如果 LibreOffice 转换卡顿,HTTP 请求容易超时 (Timeout)。
|
||||
* **建议**:明确规定 Node.js 与 Python 之间通过 HTTP 通信时必须设置较长的超时时间(如 60s),或者对于大文件(\>10MB)走异步回调模式。考虑到 MVP 简单性,**建议 MVP 走 HTTP,但要在 Python 端做严格的 Time Limit**。
|
||||
|
||||
### **2.2 Word 转 HTML 的渲染一致性 (Rendering Consistency)**
|
||||
|
||||
* **问题**:计划提到前端要渲染“还原后的 HTML 表格”并高亮错误。关于“是否必须转 HTML”及“目的为何”存在技术决策点。
|
||||
* **深度解析**:
|
||||
* **必须性**:对于“数据侦探”功能,生成 HTML 是**必须的**。
|
||||
* **目的**:
|
||||
1. **可视化**:浏览器无法直接渲染 .docx。
|
||||
2. **精准定位(核心)**:前端需根据后端计算出的坐标(如 R3C4)进行高亮。若前端渲染逻辑(如 mammoth.js)与后端提取逻辑(python-docx)对合并单元格或空行的处理不一致,会导致**高亮错位**(后端指第3行,前端亮第4行)。
|
||||
* **风险**:前后端独立解析 Word 导致 DOM 结构与 DataFrame 结构不匹配,造成“所见非所算”。
|
||||
* **建议**:采用 **“后端重绘”** 策略。
|
||||
* Python 接口返回的 JSON 中,**必须包含一份专门用于前端渲染的 HTML 片段**(只保留结构,不还原复杂样式)。
|
||||
* 或者前端完全基于后端返回的结构化 JSON 数据(Data Grid)**重绘表格**。
|
||||
* **原则**:确保 前端 DOM 结构 \=== 后端计算数据结构,从而实现 100% 精准的高亮交互。
|
||||
|
||||
### **2.3 LibreOffice 的容器化挑战 (Docker Complexity)**
|
||||
|
||||
* **问题**:在 Docker/SAE 环境中运行 LibreOffice (Headless) 是个深坑。
|
||||
* **风险**:
|
||||
* **环境配置复杂**:LibreOffice 需要大量的 Linux 依赖库 (libgl, libX11 等),导致 Docker 镜像体积激增(可能增加 500MB+)。
|
||||
* **中文字体缺失**:如果基础镜像未正确配置中文字体,转换后的文档会出现乱码。
|
||||
* **启动慢**:冷启动转换服务可能需要几秒钟,影响接口响应速度。
|
||||
* **建议**:**战略性放弃 LibreOffice**。
|
||||
* **MVP 阶段策略**:**完全移除 LibreOffice**。后端直接限制上传格式为 .docx(Open XML)。如果用户上传 .doc,前端拦截并提示“请另存为 .docx 格式上传”。不要为了 5% 的 .doc 用户,去冒 50% 的工程延期风险。
|
||||
* **后续替代方案**:如果未来必须支持 .doc,建议使用 **Pandoc**。它比 LibreOffice 轻量得多,且不需要 GUI 依赖,非常适合云原生环境。
|
||||
|
||||
### **2.4 错误处理的用户体验 (Error UX)**
|
||||
|
||||
* **问题**:如果 Word 文档格式非常烂(比如用空格对齐表格,而不是真的表格对象),python-docx 会提取失败或提取出空表。
|
||||
* **风险**:用户上传了文档,系统直接报错 500,或者提示“无表格”,用户会很挫败。
|
||||
* **建议**:定义明确的 **Fallback 机制**。如果提取失败,前端应提示:“无法识别标准表格,请检查文档格式是否为标准 Word 表格”,并允许用户降级运行(只跑规范性检查,不跑数据验证)。
|
||||
|
||||
## **3\. 🔴 技术路线修正建议 (Technical Recommendations)**
|
||||
|
||||
基于上述风险,建议对 Week 1 和 Week 2 的技术细节做如下微调:
|
||||
|
||||
### **3.1 Python 提取器的“双模”设计**
|
||||
|
||||
不要只依赖 python-docx。虽然它是核心,但有些 .doc 转 .docx 后 XML 结构会乱。
|
||||
|
||||
* **建议**:保留 pdfplumber 逻辑作为**备胎**。如果 Word 解析失败,尝试将 Word 转 PDF 后再提取表格(虽然 MVP 排除 PDF 上传,但后端可以利用 PDF 中间态来容错)。**(MVP 阶段可选,若工期紧可不做)**
|
||||
|
||||
### **3.2 明确“定位”策略**
|
||||
|
||||
在 FR-6.4(点击错误高亮单元格)中,后端如何告诉前端是哪个格子?
|
||||
|
||||
* **建议**:采用 **R1C1 坐标系**。
|
||||
* Python 返回:issue\_location: { table\_index: 0, row: 2, col: 3 }
|
||||
* 前端:根据该坐标在重绘的表格中添加 CSS class。不要试图用 XPath 或 DOM ID,因为 Word 转出来的 HTML 结构不可控。
|
||||
|
||||
### **3.3 Skill 执行的超时熔断**
|
||||
|
||||
在 FR-5.3(单个 Skill 失败不影响其他)基础上,增加**熔断机制**。
|
||||
|
||||
* **建议**:SkillExecutor 在执行 DataForensicsSkill 时,如果 30 秒无响应,强制 Kill 并标记该 Skill 为 Timeout,继续执行 EditorialSkill。不能因为一个表格算太久卡死整个审稿报告。
|
||||
|
||||
### **3.4 格式兼容策略调整 (Format Compatibility Pivot)**
|
||||
|
||||
针对 Week 1 的环境搭建,做以下明确调整:
|
||||
|
||||
* **决策**:**Week 1 不安装 LibreOffice**。
|
||||
* **执行**:后端上传接口增加白名单校验,仅允许 application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)。
|
||||
* **备选**:如果开发团队在 Python 环境中遇到不可逾越的 .docx 解析问题,可尝试引入 **Pandoc** 将 .docx 转为 HTML,然后使用 BeautifulSoup 解析表格,这通常比解析 Word XML 更直观。
|
||||
|
||||
## **4\. 补充的非功能性需求 (NFRs)**
|
||||
|
||||
建议在 PRD 中补充以下技术指标,以便测试验收:
|
||||
|
||||
1. **最大文件限制**:Word 文档 ≤ 20MB(防止内存溢出)。
|
||||
2. **表格大小限制**:单表行数 ≤ 500 行(防止 Pandas 计算卡死)。
|
||||
3. **并发限制**:SAE 实例 Python 服务最大并发数建议设为 5-10,防止 LibreOffice 耗尽 CPU。
|
||||
|
||||
## **5\. 审查结论**
|
||||
|
||||
**该计划文档质量优秀,技术路线选择正确。**
|
||||
|
||||
* **Go/No-Go**: **GO (批准启动)**
|
||||
* **关键路径提醒**:
|
||||
1. **Week 1 Day 1**:**跳过 LibreOffice 配置**,直接开始 python-docx 提取器开发。
|
||||
2. **Week 2 Day 7**:Skill 接口定义要尽早冻结,Node.js 和 Python 的契约(JSON Schema)要先行。
|
||||
|
||||
**建议立即按照计划启动 Week 1 开发。**
|
||||
Reference in New Issue
Block a user