HaHafeng
16179e16ca
Implement RVW V4.0 tenant-aware backend/frontend flow with tenant routing, config APIs, and full portal UX updates. Sync system/RVW/deployment docs to capture verified upload-review-report workflow and next-step admin configuration work. Made-with: Cursor
73 lines
5.3 KiB
Markdown
73 lines
5.3 KiB
Markdown
# **RVW V4.0 智能审稿 SaaS：核心技术难点与稳定性防范指南**
|
||
|
||
**文档受众：** 后端研发、前端研发、AI 算法工程师
|
||
|
||
**文档目的：** 针对 RVW V4.0 (期刊SaaS版) 引入的“混合 Schema 双轨输出”与“SSO 统一通行证”架构，提前识别系统稳定性风险，并确立工程防范底线。
|
||
|
||
## **⚠️ 难点一：Hybrid Schema 模式下的 JSON 转义风暴**
|
||
|
||
**【风险描述】**
|
||
|
||
我们在架构中设计了“混合 Schema”模式，要求 LLM 在输出结构化 system\_metrics 的同时，在一个名为 expert\_report\_markdown 的 JSON 字段内输出几千字的自然语言长文本。
|
||
|
||
大模型在生成含有大量回车换行（\\n）、双引号（"）、特殊反斜杠（\\）的医学长文本时，极易发生**转义字符遗漏**。几千字的文本中只要漏掉一个转义符，后端的 JSON.parse() 就会发生致命崩溃。
|
||
|
||
**【开发防范方案】**
|
||
|
||
1. **API 层强约束 (Structured Outputs)**：
|
||
* 彻底摒弃在 Prompt 中软性要求 JSON。必须在调用 DeepSeek-V3 / GPT-4o 时，在 API 传参层强制开启 response\_format: { type: "json\_object" } 或直接传入严格的 JSON Schema。
|
||
2. **容错解析器 (Robust Parser)**：
|
||
* 不要直接使用原生的 JSON.parse。建议引入容错率更高的解析库（如 jsonrepair 或通过正则预处理），在解析失败时能自动修复常见的截断或转义错误。
|
||
3. **拥抱 Partial 容灾**：
|
||
* 即使 JSON 彻底损坏，**决不允许让整个审稿流程（4个 Skill 并行）全部挂掉**。必须复用 V3.0 中已成熟的 Promise.allSettled 和 partial\_completed 机制，将解析失败的 Skill 优雅降级并记录至 error\_details。
|
||
|
||
## **⚠️ 难点二：Prompt 与 Handlebars 模板的隐性强耦合**
|
||
|
||
**【风险描述】**
|
||
|
||
内部实施人员在 ADMIN 端配置时，需要手写“评判标准 (Prompt)”和“展示模板 (Handlebars)”。
|
||
|
||
* **问题 A (变量错位)**：Prompt 要求大模型输出 5 个字段，但 Handlebars 模板里写了接收 6 个字段的占位符（如 {{missing\_field}}）。
|
||
* **问题 B (AI 幻觉断层)**：Handlebars 模板严格依赖循环 {{\#each checkpoints}}，期望渲染 20 项。但由于大模型“注意力稀释”，只输出了 18 项，导致生成的报告在视觉排版上出现错位或断层。
|
||
|
||
**【开发防范方案】**
|
||
|
||
1. **数据 Schema 校验防线 (Zod)**：
|
||
* 在 LLM 返回数据交由 Handlebars 渲染之前，必须经过 Zod 进行 Schema 强校验。对于缺失的非致命字段，给予默认值（Fallback value）填充。
|
||
2. **防御性模板渲染 (Defensive Templating)**：
|
||
* 在向运营人员开放的 Handlebars 模板规范中，强制推行防御性语法。例如，大量使用 {{\#if field}} ... {{else}} ... {{/if}}，避免因字段缺失导致渲染报错或出现大片空白。
|
||
|
||
## **⚠️ 难点三：长上下文与重度推理导致的超时灾难 (Timeout)**
|
||
|
||
**【风险描述】**
|
||
|
||
审稿业务是典型的“长上下文（数十页医学 PDF，可能超 2 万 Token）+ 复杂推理（20项方法学规则）”场景。
|
||
|
||
结合现有的云原生架构（阿里云 SAE 部署），Serverless 网关通常存在 60 秒的请求超时限制。LLM 在处理超长文献和生成千字报告时，单次请求耗时极易突破 60\~120 秒，导致前端直接报 504 Gateway Timeout。
|
||
|
||
**【开发防范方案】**
|
||
|
||
1. **异步队列为王 (Platform-Only 架构复用)**：
|
||
* 严禁在 HTTP 请求的生命周期内同步等待大模型返回。必须将审稿任务投递至平台层的 pg-boss 队列 (platform\_schema.job)。
|
||
2. **状态轮询与 SSE 进度流**：
|
||
* 前端通过发起 GET /api/v2/rvw/tasks/:id/status 进行轮询，或直接接入 SSE (Server-Sent Events) 接收后台 reviewWorker 实时推流的执行进度。
|
||
3. **Skill 内部并发 (Map-Reduce)**：
|
||
* 针对最耗时的 MethodologySkill，后端可考虑将其拆分为“科研设计”、“统计学描述”、“结果评估”三个子请求，向 LLM 发起内部并发，并在汇总后一起喂给 Handlebars 渲染，以空间（Token 成本）换取时间。
|
||
|
||
## **⚠️ 难点四：SSO 统一账号下的多租户越权风险**
|
||
|
||
**【风险描述】**
|
||
|
||
为了实现医生与专家在“主站”与“期刊 SaaS 子域名”间的无缝漫游，我们采取了“统一底层 users 表”的架构。
|
||
|
||
这种架构最大的安全隐患是**数据越权（Data Leakage）**。如果 API 接口没有严格限制上下文，A 期刊（JTIM）的责编可能会通过修改请求参数，查看到 B 期刊（CMJ）的待审稿件库。
|
||
|
||
**【开发防范方案】**
|
||
|
||
1. **JWT 强制注入上下文**：
|
||
* 登录签发 Token 时，必须将当前的 tenantId 压入 JWT Payload。
|
||
2. **Prisma 拦截器 / RLS (Row-Level Security)**：
|
||
* 在后端的 auth.middleware.ts 中提取 tenantId 后，**所有**涉及 RVW 模块的 Prisma 查询（findMany, update, delete 等），必须在 where 子句中强制挂载 tenantId: request.tenantId 的条件。
|
||
* 建议在开发规范中明确：禁止任何跳过 tenantId 校验的业务端裸查（除非是带有 ops:user-ops 权限的内部实施端操作）。
|
||
3. **路由鉴权守护**：
|
||
* 依赖现有的 requireModule 中间件，严格确保只有订阅了 RVW 模块的租户用户，才能访问对应的审稿数据。 |