加固既有生产部署流程（07-27-yang-jun-reimbursement-readiness）

2026-08-01 18:25:20 +08:00
@@ -298,3 +298,29 @@ processingProgress.stages[] = {
 - `displayFormat.ts` 新增可接受 `string | number | null | undefined` 的人民币格式化函数；PC/移动详情删除各自金额 formatter，统一复用。列表页本轮不做横向重构，避免扩大已批准范围。
 - 移动材料区继续承接发票添加；固定底栏删除同名次级按钮，只渲染提交主动作。固定栏的 safe-area、loading、禁用和提交校验保持不变。
 - 回退只需还原前端提交；不涉及 API、数据库、权限、workflow、生产配置或真实数据。
+
+## 14. 生产部署防重复事故合同
+
+### 14.1 根因与边界
+
+- 正确发布提交 `5dac336` 前，首次尝试把 Compose `working_dir` 误当仓库根目录。该标签实际指向 `deploy/trialrun` 配置目录；现有 `deploy.sh` 又到 rsync 之后才检查远端 `.env`，因此错误目标先被同步，随后才因重复的 env 路径停止。旧容器未重建，但远端 `.env` 需从仍运行容器的项目允许键原子恢复。
+- 发布慢的主因不是 Vite；现场 Vite 生产构建约 11 秒，而 server `npm ci` 约 8 分钟。Dockerfile 在依赖层之前注入每次变化的 build args，使 `apk add` 与两套依赖层随提交 SHA 一起失效。
+- 当前加固只改部署脚本、Dockerfile、脱敏输出、测试和既有 runbook/spec；不修改数据库、业务状态、生产 `.env` 值或真实报销数据。加固完成后需另行批准才再次部署。
+
+### 14.2 同步前只读 preflight
+
+- `DEPLOY_DATA_MODE=existing` 时，`deploy.sh` 在创建目录或 rsync 前通过 SSH 验证：`REMOTE_DIR` 已存在且同时含 `server/package.json` 与 `deploy/trialrun/docker-compose.yml`；PGDATA 含 `PG_VERSION`；附件目录存在。
+- `SYNC_ENV=0` 时，同一 preflight 必须确认 `REMOTE_ENV_FILE` 是普通文件；若位于 `REMOTE_DIR` 内，继续使用当前精确相对路径保护。任何验证失败均在 rsync 前退出。
+- 已有生产部署的参数只从受控 automatic-backup systemd unit 的 allowlist 环境读取，并交叉核对活动 Compose project 与挂载；禁止从 `com.docker.compose.project.working_dir` 猜仓库根目录。首次部署继续使用人工审核的显式参数。
+
+### 14.3 Docker 缓存与构建身份
+
+- `base` 只安装稳定系统依赖；client/server dependency stages 只由各自 lockfile（以及 Prisma generate 所需 schema）决定。
+- `VITE_BUILD_SHA` 只在 `client_build` 执行 Vite 前注入；`BUILD_SHA` 只在 `server_build`/最终运行层注入。改变 SHA 必须重建应用产物，但不得重跑基础包和 `npm ci`。
+- 静态合同测试断言 Dockerfile 中 `apk add`、client `npm ci`、server `npm ci` 均早于对应 build arg；既有 deploy 来源、`/ready` 和公网短 SHA 检查继续作为运行时证明。
+
+### 14.4 日志与回退
+
+- seed/smoke 只输出 readiness、计数和布尔状态，不输出完整邮箱、电话、企业微信 corp/agent 标识、redirect URI 或一次性密码。需要首次凭据时必须通过受控配置渠道提供，不从部署日志交付。
+- preflight 失败不需要回滚，因为尚未同步。镜像构建或 smoke 失败时沿用旧容器/既有发布回退合同，不通过重建 `.env` 作为常规路径。
+- 回归至少覆盖错误仓库根、缺失远端 env、无效 existing 数据目录都不会调用 rsync；正确合同可进入 rsync；Docker 缓存顺序与日志禁敏片段均有静态断言。
@@ -16,6 +16,15 @@
 - [x] 运行 R5 双设备、flow coverage/本地候选资产解析、前端 typecheck/build 与 Trellis 治理门禁；记录约 18 个其他孤儿 spec 为后续治理，不在本轮扩范围。
 - [x] 修正上一轮证据中的错误表述：页面实际仍有四个入口，只有旧采集器因 key 漂移看见两个；本轮未推送、未部署前不宣称线上已修复。

+## 0.3 生产部署流程加固（本轮部署后）
+
+- [x] 如实记录 `5dac336` 发布的首次错误根目录尝试、`.env` 原子恢复、第二次成功发布、独立构建身份和备份链验证；真实业务数据与审批状态不变。
+- [x] 把远端仓库根、`SYNC_ENV=0` env、existing PGDATA/storage 验证前移到 rsync 之前；错误合同必须在任何远端同步前停止。
+- [x] 重排 Dockerfile，使基础包与两套 lockfile 依赖层不受 build SHA 变化影响，同时保留前端短 SHA和后端完整 SHA。
+- [x] 收敛 deploy seed/external/runtime smoke 的账号、联系方式和外部配置标识输出，只保留 readiness、计数和状态。
+- [x] 增加部署顺序、错误停止点、Docker 缓存顺序和日志最小化回归；更新 deployment spec 与 runbook。
+- [x] 运行聚焦单测、环境/来源合同、shell 语法、敏感扫描、Trellis/process/docs/diff 门禁；单独提交本地加固，不在未获再次批准时部署。
+
 ## 1. 生产写入前门禁

 - [x] 只读复核活动 server 构建标识、Compose 项目、4 个 systemd service 当前 `BUILD_SHA`、timer enabled/active、最近源端备份与 ARM 新鲜度；输出仅限状态和计数。
@@ -365,3 +374,8 @@
 - 候选门禁修复：`run-local-candidate.sh list` 首轮暴露隔离夹具漏建普通 `bash child-script`，修正为按命令行同时发现 `bash` 与 `bash -n` 子脚本；focused 首轮随后揭示 Wave3 合同页在 Radix 菜单仍打开时等待背景“筛选”按钮至 300 秒超时，改为先完成页面操作、最后验证“更多/导出 CSV”。最终本地候选 50 项、10 个核心 witness 全通过，0 failed、0 skipped、0 unexpected，状态为 `FOCUSED_BROWSER_PASS`。
 - 门禁治理复验：QA Node 测试 52/52 通过；flow coverage 将 acceptance spec 从 7 项增至 8 项，8/8 有效且 0 blocking gap；前端最终 `typecheck` 与生产 build 明确 `exit=0`，PWA 产物生成完成。
 - UX 治理：task validate、Trellis governance、process contract、敏感扫描与 `git diff --check` 通过；文档审计 0 error、1 条既有未注册文档汇总 warning。稳定的 PC 单层来源返回、共享人民币展示及 acceptance spec 必须接入真实门禁的合同已写入 `frontend-react-vite-design` spec。本步骤未部署、未推送、未修改生产配置或真实业务数据。
+- `5dac336` 生产发布事故与恢复：首次尝试把 Compose 配置目录误当仓库根目录，rsync 已把源码同步到错误嵌套位置，随后因重复拼接的 `.env` 路径不存在而停止；旧容器未重建且持续服务，但远端 `.env` 被错误同步删除。恢复只从仍运行的 server 容器按 `.env.example` 允许键提取，163/163 键可恢复、关键键缺失 0，原子写回后权限为 `0600`；未输出值或原始环境。第二次使用正确根目录发布成功并清理错误嵌套代码树，不能表述为一次成功。
+- `5dac336fbf851a4196ee6607e5705ee840dce92f` 生产成功证据：63 个 migration 无待执行项；`/ready`、external deps、runtime smoke 和公网资源扫描通过；公网、活动容器与 4 个运维 service 构建标识匹配，4 个 timer enabled/active，automatic backup daily 与 watchdog 均为 `success/0`。本次未改真实报销、审批或付款数据。
+- 部署加固实现：新增既有部署包装入口，只从 automatic-backup systemd unit 读取 6 个 allowlist 参数且不回显值；远端仓库根、普通非 symlink `.env`、existing PGDATA 与 storage 在 `mkdir`/rsync 前检查。Dockerfile 把 `apk add`、client/server `npm ci` 移到 build SHA 之前；seed/smoke 不再打印完整登录标识、联系方式、企业微信标识、redirect URI 或生成凭据。
+- Docker 双 SHA 实测：第一次冷构建 `server_build` 通过，基础包约 124 秒、client `npm ci` 约 66 秒、server `npm ci` 约 85 秒；仅把前后端构建 SHA 改为另一组值后，三层均明确显示 `CACHED`，第二次约 78 秒，主要剩余前端 typecheck/Vite/PWA 构建与薄的镜像导出。第二个镜像内完整 `BUILD_SHA` 与前端 12 位标识均命中预期。
+- 加固验证：部署安全聚焦测试 7/7；server 全量 172 个文件、1136 项通过，退出码 0；Prisma validate、3 个 shell 语法、4 个 JS 语法、环境合同、task validate、Trellis governance、process contract、敏感扫描和 `git diff --check` 均通过。文档审计为 0 error、1 条既有汇总 warning（22 个历史未登记文件）。本步骤只完成本地流程加固，尚未提交、推送或部署。
@@ -59,6 +59,8 @@
 - 移动草稿详情的“添加发票”只保留在“报销材料”区；底部固定动作栏只保留“提交审批”。不删除发票上传/选择能力，不改变提交前检查、材料权限或审批状态机。
 - 旧 R5 真机反馈用例必须跟随当前移动首页信息架构：从常用动作宫格动态采集实际入口，但对经理测试角色固定断言“新建报销、上传票据、请假记录、采购”四项完整集合，并继续验证触控尺寸、单行标签、SVG 图标和无重叠；不得把动态采集写成“采到什么就接受什么”的重言测试。
 - R5 不得继续作为无人执行的孤立 spec。将其登记到现有本地候选门禁的 acceptance spec 清单，使 `run-local-candidate.sh` 每次候选回归都执行；其余未被任何门禁引用的历史 E2E 仅记录为后续测试资产治理范围，本轮不批量接入、跳过或删除。
+- 本轮生产发布暴露出既有流程仍依赖人工解释 Compose `working_dir`，且远端 `.env`/数据目录检查发生在 rsync 之后；标准发布必须在任何远端同步前只读确认目标是仓库根目录、`SYNC_ENV=0` 的远端 `.env` 存在、existing 数据目录有效，任一不满足即停止且不执行 rsync。既有部署参数以受控 systemd unit 为 canonical source，不再从 Compose 标签临时拼装路径。
+- Docker 生产镜像的依赖层不得因每次变化的 `BUILD_SHA/VITE_BUILD_SHA` 失效。基础系统包与 client/server lockfile 依赖安装必须位于构建标识注入之前；构建标识仍须进入后端运行时和前端 12 位公开标识。部署流程与 smoke 日志不得输出完整登录标识、联系方式、企业微信配置标识或 Secret。

 ## Scope

@@ -112,6 +114,9 @@
 - [x] PC/移动报销详情的总额、明细和发票金额统一使用共享人民币格式，覆盖整数、小数、千分位、空值和非法值。
 - [x] 移动草稿详情“报销材料”区保留“添加发票”，底部固定栏不再重复该动作且“提交审批”仍可见、可达并满足安全区/触控尺寸合同。
 - [x] R5 双设备用例按当前四项常用动作合同通过，且已进入本地候选门禁的 acceptance spec 清单；门禁资产解析能列出该 spec，不再依赖手工全目录执行才发现漂移。
+- [x] 标准部署在 rsync 前验证仓库根目录、远端 `.env` 与 existing 数据目录；错误根目录或缺失 `.env` 的合成回归与脚本顺序断言证明失败发生在 rsync 之前。
+- [x] Dockerfile 顺序合同及双 SHA 实际构建证明提交 SHA 变化不会使 `apk add`、client `npm ci` 或 server `npm ci` 层失效，同时前端短 SHA 与运行镜像完整 SHA 仍可核对；`/ready` 合同未改动。
+- [x] 部署 runbook/spec 固化既有部署参数来源、只读 preflight、失败停止点和脱敏日志边界；本地验证通过后单独提交，不把该未部署的流程加固冒充为已上线。

 ## Out of Scope