# 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 模板配置化增强”两阶段策略 |