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>
125 lines
8.2 KiB
Markdown
125 lines
8.2 KiB
Markdown
# **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 开发。** |