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

待部署变更清单

用途: 开发过程中实时记录所有待部署的变更，下次部署时按此清单逐项执行
维护规则: 每次修改 Schema / 新增依赖 / 改配置时，立即在此文档追加记录
Cursor Rule: .cursor/rules/deployment-change-tracking.mdc 会自动提醒
最后清零: 2026-03-09（0309 二次部署完成后清零）
本次变更: 用户直授权限体系 + 运营埋点增强 + 运营看板 MAU/Token + AIA 附件格式优化（2026-03-10）

---

当前待部署变更

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

数据库变更

#	变更内容	迁移文件	优先级	备注
DB-1	新增 user_permissions 用户直授权限表	20260309_add_user_permissions_table	高	支持不依赖角色给单个用户授权（如 ops:user-ops），platform_schema 下，含外键和唯一约束
DB-2	Seed：permissions 表插入 ops:user-ops 记录	prisma/seed.ts 或手动 SQL	高	DB-1 之后执行；INSERT INTO platform_schema.permissions (code,name,description,module) VALUES ('ops:user-ops','用户运营','运营管理端用户运营视图权限','ops') ON CONFLICT (code) DO NOTHING;

后端变更 (Node.js)

#	变更内容	涉及文件	需要操作	备注
BE-1	认证链路支持用户直授权限合并	auth.service.ts, auth.middleware.ts	重新构建镜像	getUserPermissions 合并 role_permissions + user_permissions；requirePermission / requireAnyPermission 两级检查
BE-2	用户管理 API 新增直授权限读写接口	userController.ts, userService.ts, userRoutes.ts	重新构建镜像	GET/PUT /api/admin/users/:id/permissions + GET /api/admin/users/options/permissions
BE-3	用户详情 API 返回合并权限	userService.ts (getUserById)	重新构建镜像	详情页权限列表 = 角色权限 ∪ 用户直授权限
BE-4	运营埋点覆盖 6 大模块	deepResearchController.ts, reviewController.ts, AIController.ts, StreamAIController.ts, SessionController.ts, QuickActionController.ts, iitBatchController.ts, auth.controller.ts, auth.routes.ts	重新构建镜像	ASL/RVW/DC/IIT/AIA/SYSTEM 埋点；DC 模块覆盖上传/流式AI/快速操作/非流式AI 全部 4 个入口 + 前端通用上报接口 POST /api/v1/auth/activity
BE-5	运营看板增强（MAU/Token/最活跃用户）	activity.service.ts, statsController.ts	重新构建镜像	getTodayOverview 新增 MAU、apiTokenTotal、topActiveUser
BE-6	埋点验证脚本	scripts/verify-activity-tracking.ts	无需部署	npm run test:tracking 开发/运维自测用
BE-7	AIA 附件格式能力更新（支持 .xlsx/.csv，.doc/.xls 友好提示）	modules/aia/services/attachmentService.ts, modules/aia/services/conversationService.ts, modules/aia/types/index.ts, common/document/ExtractionClient.ts	重新构建镜像	.xlsx/.csv 走 document/to-markdown 灰度解析；统一附件问答护栏，防止引用系统知识库

前端变更

#	变更内容	涉及文件	需要操作	备注
FE-1	运营管理端支持 ops:user-ops 权限入口	AdminLayout.tsx, TopNavigation.tsx	重新构建镜像	非 SUPER_ADMIN 有 ops:user-ops 也可进入运营端
FE-2	用户创建/编辑页新增"用户运营权限"开关	UserFormPage.tsx, UserDetailPage.tsx	重新构建镜像	Switch 控件，保存时调 PUT /api/admin/users/:id/permissions
FE-3	用户管理 API 层新增权限接口	userApi.ts	重新构建镜像	getUserDirectPermissions / updateUserDirectPermissions / getPermissionOptions
FE-4	运营看板展示 MAU/Token/最活跃用户	StatsDashboardPage.tsx, statsApi.ts	重新构建镜像	新增 4 个统计卡片
FE-5	顶部导航点击埋点上报	TopNavigation.tsx	重新构建镜像	点击模块导航时 fire-and-forget 上报
FE-6	AIA 上传交互更新（放开 .xlsx/.csv，.doc/.xls 友好提示）	modules/aia/components/ChatWorkspace.tsx, modules/aia/constants.ts	重新构建镜像	上传白名单与提示文案同步后端，附件入口文案更新

Python 微服务变更

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

R 统计引擎变更

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

环境变量 / 配置变更

#	变更内容	服务	变量名	备注
—	暂无（本次无新增环境变量）

基础设施变更

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

---

记录模板

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

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

---

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

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	✅