From e14400ce1b872f09775494292835bdd013e93506 Mon Sep 17 00:00:00 2001 From: shunli Date: Wed, 5 Aug 2026 10:52:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(reimbursement-payment-batch-deployment):?= =?UTF-8?q?=20=E8=AE=B0=E5=BD=95=E5=8F=97=E6=8E=A7=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E9=AA=8C=E6=94=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .trellis/spec/hyb-oa/deployment-trialrun.md | 97 +++++++++++++++++++ .../implement.md | 46 ++++++--- .../prd.md | 12 +-- 3 files changed, 133 insertions(+), 22 deletions(-) diff --git a/.trellis/spec/hyb-oa/deployment-trialrun.md b/.trellis/spec/hyb-oa/deployment-trialrun.md index ab59361e..1f87a3e2 100644 --- a/.trellis/spec/hyb-oa/deployment-trialrun.md +++ b/.trellis/spec/hyb-oa/deployment-trialrun.md @@ -19,6 +19,103 @@ operations require explicit approval and evidence. - Do not execute real payments, import bank statements, connect payment providers or write ERP without a separate approved Trellis task. +## Scenario: Existing Deployment SSH Identity Disambiguation + +### 1. Scope / Trigger + +- Trigger: `DEPLOY_SERVER` / `DEPLOY_REFRESH_SERVER` are not injected and local + SSH configuration exposes more than one alias that can read the frozen + deployment contract. +- Purpose: select the existing least-privilege deployment account without + guessing from alias names or accidentally publishing as unrestricted root. + +### 2. Signatures + +- Contract reader: `deployment_contract_load `. +- Aggregate preflight: + `DEPLOY_SERVER= DEPLOY_REFRESH_SERVER= bash deploy/trialrun/check-existing-deployment.sh`. +- Refresh probe: `ssh probe` must return exactly + `[deployment-contract-refresh][PASS] probe`. +- Deployment entry: `bash deploy/trialrun/deploy-existing.sh` with the two + resolved targets kept only in process environment. + +### 3. Contracts + +- Never choose a target from its alias name, apparent hostname or ordering in + SSH config, and never print candidate targets while probing. +- A normal deployment candidate must be non-root, own the contracted + `REMOTE_DIR`, `REMOTE_ENV_FILE` and synchronized source files, and have + Docker access. These checks use numeric UID equality on the remote host. +- An unrestricted root alias is not a valid normal deployment target even if + it can read the same contract and pass the aggregate checks. Publishing as + root can change synchronized-file ownership and break the intended + least-privilege path. +- Multiple aliases may point to the same machine and contract. Select a target + automatically only when exactly one candidate satisfies the full non-root + ownership contract; otherwise stop for explicit local configuration + guidance. +- The refresh identity is separate and valid only when the exact forced-command + `probe` response matches. Do not reuse an unrestricted root login as the + refresh identity. +- After deployment, assert the source files still belong to the selected + deployment UID before recording success. + +### 4. Validation & Error Matrix + +- No contract-readable candidate -> stop before remote mutation. +- Exactly one non-root owner candidate + one exact refresh probe -> continue to + 13/13 aggregate preflight. +- Several contract-readable aliases, but only one non-root owner -> use the + owner candidate; do not treat alias count alone as ambiguity. +- Several non-root owner candidates -> stop and request local SSH guidance; + do not choose by config order or connection speed. +- Root candidate passes 13/13 -> exclude it from normal deployment selection. +- Post-deploy ownership differs from the selected UID -> fail closeout and + investigate; do not report the release as clean. + +### 5. Good/Base/Bad Cases + +- Good: two aliases reach the same host and contract; the directory-owning + non-root account is uniquely selected and ownership remains unchanged. +- Base: one normal deployment identity and one forced-command refresh identity + are injected explicitly; no discovery is needed. +- Bad: use an unrestricted root alias because it also returns 13/13 PASS. +- Bad: select the first matching `Host` entry or expose aliases, usernames, + paths or SSH configuration in task evidence. + +### 6. Tests Required + +- Confirm the selected normal identity has a non-zero UID and numerically owns + the contracted repository, environment file and a synchronized source file. +- Confirm Docker access succeeds without sudo and the aggregate preflight is + exactly `PASS=13 FAIL=0`. +- Confirm the refresh identity returns the exact probe token and the normal + identity is not substituted for it. +- After release, compare the synchronized source owner UID with the selected + identity UID and require equality. +- Persist only PASS/FAIL counts and the selection rationale; run the sensitive + content gate before commit. + +### 7. Wrong vs Correct + +#### Wrong + +```bash +# Both aliases connect, so choose the first one (which may be root). +DEPLOY_SERVER="${candidates[0]}" bash deploy/trialrun/deploy-existing.sh +``` + +#### Correct + +```bash +# Resolve exactly one non-root candidate that owns the frozen contract paths, +# then run the aggregate gate before the controlled deployment wrapper. +test "${#owner_candidates[@]}" -eq 1 +DEPLOY_SERVER="${owner_candidates[0]}" \ +DEPLOY_REFRESH_SERVER="$forced_refresh_target" \ +bash deploy/trialrun/check-existing-deployment.sh +``` + ## Scenario: Deployment Env Contract ### 1. Scope / Trigger diff --git a/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/implement.md b/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/implement.md index 093711c2..6f074e77 100644 --- a/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/implement.md +++ b/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/implement.md @@ -2,34 +2,34 @@ ## 1. Activation and publication -- [ ] 用户批准本计划后启动 Trellis task。 -- [ ] 提交任务启动记录，确认工作区干净，将 `main` 推送到 `origin/main`。 -- [ ] 记录明确发布提交并确认无 schema、migration、配置键或部署脚本变化。 +- [x] 用户批准本计划后启动 Trellis task。 +- [x] 提交任务启动记录，确认工作区干净，将 `main` 推送到 `origin/main`。 +- [x] 记录明确发布提交并确认无 schema、migration、配置键或部署脚本变化。 ## 2. Preflight -- [ ] 运行环境合同、Trellis 治理、敏感信息和 Git 来源检查。 -- [ ] 从本机 SSH 配置无回显解析唯一部署身份与 refresh forced-command 身份。 -- [ ] 运行 `check-existing-deployment.sh`，要求 13/13 聚合合同全部 PASS。 +- [x] 运行环境合同、Trellis 治理、敏感信息和 Git 来源检查。 +- [x] 从本机 SSH 配置无回显解析唯一部署身份与 refresh forced-command 身份。 +- [x] 运行 `check-existing-deployment.sh`，要求 13/13 聚合合同全部 PASS。 ## 3. Deployment -- [ ] 使用 `DEPLOY_SERVER`、`DEPLOY_REFRESH_SERVER` 调用 `deploy-existing.sh`。 -- [ ] 确认 `SYNC_ENV=0`、existing data contract、无生产 `.env` 覆盖、无新增 migration。 -- [ ] 确认应用发布和备份合同 refresh 均通过；若部分成功，按设计中的失败分类停止。 +- [x] 使用 `DEPLOY_SERVER`、`DEPLOY_REFRESH_SERVER` 调用 `deploy-existing.sh`。 +- [x] 确认 `SYNC_ENV=0`、existing data contract、无生产 `.env` 覆盖、无新增 migration。 +- [x] 确认应用发布和备份合同 refresh 均通过；若部分成功，按设计中的失败分类停止。 ## 4. Public read-only verification -- [ ] 验证公网 `/ready`、运行时 build SHA 和前端短 SHA命中发布提交。 -- [ ] 运行基础公网 smoke、外部依赖/功能开关检查和公开资源扫描。 -- [ ] 仅在专用 `LIVE_SMOKE_*` 凭据已配置时运行登录态 smoke；否则记录明确 SKIP。 -- [ ] 扫描公开前端资源确认本轮关键文案/入口合同已发布，不读取真实回单或银行资料。 +- [x] 验证公网 `/ready`、运行时 build SHA 和前端短 SHA命中发布提交。 +- [x] 运行基础公网 smoke、外部依赖/功能开关检查和公开资源扫描。 +- [x] 仅在专用 `LIVE_SMOKE_*` 凭据已配置时运行登录态 smoke；否则记录明确 SKIP。 +- [x] 扫描公开前端资源确认本轮关键文案/入口合同已发布，不读取真实回单或银行资料。 ## 5. Closeout -- [ ] 将脱敏部署结果写回本任务，不新建平行报告。 -- [ ] 运行 task validate、Trellis 治理、敏感信息和 `git diff --check`。 -- [ ] 使用中文提交结果记录并引用 `reimbursement-payment-batch-deployment`。 +- [x] 将脱敏部署结果写回本任务，不新建平行报告。 +- [x] 运行 task validate、Trellis 治理、敏感信息和 `git diff --check`。 +- [x] 使用中文提交结果记录并引用 `reimbursement-payment-batch-deployment`。 - [ ] 归档任务并仅在全部公网门禁通过后告知用户可以测试。 ## Rollback points @@ -38,3 +38,17 @@ - 发布中：应用未健康时使用既有入口回退上一已发布提交。 - 发布后：仅备份合同 refresh 失败时不重复部署应用，单独恢复合同。 - 全程不修改生产 `.env`、数据库结构、PGDATA、附件存储或真实业务数据。 + +## Deployment result (2026-08-05) + +- 发布提交：`566c37679a6e9a2581533d40cdcfe7cdd5421b5b`，已由上游包含，未使用 unpublished override。 +- 身份消歧：两个 SSH 别名连接同一主机、读取同一合同；唯一非 root 候选是部署目录、环境文件和源码所有者，另一候选为 root 管理身份。本轮使用实际所有者发布，发布后所有权保持不变；refresh forced-command 身份唯一。 +- 本地门禁：环境合同、任务合同、Trellis 治理、敏感信息、Git 来源和 clean worktree 均 PASS。 +- 远端预检：`check-existing-deployment.sh` 两次均为 13/13 PASS。 +- 发布入口：`deploy-existing.sh` PASS；`SYNC_ENV=0`，existing data contract，生产 `.env` 未同步；64 个 migration 已存在且无待执行项。 +- 运行时：数据库、外部依赖、13 项导航合同和运行时 smoke PASS；容器完整 build SHA、公开 `/ready` 12 位 SHA、前端 12 位 SHA 均命中发布提交。 +- 功能开关：`payment_batch_v1=force_on`、`erp_sync=force_off`，ERP 环境开关保持关闭。 +- 公开资源：扫描 98 个资源，build marker PASS、旧文案 findings=0；`本批次报销单`、`费用明细`、`明细小计`、`下载需说明用途`、`在线查看` 均命中。 +- 备份合同：forced-command refresh PASS。 +- 登录态 smoke：SKIP，当前进程未提供完整专用 `LIVE_SMOKE_*` 凭据；匿名 readiness 无 blocker。真实 OCR 同样因无专用凭据和授权 PDF 样票而 SKIP，未读取或写入真实票据。 +- 业务写入：未执行真实报销、审批、付款批次、回单查看/上传、银行、ERP、企业微信或生产配置写入。 diff --git a/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/prd.md b/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/prd.md index 19022464..f49217a4 100644 --- a/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/prd.md +++ b/.trellis/tasks/08-05-reimbursement-payment-batch-deployment/prd.md @@ -48,12 +48,12 @@ ## Acceptance Criteria -- [ ] AC1：候选提交已推送到 `origin/main`，工作区干净，来源和部署前聚合体检通过。 -- [ ] AC2：`deploy-existing.sh` 完整通过，生产 `.env` 未同步或覆盖，数据库无新增 migration，未发生真实业务或付款写入。 -- [ ] AC3：公网 `/ready`、运行时 build 与前端短 SHA 均命中本次发布提交。 -- [ ] AC4：基础公网 smoke、部署运行时 smoke、外部依赖/功能开关和前端资源扫描通过；登录态 smoke 按凭据实际状态记录 PASS 或明确 SKIP。 -- [ ] AC5：公开资源可确认差旅事由去重、付款批次费用明细/小计和“下载需说明用途”等新前端合同已发布，不暴露真实回单、账号或存储资料。 -- [ ] AC6：任务记录、Trellis 治理、敏感信息检查和 `git diff --check` 通过；只在全部部署与公网门禁通过后告知用户可以测试。 +- [x] AC1：候选提交已推送到 `origin/main`，工作区干净，来源和部署前聚合体检通过。 +- [x] AC2：`deploy-existing.sh` 完整通过，生产 `.env` 未同步或覆盖，数据库无新增 migration，未发生真实业务或付款写入。 +- [x] AC3：公网 `/ready`、运行时 build 与前端短 SHA 均命中本次发布提交。 +- [x] AC4：基础公网 smoke、部署运行时 smoke、外部依赖/功能开关和前端资源扫描通过；登录态 smoke 按凭据实际状态记录 PASS 或明确 SKIP。 +- [x] AC5：公开资源可确认差旅事由去重、付款批次费用明细/小计和“下载需说明用途”等新前端合同已发布，不暴露真实回单、账号或存储资料。 +- [x] AC6：任务记录、Trellis 治理、敏感信息检查和 `git diff --check` 通过；只在全部部署与公网门禁通过后告知用户可以测试。 ## Out of Scope