hyb-oa/.trellis/tasks/archive/2026-08/08-05-reimbursement-payment-batch-deployment/design.md

报销付款批次改进部署：技术设计

1. Release boundary

本任务只发布已提交代码，不新增产品行为。目标来源为完成任务后的 main HEAD；应用代码核心提交为 d440011，部署任务启动记录会在发布前一并提交并推送。部署从 Git archive 的已验证提交构建，不从脏工作区同步。

2. Controlled deployment path

clean local main
  -> commit/start deployment task
  -> push origin/main
  -> resolve existing controlled SSH identities without echo
  -> deploy-existing aggregate preflight
  -> deploy.sh with SYNC_ENV=0 + existing data contract
  -> runtime/build/smoke checks
  -> forced-command backup contract refresh
  -> public read-only verification

• 部署身份和 refresh 身份必须来自本机既有 SSH 配置，分别通过普通 true 与固定 probe 行为识别；不把候选值写入任务、日志或聊天。
• deploy-existing.sh 是唯一发布入口。它读取 root-owned systemd unit 中的六项 allowlist 合同，内部调用 deploy.sh 并固定 DEPLOY_DATA_MODE=existing、SYNC_ENV=0。
• 若无法唯一解析两个身份，停止并向用户请求本机配置指引；不猜测远端地址。

3. Data and compatibility

• 无 schema 或 migration 变化；部署脚本仍执行标准迁移状态检查，但预期零新增迁移。
• 生产 .env、PGDATA、附件存储和备份合同原样保留。
• 旧客户端/服务端兼容由原功能任务验证；本任务不拆分前后端发布。

4. Verification contract

• 部署脚本必须确认远端运行 build、公开 /ready 和前端短 SHA。
• 公网额外执行无凭据基础 smoke 和资源文案扫描；专用测试凭据存在时才执行登录态 smoke。
• 本轮不在生产创建合成报销或回单。关键业务交互继续引用已通过的本地 19 项合成 E2E，公网只证明目标 build 和前端合同已发布。

5. Failure and rollback

• 推送、来源、预检失败：尚未发布，修复后重试。
• 构建或应用 readiness 失败：按部署脚本失败阶段处理，必要时使用同一入口发布上一已知提交。
• 应用已成功、refresh 失败：不重跑应用发布，只修复并重跑 forced-command refresh。
• 回滚不更改数据库结构、生产 .env、PGDATA 或附件存储。

6. Security boundary

• 任务记录只保存提交、PASS/FAIL/SKIP 摘要，不保存 SSH target、用户名、远端绝对路径、真实账号、回单、银行信息或原始响应。
• 所有公网检查只读；不调用回单在线预览，以免对真实材料产生访问审计或暴露敏感文件。