AIclinicalresearch/docs/05-部署文档/03-待部署变更清单.md

待部署变更清单

用途: 开发过程中实时记录所有待部署的变更，下次部署时按此清单逐项执行
维护规则: 每次修改 Schema / 新增依赖 / 改配置时，立即在此文档追加记录
Cursor Rule: .cursor/rules/deployment-change-tracking.mdc 会自动提醒
最后清零: 2026-03-10（0310 部署完成后清零）
本次变更: 已新增待部署项（2026-03-11，含 Agent 严格分步执行模式）

---

当前待部署变更

⚠️ 下次部署前，逐项检查此清单。部署完成后将已部署项移到「历史」区域并清零。

数据库变更

#	变更内容	迁移文件	优先级	备注
DB-1	SSA Agent 执行记录新增分步执行与种子审计字段（step_results/current_step/seed_audit）	20260311_add_ssa_agent_step_seed_fields	高	按数据库规范生成；Shadow DB 失败后采用降级流程产出 SQL，并已人工收敛为仅本次字段变更
DB-2	RVW V4.0：新增 platform_schema.tenant_rvw_configs 表（每期刊独立审稿配置，含4维提示词+Handlebars模板）	20260314_add_tenant_rvw_configs	高	⚠️ 部署前无需前置条件；使用降级流程手动创建迁移SQL，需执行 prisma migrate resolve --applied 20260314_add_tenant_rvw_configs 标记为已应用
DB-3	RVW V4.0：rvw_schema.review_tasks 新增 tenant_id 字段 + 索引（历史数据平滑回填两步走）	20260314_add_tenant_id_to_review_tasks	高	⚠️ 部署前必须先确认 platform_schema.tenants 中存在 code='yanjiu' 的主站默认租户；迁移会自动将历史记录回填为该租户ID；需执行 prisma migrate resolve --applied 20260314_add_tenant_id_to_review_tasks 标记为已应用
DB-4	RVW V4.0：期刊配置中心 MVP 一次性补齐字段（tenants 新增期刊字段；tenant_rvw_configs 升级为 4 维 Prompt+Template；TenantType 新增 JOURNAL）	20260315_journal_config_center_mvp	高	⚠️ prisma migrate dev 因历史 shadow DB 迁移失败触发降级流程，已按规范收敛手工 SQL；部署后执行 prisma migrate resolve --applied 20260315_journal_config_center_mvp

后端变更 (Node.js)

#	变更内容	涉及文件	需要操作	备注
BE-1	SSA Agent 执行链路增加确定性种子注入、错误分类、seed 审计透传 + 分步执行事件（step_*）	backend/src/modules/ssa/services/ChatHandlerService.ts, backend/src/modules/ssa/services/CodeRunnerService.ts, backend/src/modules/ssa/services/AgentCoderService.ts	重新构建镜像	与 DB-1 配套上线，确保执行可复现与可追溯
BE-2	新增 Agent 计划参数编辑接口 PATCH /api/v1/ssa/agent-executions/:executionId/plan-params（复用参数约束配置）	backend/src/modules/ssa/routes/agent-execution.routes.ts, backend/src/modules/ssa/index.ts	重新构建镜像	Phase 5A.5 后端入口，限制 plan_pending 状态可编辑
BE-3	Agent 切换为严格分步模式：confirm_plan 不生成整段代码，执行阶段统一按步骤生成 + 失败后依赖短路跳过后续步骤	backend/src/modules/ssa/services/ChatHandlerService.ts	重新构建镜像	修复“第3步失败仍尝试第4步”问题，降低无效重试与误导性结果
BE-4	R 代码语法修复器纠正 } else 处理策略，避免引入 unexpected 'else'	backend/src/modules/ssa/services/CodeRunnerService.ts	重新构建镜像	修复线上语法错误噪声，减少重试失败
BE-5	RVW 审稿通道改造：4 通道 Prompt 动静分离（业务提示词可编辑 + 系统协议固化）+ 方法学/稿约 JSON 结构化修复兜底 + DataForensics 默认切换为 LLM-only（规则验证默认关闭）	backend/src/modules/rvw/services/promptProtocols.ts, backend/src/modules/rvw/services/editorialService.ts, backend/src/modules/rvw/services/methodologyService.ts, backend/src/modules/rvw/services/clinicalService.ts, backend/src/modules/rvw/skills/library/DataForensicsSkill.ts, backend/src/modules/rvw/skills/core/types.ts, backend/src/common/document/ExtractionClient.ts, backend/src/common/prompt/prompt.fallbacks.ts	重新构建镜像	解决运营端改 Prompt 导致 JSON 解析失败；数据侦探默认仅“表格提取+LLM判断”，规则代码保留可回切
BE-6	RVW V4.0 Phase 1：Prisma Schema 新增 TenantRvwConfig 模型 + ReviewTask.tenantId 字段 + RVW租户中间件（rvwTenantMiddleware，slug到UUID解析+tenant_members校验+缓存）+ FastifyRequest 扩展 tenantId/tenant 字段	backend/prisma/schema.prisma, backend/src/modules/rvw/middleware/rvwTenantMiddleware.ts, backend/src/common/auth/auth.middleware.ts	重新构建镜像 + 执行 DB-2/DB-3 迁移	与 DB-2/DB-3 配套上线；Prisma Client 已重新生成
BE-7	RVW V4.0 Phase 2：RVW Config CRUD API（GET/PUT /api/admin/tenants/:id/rvw-config）+ Handlebars 渲染引擎（Zod 校验 + 默认模板）+ SkillExecutor 按租户装配 Hybrid Prompt	backend/src/modules/admin/rvw-config/rvwConfigController.ts, backend/src/modules/admin/rvw-config/rvwConfigService.ts, backend/src/modules/admin/rvw-config/rvwConfigRoutes.ts, backend/src/modules/rvw/services/rvwReportRenderer.ts, backend/src/modules/rvw/workers/reviewWorker.ts, backend/src/index.ts	重新构建镜像	与 BE-6/DB-2/DB-3 配套上线
BE-8	RVW V4.0 Phase 3：后端 CORS 配置新增 x-tenant-id 白名单（多租户 Header 跨域支持）	backend/src/index.ts	重新构建镜像	⚠️ 缺少此项会导致浏览器预检请求拦截 x-tenant-id，整个多租户功能失效
BE-9	RVW V4.0 Phase 4（期刊配置中心 MVP）：新增 /api/admin/journal-configs 专用 API；租户模型扩展期刊字段；RVW 执行链路接入最小配置适配（tenantCustom ?? systemDefault），Editorial 支持 zh/en 基线路由；创建/更新为 JOURNAL 时自动兜底开通 RVW 模块	backend/src/modules/admin/journal-config/*, backend/src/modules/admin/services/tenantService.ts, backend/src/modules/admin/types/tenant.types.ts, backend/src/modules/admin/rvw-config/*, backend/src/modules/rvw/workers/reviewWorker.ts, backend/src/modules/rvw/skills/library/*, backend/src/modules/rvw/services/editorialService.ts, backend/src/modules/rvw/services/clinicalService.ts, backend/src/common/prompt/prompt.fallbacks.ts, backend/src/index.ts	重新构建镜像 + 执行 DB-4 迁移	与 FE-7 联动上线，满足「独立一级菜单 + 中英文基线 + 继承/覆盖」MVP 范围，并避免新期刊用户登录后无 RVW 模块权限

前端变更

#	变更内容	涉及文件	需要操作	备注
FE-1	Agent 通道接入 step_* SSE 事件并展示分步执行状态（兼容旧 code_* 事件）	frontend-v2/src/modules/ssa/hooks/useSSAChat.ts, frontend-v2/src/modules/ssa/components/AgentCodePanel.tsx, frontend-v2/src/modules/ssa/types/index.ts, frontend-v2/src/modules/ssa/stores/ssaStore.ts	重新构建镜像	右侧工作区可见每步状态/错误/耗时，便于排障
FE-2	Agent 计划阶段复用 QPER 变量编辑控件（单变量/多变量）并接入保存、确认前自动保存	frontend-v2/src/modules/ssa/components/AgentCodePanel.tsx, frontend-v2/src/modules/ssa/components/WorkflowTimeline.tsx, frontend-v2/src/modules/ssa/components/SSAWorkspacePane.tsx	重新构建镜像	对接 PATCH /agent-executions/:executionId/plan-params，实现 5A.5 前后端闭环
FE-3	Agent 工作区增强：在分步状态下可展开查看每步已生成结果（reportBlocks），并兼容严格分步模式下的 code_pending 空代码预览	frontend-v2/src/modules/ssa/components/AgentCodePanel.tsx, frontend-v2/src/modules/ssa/hooks/useSSAChat.ts	重新构建镜像	修复“有结果但代码下方不可见”与状态显示误导问题
FE-4	RVW V4.0 Phase 2：TenantDetailPage 新增「智能审稿配置」Tab（4 Panel：稿约规范占位 / 方法学Prompt+Handlebars模板 / 数据验证深度L1-L3 / 临床FINER权重）+ tenantApi 新增 fetchRvwConfig/saveRvwConfig	frontend-v2/src/pages/admin/tenants/TenantDetailPage.tsx, frontend-v2/src/pages/admin/tenants/api/tenantApi.ts	重新构建镜像	与 BE-7/DB-2/DB-3 配套上线
FE-5	RVW V4.0 Phase 3：新增 TenantPortalLayout 极简期刊门户布局 + App.tsx 新增 /:tenantSlug/rvw/* 路由（期刊专属 URL）+ LoginPage.tsx 修复跳转逻辑（读取 ?redirect= 查询参数 + 租户默认落地页 /:tenantSlug/rvw）	frontend-v2/src/framework/layout/TenantPortalLayout.tsx, frontend-v2/src/App.tsx, frontend-v2/src/pages/LoginPage.tsx	重新构建镜像	与 BE-6/BE-7/BE-8 配套上线；实现期刊租户完整访问路径 /jtim → /jtim/rvw
FE-6	RVW V4.0 租户门户体验收敛：上传按钮稳定触发（原生文件选择器 API + input 回退）、执行审稿后跳转旧版过程页（复用 TaskDetail）、列表四维状态图标修复（完成态正确显示绿勾/警告）	frontend-v2/src/modules/rvw/pages/TenantDashboard.tsx, frontend-v2/src/modules/rvw/pages/TenantTaskDetail.tsx	重新构建镜像	已本地联调通过；上线后重点回归 /:tenant/login -> /:tenant/rvw 主流程
FE-7	RVW V4.0 期刊配置中心 MVP：ADMIN 新增独立一级菜单“期刊配置中心”，新增列表页/详情页（基础信息 + 4 维审稿配置），并对齐新 API DTO（journalLanguage、editorialBaseStandard、Prompt/Handlebars 字段）	frontend-v2/src/framework/layout/AdminLayout.tsx, frontend-v2/src/App.tsx, frontend-v2/src/pages/admin/journal-configs/*, frontend-v2/src/pages/admin/tenants/api/tenantApi.ts, frontend-v2/src/pages/admin/tenants/TenantDetailPage.tsx	重新构建镜像	与 BE-9/DB-4 配套上线；MVP 阶段先跑通配置闭环，品牌视觉字段先存储后逐步渲染
FE-8	登录路径策略统一为单一路径：仅保留 /:tenantCode/login，未登录重定向与退出登录统一 /:tenant/login，开发/生产同路径仅域名不同	frontend-v2/src/App.tsx, frontend-v2/src/framework/router/RouteGuard.tsx, frontend-v2/src/framework/layout/TenantPortalLayout.tsx, frontend-v2/src/pages/TenantLoginPage.tsx, frontend-v2/src/pages/LoginPage.tsx	重新构建镜像	对齐生产目标链接 review.xunzhengyixue.com/test-qikan01；不再保留 /t/:tenantCode/login 路径，需同步更新测试文档/书签

Python 微服务变更

#	变更内容	涉及文件	需要操作	备注
PY-1	Forensics API 新增 EXTRACT_ONLY 模式并默认仅提取表格（不执行 L1/L2 规则校验）	extraction_service/forensics/api.py, extraction_service/forensics/types.py	重新构建镜像	与后端 RVW LLM-only 路径配套，避免规则与 LLM 双轨冲突

R 统计引擎变更

#	变更内容	涉及文件	需要操作	备注
R-1	execute-code 端点升级为语法+安全双层预检，新增 E_SECURITY 与运行时高危函数拦截	r-statistics-service/plumber.R	重新构建镜像	阻断 system/eval/source/file.remove/setwd 等风险调用

环境变量 / 配置变更

#	变更内容	服务	变量名	备注
ENV-1	新增 RVW 数据侦探规则引擎开关（默认关闭）	nodejs-backend-test / nodejs-backend-prod	RVW_FORENSICS_RULES_ENABLED=false	false=仅表格提取+LLM判断（推荐）；如需恢复规则验证可设为 true

基础设施变更

#	变更内容	范围	备注
INF-1	前端 Nginx 增加 SPA 深链回退（try_files $uri /index.html），并确保 /api/ 路由优先反代后端（不能被 index.html 吞掉）	frontend-nginx-service / ingress	⚠️ 否则直接访问 review.xunzhengyixue.com/test-qikan01 或 .../test-qikan01/login 会 404；部署后需在无缓存浏览器验证
INF-2	前端 Docker 构建与发布注意：确认镜像内 Nginx 配置已包含深链规则、并清理旧静态资源缓存（CDN/浏览器）后再灰度	frontend-v2 build/deploy pipeline	建议发布后先执行硬刷新（Ctrl+F5）与隐身窗口验证，避免旧 bundle 缓存导致仍跳旧路径
INF-3	SAE 接入 RVW 多租户链路：review.xunzhengyixue.com 仅负责流量入口，实际租户/模块判定由应用完成（/:tenantCode/login、/:tenantSlug/rvw + x-tenant-id + tenant_members + tenant_modules）	frontend SAE + backend SAE + ingress/SLB	⚠️ SAE 不会自动“识别审稿模块”；必须保证前端路由命中、/api 正确转发后端、后端开启 RVW 路由与租户中间件；并确认租户已开通 RVW 且用户在该租户下有成员关系
INF-4	前端镜像构建发布标准流程（生产）：安装依赖→构建 frontend-v2/dist→打包 Nginx 镜像→推送镜像仓库→SAE 更新版本→灰度验证→全量发布	frontend-v2 build/deploy pipeline	推荐命令：npm ci && npm run build（在 frontend-v2 目录）；镜像发布后必须验证 review.xunzhengyixue.com/{tenant}/login、/{tenant}/rvw、/api/v1/auth/verification-code 三条链路可用

---

上线后快速验收（运维执行）

目标：确认 review.xunzhengyixue.com 已真正接入 RVW 租户审稿链路，而非仅页面可访问。

1. 前端深链验证（无缓存）

   • 隐身窗口访问：https://review.xunzhengyixue.com/{tenantCode}/login
   • 登录后应进入：https://review.xunzhengyixue.com/{tenantCode}/rvw
   • 直接刷新 /{tenantCode}/rvw 不应 404（验证 Nginx SPA 回退生效）

2. API 代理验证

   • 在浏览器 Network 确认 /api/v1/auth/*、/api/rvw/* 均返回后端响应（非前端静态 200 HTML）
   • 若返回 HTML 或 404，优先检查 ingress/Nginx /api 反代优先级

3. 租户权限验证（业务可用性）

   • 运营端确认目标租户已开通 RVW 模块（tenant_modules）
   • 运营端确认用户已分配到该租户（tenant_members）
   • 若登录后提示“暂无访问智能审稿模块权限”，先查租户模块与用户模块覆盖关系

4. 验证码链路验证

   • 验证码发送成功 + 倒计时启动 + 登录成功 需完整通过
   • 弱网场景若偶发失败，先排查网络/网关，再看后端日志；前端已增加“发送中”防重入保护

---

记录模板

开发时发现需要部署的变更，复制下方模板追加到对应区域：

<!-- 数据库变更 -->
| DB-N | 简述变更 | `迁移文件名` | 高/中/低 | 备注 |

<!-- 后端变更 -->
| BE-N | 简述变更 | `file.ts` | 重新构建镜像 | 备注 |

<!-- 前端变更 -->
| FE-N | 简述变更 | `Component.tsx` | 重新构建镜像 | 备注 |

<!-- Python 变更 -->
| PY-N | 简述变更 | `requirements-prod.txt` | 重新构建镜像 | 备注 |

<!-- R 变更 -->
| R-N | 简述变更 | `tool.R` | 重新构建镜像 | 备注 |

<!-- 环境变量 -->
| ENV-N | 简述变更 | nodejs-backend-test | `VAR_NAME=value` | 备注 |

---

历史（已部署，仅供追溯）

0310 部署已清零项

#	变更内容	部署日期	结果
DB	新增 user_permissions 表（20260309_add_user_permissions_table）	2026-03-10	✅
DB	Seed 权限 ops:user-ops	2026-03-10	✅
BE	后端 v2.10 → v2.11（用户直授权限、运营埋点与看板、AIA 附件与 RVW 提速等）	2026-03-10	✅
FE	前端 v2.7 → v2.8（运营端权限入口、用户运营权限开关、看板增强、AIA/RVW 体验优化）	2026-03-10	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.173.110	2026-03-10	✅

0309 二次部署已清零项

#	变更内容	部署日期	结果
DB	AIA 新增 attachments 持久化表（20260309_add_aia_attachments_persistence）	2026-03-09	✅
R	v1.0.2 → v1.0.5（包诊断接口、构建期缺包校验、错误映射修复、`%		%` 修复）
BE	v2.9 → v2.10（SSE/优雅停机/AIA附件/短信能力等变更）	2026-03-09	✅
FE	v2.6 → v2.7（SSE 代理与友好重试体验优化）	2026-03-09	✅
ENV	nodejs-backend-test: R_SERVICE_URL → http://172.17.197.26:8080	2026-03-09	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.173.109	2026-03-09	✅

0309 部署已清零项

#	变更内容	部署日期	结果
DB	4 个 Prisma 迁移（error_details + eQuery 去重 + agent 默认 + token_version）	2026-03-09	✅
DB	3 个种子脚本（modules ASL_SR + RVW Prompt×2 + SSA Agent Prompt×2）	2026-03-09	✅
R	R 统计引擎 v1.0.1 → v1.0.2（execute-code + 错误处理 + AST 预检，3 项变更）	2026-03-09	✅
BE	Node.js v2.8 → v2.9（Deep Research V2 + RVW 4维 + SSA Agent + IIT 幂等 + 认证互踢，13 项变更）	2026-03-09	✅
FE	前端 v2.5 → v2.6（ASL 手风琴 + RVW 4Tab + SSA Agent UI + 全局心跳，10 项变更）	2026-03-09	✅
ENV	nodejs-backend-test: R_SERVICE_URL → http://172.17.197.22:8080	2026-03-09	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.173.108	2026-03-09	✅

0305 部署已清零项

#	变更内容	部署日期	结果
DB	modules 表 seed 更新（新增 RM、AIA_PROTOCOL，IIT→CRA质控）	2026-03-05	✅
BE	Node.js v2.4 → v2.6（登录踢人 + 权限体系 + SSA双通道 + 批量导入，9 项变更）	2026-03-05	✅
FE	前端 v2.0 → v2.3（ASL/AIA/PKB UI优化 + 权限适配 + 批量导入重构，11 项变更）	2026-03-05	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.197.36	2026-03-05	✅
DB	SSA 双通道：ssa_sessions 新增 execution_mode + ssa_agent_executions 表	2026-03-05	✅ 热修
BE	Node.js v2.6 → v2.7（bug 修复，基于测试反馈）	2026-03-05	✅ 二次部署
FE	前端 v2.3 → v2.4（bug 修复，基于测试反馈）	2026-03-05	✅ 二次部署
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.197.37	2026-03-05	✅ 二次部署
BE	Node.js v2.7 → v2.8（bug 修复）	2026-03-05	✅ 三次部署
FE	前端 v2.4 → v2.5（bug 修复）	2026-03-05	✅ 三次部署
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.173.106	2026-03-05	✅ 三次部署

0302 部署已清零项

#	变更内容	部署日期	结果
DB	6 个 Prisma 迁移（SSA 类型对齐 + IIT RBAC + is_demo + V3.1 QC 三批）	2026-03-02	✅
DB	新建 qc_field_status、qc_event_status 2 张表（84 → 86）	2026-03-02	✅
BE	Node.js v2.3 → v2.4（IIT V3.1 QC引擎全面升级，27 项变更）	2026-03-02	✅
FE	前端 v1.9 → v2.0（GCP 报表 + V3.1 前端，17 项变更）	2026-03-02	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.197.32	2026-03-02	✅

0227 部署已清零项

#	变更内容	部署日期	结果
DB	5 个业务迁移 + 1 个 drift patch	2026-02-27	✅
DB	SSA data_profile 列补充	2026-02-27	✅ 线上热修
DB	RVW review_tasks 8 列补充	2026-02-27	✅ 线上热修
BE	Node.js v1.7 → v2.2（SSA/ASL/RVW/IIT 全模块更新）	2026-02-27	✅
BE	Dockerfile 增加 JSON 配置文件拷贝	2026-02-27	✅
FE	前端 v1.3 → v1.8（react-markdown, nginx 配置更新）	2026-02-27	✅
PY	Python v1.1 → v1.2（新增 scipy）	2026-02-27	✅
R	R 统计引擎 v1.0.1 全新部署	2026-02-27	✅
ENV	nodejs-backend-test: R_STATISTICS_SERVICE_URL 等	2026-02-27	✅
ENV	frontend-nginx-service: BACKEND_SERVICE_HOST 更新	2026-02-27	✅