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

待部署变更清单

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

---

当前待部署变更

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

数据库变更

#	变更内容	迁移文件	优先级	备注
DB-1	modules 表 seed 新增 ASL_SR 模块（系统综述项目）	backend/scripts/seed-modules.js	高	部署后需执行 node scripts/seed-modules.js，并在运营管理端为目标用户/租户开通
DB-2	prompt_templates 表新增 RVW_DATA_VALIDATION + RVW_CLINICAL 两个 Prompt	backend/scripts/migrate-rvw-prompts.ts	高	部署后需执行 npx tsx scripts/migrate-rvw-prompts.ts，运营管理端可配置修改
DB-3	ReviewTask 表新增 error_details JSONB 字段（存储 Skill 级失败详情）	prisma/migrations/20260307_add_error_details_to_review_task/migration.sql	高	支持 partial_completed 状态，记录每个失败/超时 Skill 的名称和原因
DB-4	SSA execution_mode 默认值改为 agent + 已有 session 全部更新	prisma/migrations/20260308_default_agent_mode/migration.sql	高	ALTER DEFAULT + UPDATE 旧数据；QPER UI 入口已移除
DB-5	SSA Agent Prompt 种子数据（SSA_AGENT_PLANNER / SSA_AGENT_CODER）	prisma/seed-ssa-agent-prompts.ts	高	部署后执行 npx tsx prisma/seed-ssa-agent-prompts.ts；幂等可重复执行

后端变更 (Node.js)

#	变更内容	涉及文件	需要操作	备注
BE-1	Deep Research V2.0 新增历史列表 + 删除接口 + getTask 鉴权修复	deepResearchController.ts, routes/index.ts	重新构建镜像	GET /research/v2/tasks, DELETE /research/tasks/:taskId, getTask 增加 userId 校验
BE-2	SR 相关路由（projects/literatures/screening/fulltext-screening/extraction/charting/meta-analysis）增加 requireModule('ASL_SR') 中间件	asl/routes/index.ts, extraction/routes/index.ts, charting/routes/index.ts, meta-analysis/routes/index.ts	重新构建镜像	需先完成 DB-1 seed，否则无 ASL_SR 模块会 403
BE-3	Unifuncs DeepSearch API 从 S2 升级至 S3（新增 language: "zh"）	unifuncsSseClient.ts, unifuncsAsyncClient.ts	重新构建镜像	通过 UNIFUNCS_MODEL 环境变量控制，默认 s3，设为 s2 可降级
BE-4	RVW 数据验证增加 LLM 核查通道（DataForensicsSkill 增强）	DataForensicsSkill.ts, prompt.fallbacks.ts	重新构建镜像	规则验证完成后批量调用 LLM 核查所有表格，失败时降级为纯规则验证
BE-5	RVW 新增临床专业评估维度（ClinicalAssessmentSkill）	clinicalService.ts(新), ClinicalAssessmentSkill.ts(新), library/index.ts, profile.ts, utils.ts, reviewWorker.ts, reviewService.ts	重新构建镜像	新增 clinical Agent + Skill，存储在 contextData.clinicalReview
BE-6	RVW 稳定性增强：SkillExecutor Promise.allSettled + partial_completed 状态 + errorDetails	executor.ts, reviewWorker.ts, reviewService.ts, reviewController.ts, types/index.ts	重新构建镜像	并行 Skill 故障隔离，部分模块失败时仍返回成功模块结果，新增 partial_completed 任务状态
BE-7	DataForensicsSkill LLM 核查增加独立 60s 超时	DataForensicsSkill.ts	重新构建镜像	LLM 核查超时不阻塞整体 Skill，graceful 降级为纯规则验证
BE-8	SSA Agent 通道体验优化（方案 B 左右职责分离 + 10 项 Bug 修复）	ChatHandlerService.ts, AgentCoderService.ts, chat.routes.ts	重新构建镜像	视线牵引 Prompt + maxTokens 8000 + 重试流式生成 + consoleOutput 类型防御 + Prompt 铁律 + parseCode 健壮化
BE-9	Phase 5A：CoderAgent 防错护栏（4 项改动）	AgentCoderService.ts, TokenTruncationService.ts, chat.routes.ts	重新构建镜像	XML 标签提取 + 防御性编程 Prompt + 高保真 Schema 注入 + token 配额 2500 + 后端强制 Agent 模式
BE-10	SSA Agent 核心 Prompt 接入运营管理端（PlannerAgent + CoderAgent）	AgentPlannerService.ts, AgentCoderService.ts, prompt.fallbacks.ts	重新构建镜像	硬编码 → PromptService.get() 动态加载；三级容灾：DB → 缓存 → fallback；需先完成 DB-5

前端变更

#	变更内容	涉及文件	需要操作	备注
FE-1	ASL 左侧导航栏重构为互斥手风琴（Deep Research 历史记录 + SR 工具导航）	ASLLayout.tsx, asl-sidebar.css（新建）, DeepResearchPage.tsx, asl/index.tsx	重新构建镜像	Panel A: 智能文献检索历史；Panel B: 系统综述项目（5 工具）
FE-2	Deep Research 历史记录功能（API 客户端 + 类型定义 + URL 任务恢复）	asl/api/index.ts, types/deepResearch.ts, DeepResearchPage.tsx, asl/index.tsx	重新构建镜像	新增 listDeepResearchTasks / deleteDeepResearchTask API；新增 /research/deep/:taskId 路由
FE-3	Panel B SR 工具导航权限控制（hasModule('ASL_SR')）	ASLLayout.tsx, asl-sidebar.css	重新构建镜像	未开通时显示"请联系管理员开通"；已开通显示 5 个 SR 工具导航项
FE-4	RVW 数据验证报告增加 LLM 核查结果展示	ForensicsReport.tsx, rvw/types/index.ts	重新构建镜像	总览展示完整 LLM 报告，每个表格卡片展开后显示对应 AI 核查结果（Markdown）
FE-5	RVW 新增临床专业评估 Tab + Agent 选择项	ClinicalReport.tsx(新), AgentModal.tsx, TaskDetail.tsx, rvw/types/index.ts	重新构建镜像	共 4 个 Tab：稿约规范性/方法学/数据验证/临床评估；Word 导出包含临床评估章节
FE-6	RVW 前端支持 partial_completed 状态（部分完成）	TaskDetail.tsx, TaskTable.tsx, rvw/types/index.ts	重新构建镜像	琥珀色警告横幅展示失败模块详情，列表页显示"部分完成"标签，支持查看已完成模块的报告
FE-7	SSA Agent 通道体验优化（方案 B + 动态 UI）	AgentCodePanel.tsx, SSAChatPane.tsx, SSAWorkspacePane.tsx, SSACodeModal.tsx, useSSAChat.ts, ssaStore.ts, ssa.css	重新构建镜像	左右职责分离 + JWT 刷新 + 重试代码展示 + 错误信息展示 + 进度条同步 + 导出/查看代码按钮恢复 + ExecutingProgress 组件
FE-8	SSA 默认 Agent 模式 + 查看代码修复 + 分析历史卡片	SSAChatPane.tsx, SSAWorkspacePane.tsx, useSSAChat.ts, ssaStore.ts	重新构建镜像	移除 ModeToggle + 默认 agent + 查看代码走 Modal + 分析完成后对话插入可点击结果卡片 + ChatIntentType 扩展 system

Python 微服务变更

#	变更内容	涉及文件	需要操作	备注
—	暂无

R 统计引擎变更

#	变更内容	涉及文件	需要操作	备注
R-1	新增 POST /api/v1/execute-code 端点（Agent 通道任意 R 代码执行）	plumber.R	重新构建镜像	含超时 + 沙箱限制
R-2	Agent 结构化错误处理增强（20+ 模式匹配 + format_agent_error）	plumber.R, utils/error_codes.R	重新构建镜像	withCallingHandlers 捕获 warnings/messages + 行号提取 + 错误分类 + 修复建议
R-3	AST 语法预检（parse() 前置于 eval()）	plumber.R	重新构建镜像	语法错误秒级返回 E_SYNTAX + 行号 + 上下文代码，不进入沙箱执行

环境变量 / 配置变更

#	变更内容	服务	变量名	备注
ENV-1	Unifuncs 模型版本控制（可选，不配置则默认 s3）	nodejs-backend	UNIFUNCS_MODEL=s3	降级时改为 s2，无需重新部署代码

基础设施变更

#	变更内容	范围	备注
—	暂无

---

记录模板

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

<!-- 数据库变更 -->
| 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` | 备注 |

---

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

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	✅