hyb-oa/.trellis/tasks/07-15-production-trust-closeout-cleanup/research/p0-technical-research.md

P0 技术研究摘要

运行时基线

• Node 官方 release schedule 显示 Node 20 已于 2026-04-30 结束支持；Node 22 支持至 2027-04-30，Node 24 支持至 2028-04-30。
• 当前本机使用 Node 22，前端 build、Prisma validate 和后端绝大多数测试已在该版本运行；CI、开发 compose 和试运行 Dockerfile 仍为 Node 20。
• 推荐统一 Node 22，更新 CI、Dockerfile、开发 compose、package engines 和版本文件；Node 24 延后单独评估。

依赖升级分段

A. 兼容补丁/小版本

• @fastify/jwt 10.0 -> 10.2；最新版依赖修复后的 fast-jwt 6.2.4。
• Fastify 5.7 -> 5.10。
• fast-xml-parser 5.3.4 -> 5.10。
• Prisma / Prisma Client 7.3 -> 7.8。
• AWS S3 SDK 更新到同一 v3 最新兼容线，以消除旧 XML 解析传递依赖。
• React Router DOM 仅升 6.30.3 -> 6.30.4，不跨到 7.x。

B. OTel 0.x 版本族

• SDK 0.213 -> 0.220，auto-instrumentations 0.71 -> 0.78。
• 0.x 次版本可能包含破坏性变化，需单独验证 server bootstrap、traces disabled/enabled、metrics 和优雅退出。
• 该升级用于消除 protobuf/grpc 等传递严重公告；不在第一批删除 OTel 代码。

C. Nodemailer 主版本

• 当前 6.x，安全修复线为 9.x；项目只使用 createTransport 和文本 sendMail 基础接口。
• 单独升级并补 transporter 配置、发送成功、发送异常和禁用邮件测试；不得用真实 SMTP 做自动验证。

Readiness 状态设计

• check-pending-ocr.mjs 应输出机器可读 PASS/SKIP/FAIL，缺数据库时为 SKIP 且 findingCount 非零。
• run-live-smoke-readiness.sh 为 /ready、public bundle、pending OCR、live smoke、live OCR 分别写 step JSON。
• 缺凭据、缺样票或缺数据库属于 manual_or_config，最终为 PASS_WITH_FINDINGS；required step 失败才为 FAIL/BLOCKED。
• summary.json 必须包含 child/step status、findingCount、repo-relative reportRef 和 commit，且不得含原始凭据名或完整路径。
• 回归必须覆盖缺数据库、缺登录凭据、缺 OCR 样票和全前置条件就绪四类场景。

Dev Seed 安全设计

• NODE_ENV=production 无条件拒绝。
• 必须同时设置显式允许开关和目标数据库确认值；数据库必须为本机地址，确认值必须匹配 URL 中实际数据库名。
• 默认创建缺失开发账号，但不覆盖已有账号密码；密码重置需要额外显式开关。
• 继续支持本地/CI 可重复测试，但不在控制台、报告或文档输出任何口令。
• 对 guard 做纯函数单元测试；禁止用真实数据库验证拒绝路径。

发布追溯设计

• 部署脚本在 rsync 前拒绝 dirty/untracked 工作树，记录完整 commit SHA 和分支。
• 默认要求 HEAD 已包含在 upstream；如确有离线灾备场景，必须使用单独显式 override，不能静默部署未同步提交。
• 构建接收 commit/build 参数，健康或版本元数据返回脱敏短 SHA；部署报告据此核对公网版本。
• 本任务不执行公网部署，完成后另行获得批准。

结论

采用“基线测试 -> Node/兼容升级 -> OTel -> 邮件 -> readiness/seed -> 发布追溯”的顺序。每段可独立回滚 lockfile 和对应代码，避免安全升级与历史清理互相掩盖。

2026-07-15 实施与风险处置结果

• 统一 Node 22，关键生产依赖升级后全量后端为 153 个测试文件、786 个用例全绿；客户端 typecheck/build 全绿。空 DATABASE_URL/JWT_SECRET 的 CI 等价最小门禁同样通过。
• 生产依赖审计：server 为 0 critical / 0 high / 6 moderate，client 为 0 漏洞。server 剩余中危分别位于 Prisma CLI 的 Hono 静态服务依赖，以及 ExcelJS/Tencent SDK 的 UUID v3/v5/v6 传递链；不采用会把 Prisma 回退到 6.x 或 SDK 回退版本的 audit fix --force。
• 完整开发依赖审计 server/client 各 16 项，属于后续构建与测试工具链升级范围，不与本轮生产运行风险混报。
• Pending OCR 改为复用 Prisma 7 adapter 工厂并关闭外部 pool；缺数据库仍为非 clean SKIP。
• Readiness 现在同时记录 sourceCommit、expectedBuildSha、observedBuildSha 和匹配结论；缺失或不匹配不再 clean PASS。
• Seed guard 使用 node-postgres 的实际解析结果校验目标，阻断 ?host= 绕过；新建和显式轮换账号均强制首次改密。
• 邮件失败日志只保留白名单化错误分类、provider code、SMTP command 和数字响应码，不再序列化 Nodemailer 原始错误对象。
• 部署使用 clean/published Git archive，并在判断 published 前刷新 upstream；离线 override 需要 allowlist 原因码且输出醒目审计。完整 SHA 仅用于后端构建与运行时，前端在 Vite 构建期截断为 12 位，直接 Compose 缺任一 SHA 时拒绝解析。
• 敏感扫描从状态矩阵派生全部 CURRENT docs，扫描范围由 16 个文件扩展到 28 个；遗漏的两处完整本地路径已脱敏。
• 本任务只完成本地可信基线，未据此声称公网版本已更新或可测试。