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
67 lines
6.4 KiB
Markdown
67 lines
6.4 KiB
Markdown
# **RVW V4.0 智能审稿 SaaS 开发计划 \- 架构与工程审查报告**
|
||
|
||
**审查目标：** 评估 V1.0 版开发计划的技术可行性，识别潜在的架构漏洞、数据迁移风险及开发体验（DX）阻塞点。
|
||
|
||
**架构前提变更：** 确认 MVP 阶段为节约泛域名 SSL 证书成本，采用 **URL 路径隔离 (review.xunzhengyixue.com/jtim)** 方案。 **审查结论：** 整体架构设计优秀，但在**历史数据迁移、长耗时接口设计、以及路径路由下的静态资源加载**等方面存在 6 个具体的工程盲区，需在执行前修正。
|
||
|
||
## **🔴 核心高风险项 (P0级 \- 影响系统稳定与上线)**
|
||
|
||
### **1\. 历史数据迁移盲区：review\_tasks 增加 tenantId 会导致现网报错**
|
||
|
||
* **计划现状**：任务 1.2 提出给现有的 review\_tasks 表添加 tenant\_id 字段，并设为外键。
|
||
* **风险点**：线上生产环境（RDS）中已经存在大量 V3.0 的历史审稿任务。如果在 Prisma 中直接增加强制（Required）关联的 tenantId 字段，**Prisma Migrate 将会报错并中断**，因为历史数据该字段为空，违反了非空和外键约束。
|
||
* **修正建议**：
|
||
在 Phase 1 的数据库改造中，必须明确两步走的迁移策略：
|
||
1. 先在 platform\_schema.tenants 中初始化一个“默认临床主站租户”（如 tenant-default-yanjiu）。
|
||
2. 编写自定义的数据迁移脚本（Data Migration Script），在添加 tenant\_id 列后，将所有历史 review\_tasks 的 tenant\_id 刷为这个默认租户的 ID，最后再设置外键非空约束。
|
||
|
||
### **2\. 接口超时风险：退修信生成（任务 3.7）采用了同步阻塞设计**
|
||
|
||
* **计划现状**：任务 3.7 设计的接口 POST /api/v2/rvw/tasks/:id/revision-letter 是一个同步接口，直接返回 letterContent 和 wordFileUrl。
|
||
* **风险点**：组装数十个问题并请求大模型生成一封高质量、排版精美的退修信，耗时极易超过阿里云 SAE 网关的 **60秒超时限制**。如果让前端一直 loading 等待，极易出现 504 Gateway Timeout。
|
||
* **修正建议**：
|
||
鉴于你们在 ASL Deep Research V2.0 中已经成功应用了 SSE 流式架构，强烈建议将退修信生成改为：
|
||
* **方案 A（流式推荐）**：前端调用 SSE 接口，打字机式实时渲染退修信，生成完毕后再通过另一个接口触发 Word 文件上传并获取 URL。
|
||
* **方案 B（异步）**：复用现有的 pg-boss 队列，前端轮询任务状态（但退修信字数不多，方案 A 体验更好）。
|
||
|
||
## **🟡 中风险项 (P1级 \- 影响开发体验与业务闭环)**
|
||
|
||
### **3\. 【新增架构风险】前端静态资源404与Nginx刷新白屏风险**
|
||
|
||
* **计划现状**：MVP 架构已调整为 review.xunzhengyixue.com/:tenantId 路径隔离。
|
||
* **风险点**：
|
||
1. **静态资源 404**：如果前端打包配置使用的是相对路径（./），用户访问 /jtim 时，浏览器会向 /jtim/assets/... 错误地请求 JS/CSS 文件，导致全站白屏。
|
||
2. **Nginx 刷新 404**：用户在 /jtim/dashboard 页面直接刷新浏览器时，Nginx 会试图寻找服务器上的真实物理目录，找不到即报 404。
|
||
* **修正建议**：
|
||
* **前端组**：打包配置（Vite/Webpack）中的 base 或 publicPath 必须强制设置为绝对根路径 /。
|
||
* **运维组**：部署前端镜像的 nginx.conf 中，必须配置 try\_files $uri $uri/ /index.html; 以支持单页应用（SPA）的 History 路由回退。
|
||
|
||
### **4\. 业务闭环缺失：谁把“责编”拉进特定的租户？**
|
||
|
||
* **计划现状**：计划涵盖了数据隔离和 ADMIN 配置，但忽略了“用户-租户绑定（User-Tenant Binding）”的操作入口。
|
||
* **风险点**：当我们把 review.xunzhengyixue.com/jtim 交付给客户时，JTIM 的编辑登录后，系统如何知道他属于 JTIM？如果他不在 tenant\_members 表里，他依然会看到空数据或 403。
|
||
* **修正建议**：
|
||
系统状态文档显示已有 platform\_schema.tenant\_members 表和用户管理 API。需要在 Phase 2 的任务中补充明确：**内部超管通过 ADMIN 端现有的【用户管理 / 租户成员管理】界面，预先将对应的医生账号添加到指定的期刊租户中，并赋予 RVW 模块权限**。这不需要新开发，但必须列入交付 SOP 流程。
|
||
|
||
### **5\. 灾难级配置风险：Handlebars 缺少“实时预览”功能（任务 2.2）**
|
||
|
||
* **计划现状**：ADMIN 端的 Panel B 提供了一个供运营人员编辑 Handlebars 模板的文本区。
|
||
* **风险点**：如果运营人员不小心写错了语法（例如少写了一个 }），或者引用了错误的变量。由于没有预览功能，必须去前台上传一篇真实的 PDF，等待 5 分钟 LLM 分析完，在最后一步渲染报告时系统才会崩溃。这会导致极高的配置试错成本。
|
||
* **修正建议**：
|
||
强烈建议在任务 2.2 的 Handlebars 编辑器旁，复用你们在 ADMIN Phase 3.5.4 已经实现的\*\*“测试渲染 (Test Render)”\*\*功能。提供一份 Mock 好的完整 system\_metrics JSON 假数据，运营人员点击“预览”按钮，即可立刻在右侧看到 Markdown 报告的渲染效果，确保语法 100% 正确后再保存。
|
||
|
||
## **🟢 细节优化项 (P2级 \- 架构规范对齐)**
|
||
|
||
### **6\. 后端鉴权上下文提取方式需明确 (适应路径隔离)**
|
||
|
||
* **计划现状**：由子域名切换到了 URL 路径隔离。
|
||
* **风险点**：后端无法再通过请求头中的 Origin 或 Host 隐式判断当前用户正在访问哪个租户的工作台。
|
||
* **修正建议**： 明确开发规范：前端在使用 Axios 发起对 RVW 模块的业务 API 请求时，必须在 Header 中显式携带 x-tenant-id（从前端路由 :tenantId 中获取）。后端 auth.middleware.ts 统一从 Header 获取上下文，进行防越权校验。
|
||
|
||
## **🎯 总结与建议行动**
|
||
|
||
这份开发计划总体可以直接执行，但建议在启动会（Kick-off）上，让技术负责人将以上 6 点更新进原有的 Markdown 计划中：
|
||
|
||
1. **后端/DBA**：确认 review\_tasks 的平滑迁移 SQL 脚本。
|
||
2. **后端**：将退修信接口（任务 3.7）重构为 SSE 流式响应，并在鉴权中间件增加 x-tenant-id 解析。
|
||
3. **前端 & 运维**：死守前端打包的 base: '/' 设置与 Nginx try\_files 配置，确保路径路由不白屏；并在 ADMIN 增加模板预览按钮。 |