# 待部署变更清单

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

---

## 当前待部署变更

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

### 数据库变更

| # | 变更内容 | 迁移文件 | 优先级 | 备注 |
|---|---------|---------|--------|------|
| DB-1 | AIA 新增 `attachments` 持久化表（附件文本真相源） | `prisma/migrations/20260309_add_aia_attachments_persistence/migration.sql` | 高 | 解决“附件仅缓存”导致偶发“内容已过期或不存在”，支持缓存 miss 回源数据库 |

### 后端变更 (Node.js)

| # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
|---|---------|---------|---------|------|
| BE-1 | 移除全部 SSE 端点 `Connection: keep-alive` 响应头（HTTP/2 禁止头部） | `chat.routes.ts`, `session.routes.ts`, `workflow.routes.ts`, `OpenAIStreamAdapter.ts`, `ExtractionController.ts`, `researchController.ts`, `conversationController.ts`, `chatController.ts`×2, `StreamAIController.ts` | 重新构建镜像 | 修复 SAE 环境下 SSE 流式响应 `ERR_HTTP2_PROTOCOL_ERROR` |
| BE-2 | 优雅停机增强：健康检查停机时返回 503 + 30s 强制超时兜底 | `healthCheck.ts`, `health/index.ts`, `index.ts` | 重新构建镜像 | CLB 在滚动更新时不再向濒死 Pod 派发请求 |
| BE-3 | AIA 附件链路稳定性修复（上传落库 + 发送回源 + 错误分层） | `aia/services/attachmentService.ts`, `aia/services/conversationService.ts` | 重新构建镜像 | 上传阶段持久化附件文本与提取状态；发送时缓存未命中自动回源 DB 并回填，显著降低“对话中途上传附件无法识别”概率 |
| BE-4 | 生产环境缓存安全护栏：禁止 `CACHE_TYPE=memory` 启动 | `config/env.ts` | 重新构建镜像 | 防止多实例缓存不共享导致附件/会话等状态偶发丢失，符合云原生规范 |
| BE-5 | 登录验证码接入阿里云短信（保留 mock 模式） | `auth.service.ts`, `common/sms/aliyunSms.service.ts`, `config/env.ts` | 重新构建镜像 | `sendVerificationCode` 改为真实短信发送；生产建议 `SMS_PROVIDER=aliyun`，开发可继续 `mock` |

### 前端变更

| # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
|---|---------|---------|---------|------|
| FE-1 | Nginx `Connection` 头部条件化（`map $http_upgrade $connection_upgrade`） | `nginx.conf` | 重新构建镜像 | SSE 请求不再携带错误的 `Connection: upgrade`，WebSocket 不受影响 |
| FE-2 | SSA 对话网络错误友好提示 + 指数退避自动重试 2 次 + 手动重试按钮 | `useSSAChat.ts`, `SSAChatPane.tsx`, `ssa.css` | 重新构建镜像 | 瞬时网络错误自动重试 2 次（2s/4s 指数退避），失败后中文友好提示 + 蓝色重试按钮 |

### Python 微服务变更

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

### R 统计引擎变更

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

### 环境变量 / 配置变更

| # | 变更内容 | 服务 | 变量名 | 备注 |
|---|---------|------|--------|------|
| ENV-1 | 新增短信网关配置（登录验证码） | nodejs-backend | `SMS_PROVIDER`,`SMS_ENDPOINT`,`SMS_SIGN_NAME`,`SMS_TEMPLATE_CODE_LOGIN`,`SMS_TEMPLATE_CODE_RESET`,`ALIBABA_CLOUD_ACCESS_KEY_ID`,`ALIBABA_CLOUD_ACCESS_KEY_SECRET` | 若生产使用阿里云短信，需在 SAE 配置完整变量；`SMS_TEMPLATE_CODE_RESET` 可选（默认复用登录模板） |

### 基础设施变更

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

---

## 记录模板

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

```markdown
<!-- 数据库变更 -->
| 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 | 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 | ✅ |