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
221 lines
8.4 KiB
Markdown
221 lines
8.4 KiB
Markdown
# RVW V4.0 智能审稿输出解耦开发计划
|
||
|
||
> 文档版本：v1.1
|
||
> 创建日期：2026-03-13
|
||
> 维护者：RVW 模块开发组
|
||
> 优先级：P0
|
||
> 目标周期：2 阶段（P0: 1 周快速上线；P1: 2 周配置化增强）
|
||
> 适用范围：方法学、稿约规范性、临床评估、数据验证四通道
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 当前痛点
|
||
|
||
1. 运营端可编辑 Prompt 与系统 JSON 协议同时约束输出，存在格式冲突。
|
||
2. 专家希望掌控最终报告呈现（A/B/C、1/2/3/4 等），但当前展示仍受通道实现细节影响。
|
||
3. JSON 解析稳定性与专家自然语言表达存在天然张力。
|
||
4. 运营发布后难以快速验证“是否真的生效”（缺少统一版本指纹与可观测性）。
|
||
|
||
### 1.2 V4.0 核心目标
|
||
|
||
构建“数据与展示分离”的稳定架构，并采用“先快后全”的实施策略：
|
||
|
||
- LLM 负责结构化评估数据（系统可解析、可存储、可统计）。
|
||
- P0 先使用代码内置默认模板渲染专家报告，快速验证核心链路。
|
||
- P1 再开放运营端模板配置（Handlebars），实现风格动态化。
|
||
- 系统协议只负责结构约束，不覆盖业务判断。
|
||
- 支持版本化、回滚、可观测，避免“看起来没生效”。
|
||
|
||
---
|
||
|
||
## 2. 方案边界与设计原则
|
||
|
||
### 2.1 In Scope（本期纳入）
|
||
|
||
- 四通道统一双轨输出：`structured_review` + `rendered_report_text`。
|
||
- P0：后端新增“硬编码默认模板”渲染层与失败降级策略。
|
||
- P1：运营端新增“报告模板”配置能力（DRAFT/ACTIVE/发布/回滚）。
|
||
- 前端报告页与导出统一使用 `rendered_report_text` 展示。
|
||
- 增加 Prompt/Template 版本指纹日志与排障接口。
|
||
|
||
### 2.2 Out of Scope（本期不纳入）
|
||
|
||
- 双 Agent Writer 高拟人化撰写链路（保留为后续增强）。
|
||
- 全量替换所有模型适配器为单一厂商 Structured Outputs（先做兼容层）。
|
||
- 复杂可视化模板编辑器（先不上，后续按运营反馈决定）。
|
||
- P0 阶段不开放模板运营配置界面（先用代码默认模板快速上线）。
|
||
|
||
### 2.3 设计原则
|
||
|
||
1. 业务可变（运营可配）与协议稳定（研发固化）严格分层。
|
||
2. 失败可降级但不可静默：所有 fallback 必须留痕并告警。
|
||
3. 默认向后兼容：旧任务、旧报告不破坏。
|
||
4. 能复用现有能力就不重复造轮子（PromptService、Handlebars、pg-boss、现有审查流程）。
|
||
|
||
---
|
||
|
||
## 3. 目标架构（V4.0）
|
||
|
||
## 3.1 双轨输出模型
|
||
|
||
- 结构化轨（系统轨）
|
||
- 字段：`overall_score`、`conclusion`、`issues/parts/items` 等。
|
||
- 用途：存库、统计、评分、后续机器处理。
|
||
|
||
- 展示轨（专家轨）
|
||
- 字段：`report_text`（Markdown/纯文本）。
|
||
- 来源：`report_template` + 结构化数据渲染。
|
||
- 用途：前端展示、导出、人工审阅。
|
||
|
||
## 3.2 通道配置拆分
|
||
|
||
每个通道最终拆分为两份可配置资产（P1 落地）：
|
||
|
||
- `RVW_xxx_PROMPT`：专家评估标准（不含输出格式约束）。
|
||
- `RVW_xxx_REPORT_TEMPLATE`：专家展示模板（Handlebars）。
|
||
|
||
系统保留一份研发固化协议：
|
||
|
||
- `RVW_PROTOCOL_xxx`：结构化字段 schema/协议约束（代码侧维护）。
|
||
|
||
---
|
||
|
||
## 4. 分阶段实施计划
|
||
|
||
## 4.1 Phase P0（Week 1）快速上线：硬编码默认模板 + 预留配置能力
|
||
|
||
目标：1 周内上线“稳定结构化 + 专家样式展示”的核心能力。
|
||
|
||
- 梳理四通道当前输入输出、协议、前端渲染路径。
|
||
- 标记并移除“业务硬编码覆盖”点（仅保留协议校验/解析兜底）。
|
||
- 新增 `reportRenderer` 服务，内置四通道默认模板（代码内维护）。
|
||
- `reviewWorker` 汇总阶段写入 `rendered_report_text`。
|
||
- 前端报告页与导出优先展示 `rendered_report_text`，旧数据兼容兜底。
|
||
- 增加可观测字段：`promptVersion`、`promptFingerprint`、`render_fallback`。
|
||
- 预留配置扩展点：模板来源抽象接口（先实现 `code` provider，后续接 `db` provider）。
|
||
|
||
交付物：
|
||
|
||
- `backend/src/modules/rvw/services/reportRenderer.ts`（默认模板模式）
|
||
- 四通道渲染接入点
|
||
- 前端展示/导出统一到展示轨
|
||
- P0 上线验收报告与回滚脚本
|
||
|
||
## 4.2 Phase P1（Week 2-3）增强：运营端模板配置化
|
||
|
||
目标：在不改变 P0 主链路的前提下，实现模板动态可配、可发布、可回滚。
|
||
|
||
- 运营端 Prompt 管理增加四通道模板条目。
|
||
- 模板版本流程：DRAFT 编辑 -> 预览渲染 -> 发布 ACTIVE -> 回滚。
|
||
- `reportRenderer` 增加 `db` provider，并支持 provider 切换。
|
||
- 增加“模板变量提示面板”（减少占位符写错）。
|
||
- 增加模板指纹与版本审计：`templateVersion/templateFingerprint`。
|
||
|
||
交付物：
|
||
|
||
- 模板配置与发布流程可用
|
||
- 模板预览页（输入样例 JSON 即时渲染）
|
||
- 版本变更审计记录
|
||
- P1 灰度发布与稳定性报告
|
||
|
||
---
|
||
|
||
## 5. 验收标准（分阶段）
|
||
|
||
### 5.1 P0 功能验收（快速上线门槛）
|
||
|
||
1. 四通道都能产出 `rendered_report_text`，并用于前端展示与导出。
|
||
2. JSON 解析失败不影响最终展示（可读降级报告 + 告警）。
|
||
3. 默认模板可输出专家认可的报告结构（如 1/2/3/结论）。
|
||
4. 本阶段不依赖运营端模板配置即可上线。
|
||
|
||
### 5.2 P1 功能验收（配置化门槛）
|
||
|
||
1. 四通道可在运营端单独修改“展示模板”。
|
||
2. 运营发布后，新任务可命中 ACTIVE 模板并产出对应格式报告。
|
||
3. 模板从 A/B/C 改为 1/2/3/4，无需发版即可生效。
|
||
|
||
### 5.3 稳定性验收
|
||
|
||
1. 四通道 JSON 解析成功率 >= 99%（含修复链路）。
|
||
2. 模板渲染失败率 < 1%，且全部可回退到默认模板。
|
||
3. fallback 事件 100% 有日志与可追踪任务 ID。
|
||
|
||
### 5.4 可观测性验收
|
||
|
||
每次审稿必须可追溯：
|
||
|
||
- `promptVersion` / `promptFingerprint`
|
||
- `templateVersion` / `templateFingerprint`（P1 生效）
|
||
- `isDraft` / `render_fallback` / `protocol_repair_used`
|
||
|
||
---
|
||
|
||
## 6. 关键风险与应对
|
||
|
||
| 风险 | 影响 | 等级 | 应对 |
|
||
|---|---|---|---|
|
||
| 模板变量拼写错误导致渲染失败 | 报告显示异常 | 高 | P0 仅默认模板规避；P1 增加变量白名单 + 预览 + 默认模板降级 |
|
||
| 多模型结构化能力差异 | JSON 不稳定 | 高 | 统一 schema 校验 + repair + 明确模型兼容矩阵 |
|
||
| 历史任务缺少展示轨字段 | 页面兼容风险 | 中 | 前端双读逻辑（新字段优先，旧字段兜底） |
|
||
| 运营频繁发布造成“版本感知混乱” | 排障困难 | 中 | 强制记录版本指纹并在任务详情可见 |
|
||
|
||
---
|
||
|
||
## 7. 回滚策略
|
||
|
||
1. 模板回滚：P0 使用代码版本回滚，P1 支持运营端一键回滚到上一 ACTIVE 版本。
|
||
2. 服务回滚：保留旧展示拼装逻辑，Feature Flag 控制新渲染链路。
|
||
3. 故障兜底：渲染失败自动走默认模板，不阻塞任务完成状态。
|
||
4. 数据回滚：不删除结构化结果，仅切换展示来源。
|
||
|
||
---
|
||
|
||
## 8. 任务拆解（可直接进入排期）
|
||
|
||
### 后端（P0 先做）
|
||
|
||
- [ ] 新增 `reportRenderer` 服务（代码默认模板）
|
||
- [ ] 四通道接入模板渲染与降级日志
|
||
- [ ] 任务结果结构新增 `rendered_report_text`（含兼容）
|
||
- [ ] 增加 `promptVersion/promptFingerprint/render_fallback` 日志
|
||
- [ ] 预留模板 provider 扩展接口（`code` -> `db`）
|
||
|
||
### 前端（P0 先做）
|
||
|
||
- [ ] 任务详情优先展示 `rendered_report_text`
|
||
- [ ] 导出链路切换至展示轨
|
||
- [ ] 旧数据兼容兜底视图
|
||
|
||
### 后端/前端（P1 再做）
|
||
|
||
- [ ] 模板配置页支持预览与变量提示
|
||
- [ ] 接入模板版本发布/回滚流程
|
||
- [ ] 版本信息可视化（可选：调试面板）
|
||
|
||
### QA/运维
|
||
|
||
- [ ] 四通道回归测试用例补齐
|
||
- [ ] 模板异常、fallback、回滚演练
|
||
- [ ] 上线检查清单与告警看板更新
|
||
|
||
---
|
||
|
||
## 9. 里程碑
|
||
|
||
- M1（Week 1 结束）：P0 上线，四通道默认模板渲染可用，前端/导出展示轨打通。
|
||
- M2（Week 2 结束）：P1 配置化开发完成并进入灰度。
|
||
- M3（Week 3 结束）：P1 稳定上线，模板发布/回滚流程可用。
|
||
|
||
---
|
||
|
||
## 10. 版本记录
|
||
|
||
| 日期 | 版本 | 说明 |
|
||
|---|---|---|
|
||
| 2026-03-13 | v1.0 | 首版计划，确立“结构化评估 + 动态模板展示”双轨架构 |
|
||
| 2026-03-13 | v1.1 | 调整为“P0 硬编码默认模板快速上线 + P1 模板配置化增强”两阶段策略 |
|
||
|