R1-R2 落地发布试运行准备清单

2026-05-10 12:44:34 +08:00
@@ -90,6 +90,8 @@ node scripts/qa/check-live-smoke-env.mjs
 LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh
 ```

+发布候选进入公网或小范围试运行前，先按 [`docs/trialrun/release-readiness-checklist.md`](trialrun/release-readiness-checklist.md) 完成证据整理、权限直连审计、部署预检、live smoke 和试运行分级。
+
 系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查：

 - 回调 code 是否传到后端。
@@ -124,6 +126,28 @@ node scripts/qa/check-pending-ocr.mjs --thresholds=2,5,10

 脚本只输出票据 ID、上传时间、尝试次数和最后错误摘要，不读取票据文件内容。缺少 `DATABASE_URL` 时应输出 `SKIP`，不视为真实数据库健康检查通过。

+## 发布候选本地门禁
+
+首轮主线 A8 复跑本地门禁时，需要先用本地回归参数启动服务，再执行回归脚本。推荐参数：
+
+```bash
+SERVE_CLIENT_DIST=true
+OCR_PROVIDER=mock
+IM_NOTIFIER_ENABLED=true
+FIELD_ENCRYPTION_KEY=<local-test-key>
+PROJECT_DOMAIN_ENABLED=true
+PROJECT_LINKING_ENABLED=true
+PROJECT_COMMUNICATION_LOG_ENABLED=true
+PROJECT_CLOSURE_CHECKLIST_ENABLED=true
+```
+
+注意：
+
+- `FIELD_ENCRYPTION_KEY` 只允许使用本地测试值；生产密钥不得提交或写入文档。
+- `OCR_PROVIDER=mock` 只证明本地 OCR 流程，不代表真实 OCR provider 通过。
+- `IM_NOTIFIER_ENABLED=true` 用于覆盖通知链路；缺真实企业微信配置时，企业微信真机仍必须标 `SKIP`。
+- 项目相关开关用于本地项目轻管理回归，不得被解释为扩展 P2 范围。
+
 ## 公网与部署

 当前公网服务器信息以实际配置为准。已知历史信息：
@@ -2,6 +2,8 @@

 **文档状态**：当前操作手册，用于部署后公网、企业微信入口和真实 OCR 条件复核。

+发布候选证据、权限直连审计、部署预检和小范围试运行顺序，以 [`release-readiness-checklist.md`](release-readiness-checklist.md) 为准；本文只列 live smoke 和真实 OCR 的执行条件。
+
 ## 必需环境变量

 - `LIVE_SMOKE_BASE_URL`：默认 `https://oa.hyinda.com`。
@@ -28,3 +30,4 @@ LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readine
 - 缺少 live smoke 账号或 OCR 样本时，脚本必须输出 `SKIP` 和缺项，不得误报通过真实链路。
 - 配置完整时，脚本执行公网 `/ready`、公网资源文案扫描、网页 live smoke 和真实 OCR 样本上传。
 - 脚本不得打印密码、腾讯密钥或第三方 secret。
+- 手机企业微信入口必须由真实企业微信客户端补测；自动化 UA 只能作为辅助证据。
@@ -0,0 +1,128 @@
+# 发布试运行准备清单
+
+**文档状态**：当前操作手册，用于首轮主线发布候选、live smoke 和小范围试运行准备。
+**适用范围**：`hyb-oa` MVP 首轮主线 A1-A8 之后，部署前和部署后试运行前。
+
+本文不替代 PRD、模块规约或 Issue CSV；它只回答“当前是否可以从本地可回归进入公网/企业微信/真实 OCR 验收”。
+
+## 1. 当前结论
+
+- Release candidate：`537e608 A8 完成首轮主线总回归门禁`。
+- 主开发合同：`issues/2026-05-09_20-57-19-mvp-mainline-dev-kickoff.csv`，A1-A8 已全部 `DONE/DONE/DONE`。
+- 剩余主线批次合同：`issues/2026-05-10_10-48-03-mvp-remaining-mainline-closeout.csv`，B1-B5 已全部 `DONE/DONE/DONE`。
+- 当前状态：本地门禁已闭环，尚未部署本轮 release candidate。
+- 当前最大缺口：公网真实账号、企业微信真机和真实 OCR 样票条件未闭环，仍按 `SKIP` 处理。
+
+首轮路线保持不变：OA 是唯一业务主系统和正式审批中心；企业微信只做入口、身份、通知、deeplink 和打卡原始采集边界；不接飞书，不接企业微信原生审批。
+
+## 2. 已完成证据
+
+| 范围 | 证据 | 结论 |
+| --- | --- | --- |
+| A1 代码差距盘点 | `644852f A1 完成MVP主线代码差距盘点` | 已确认复用现有能力，不从零重写 |
+| A2 统一审批中心 | `d871a40`、`f8c99c8`、`28be209` | PC/移动审批、状态展示和本地回归已闭环 |
+| A3 报销/发票/OCR | `e79d252 A3 收口报销发票 OCR 主链路` | mock OCR、查重、主流程和视觉验证已通过 |
+| A4 企业微信入口/通知 | `86451b3 A4 收口企业微信入口与通知回 OA` | 自动化入口和通知 deeplink 已收口，真机留到 live smoke |
+| 测试与交付规约 | `9d6abc7 A1-A5 落地测试与交付规约` | 测试、视觉、SKIP、commit 规则已固定 |
+| A5 请假考勤 | `d2bd4dc A5 收口请假考勤审批口径` | 请假审批、团队状态/日历本地通过 |
+| A6 采购合同项目 | `d6ee25f A6 收口采购合同项目最小可用` | 采购、合同、项目最小可用验证已完成 |
+| A7 权限导航 | `a18d477 A7 收口权限导航与备用模块护栏` | 导航护栏完成，部署前仍需直连权限审计 |
+| A8 总回归 | `537e608 A8 完成首轮主线总回归门禁` | 本地总回归通过，公网/真机/真实 OCR 仍 SKIP |
+
+## 3. 本地门禁复跑条件
+
+A8 的本地门禁不是裸跑脚本即可完成，必须先用本地回归配置启动服务。推荐本地服务参数：
+
+```bash
+SERVE_CLIENT_DIST=true
+OCR_PROVIDER=mock
+IM_NOTIFIER_ENABLED=true
+FIELD_ENCRYPTION_KEY=<local-test-key>
+PROJECT_DOMAIN_ENABLED=true
+PROJECT_LINKING_ENABLED=true
+PROJECT_COMMUNICATION_LOG_ENABLED=true
+PROJECT_CLOSURE_CHECKLIST_ENABLED=true
+```
+
+说明：
+
+- `FIELD_ENCRYPTION_KEY` 必须只使用本地测试值；生产密钥不得提交、打印或写入文档。
+- `OCR_PROVIDER=mock` 只证明本地 OCR 状态机和页面链路，不能替代真实 OCR 验收。
+- `IM_NOTIFIER_ENABLED=true` 用于覆盖通知 outbox 和企业微信通知分支；缺真实企业微信配置时仍不能宣称真机通过。
+- 项目相关开关用于复跑项目轻管理 E2E 和本地 smoke，不表示扩大 P2 范围。
+
+部署前建议复跑：
+
+```bash
+cd server && npm run prisma:validate
+cd server && ./scripts/regression-all.sh
+cd client && npm run typecheck
+cd client && npm run build
+bash scripts/qa/run-web-gates.sh smoke-local
+node scripts/qa/check-live-smoke-env.mjs
+```
+
+## 4. 权限直连审计矩阵
+
+部署前必须补一轮“直连 URL / API 权限审计”。导航隐藏只能改善体验，不能替代服务端授权。
+
+| 角色 | 必查主路径 | 备用或敏感路径 | 期望 |
+| --- | --- | --- | --- |
+| 普通员工 | `/portal`、`/workflow/tasks`、`/reimbursements`、`/leave`、`/purchase-requests`、`/mobile` | `/budgets`、`/ap`、`/integrations/erp`、`/travel`、`/invoice-pool`、`/contracts-registry`、`/payment-batches` | 主路径可用；备用或敏感路径不得泄露数据 |
+| 主管/审批人 | `/workflow/tasks`、业务详情、移动审批 | 预算、ERP、票据中心、付款批次 | 只可见其审批和管理范围内数据 |
+| 财务 | 报销复核、付款、导出、发票相关页面 | 管理员配置、员工敏感档案 | 财务能力可用，不越权到系统管理 |
+| 管理员 | 系统配置、权限、审计、企业微信配置 | 真实凭据和密钥明文 | 可配置系统，但接口不得返回 secret 明文 |
+
+如发现服务端权限缺口，必须停止部署并拆独立修复 Issue；不得用前端隐藏临时绕过。
+
+## 5. 部署预检
+
+部署前只做只读确认，不直接改生产：
+
+- 当前生产 commit、部署目录和本地 release candidate 是否一致。
+- 生产 `.env` 必需项是否完整；检查时不得打印 secret。
+- 数据库迁移状态是否干净；若存在 drift，先备份并拆数据库治理 Issue。
+- 对象存储、附件目录、OCR provider、IM provider、企业微信回调域名是否与试运行目标一致。
+- Caddy/systemd 或既有部署脚本状态是否健康。
+- `/ready`、前端资源、企业微信 config 探活是否正常。
+- 回滚方式是否明确：上一个部署包、上一个 commit、数据库备份和配置备份位置。
+
+## 6. 公网 live smoke 条件
+
+执行前必须准备以下环境变量或本机安全文件，不提交到仓库：
+
+- `LIVE_SMOKE_ADMIN_IDENTIFIER` / `LIVE_SMOKE_ADMIN_PASSWORD`
+- `LIVE_SMOKE_EMPLOYEE_IDENTIFIER` / `LIVE_SMOKE_EMPLOYEE_PASSWORD`
+- `LIVE_EXPECT_WECOM_STATUS=ready`
+- `PLAYWRIGHT_OCR_LIVE_FILE` 或 `PLAYWRIGHT_OCR_LIVE_DIR`
+- 可选：`PLAYWRIGHT_OCR_LIVE_IDENTIFIER` / `PLAYWRIGHT_OCR_LIVE_PASSWORD`
+
+命令：
+
+```bash
+node scripts/qa/check-live-smoke-env.mjs
+LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh
+```
+
+判定：
+
+- `liveSmokeReady=false` 时只能记录公网账号条件缺失。
+- `liveOcrReady=false` 时只能记录真实 OCR 条件缺失。
+- 手机企业微信入口必须用真实企业微信客户端补测；普通浏览器 UA 不等于真机通过。
+
+## 7. 小范围试运行
+
+只有 R3-R5 无阻断后，才开放 2-3 个内部用户试运行。
+
+建议首批角色：
+
+- 普通员工 1 人：提交报销、请假、采购，使用移动入口补资料。
+- 审批人 1 人：处理待办、驳回或退回一条测试申请。
+- 财务或管理员 1 人：复核发票、标记付款、导出、检查审计和通知记录。
+
+试运行规则：
+
+- 每日固定收集问题，按阻断、重要、体验、后续需求分级。
+- 问题先登记到新 Issue CSV，不在试运行现场扩大范围。
+- P2 的预算、ERP、AI、完整差旅、复杂 BPM 继续不进入首轮试运行。
+- 出现权限泄漏、付款状态错乱、真实 OCR 大面积失败、企业微信入口无法进入时，应暂停试运行并回滚或修复。
@@ -45,6 +45,7 @@
 | [管理员手册](./admin-handbook.md) | 管理员上线、企业微信入口、权限、试点配置 | 适合小团队试运行 |
 | [员工快速上手](./employee-quickstart.md) | 员工侧日常使用说明 | 面向普通员工 |
 | [试运行与自动化验证 Runbook](./trialrun-runbook.md) | 本地、公网、企业微信试运行操作 | 涉及公网或企业微信真机时必须看 |
+| [发布试运行准备清单](./trialrun/release-readiness-checklist.md) | 发布候选证据、权限直连审计、部署预检、live smoke 和小范围试运行顺序 | 从本地可回归进入公网/真机验收前必须看 |
 | [公网 live smoke 与真实 OCR 准备清单](./trialrun/live-smoke-readiness.md) | 公网、真实 OCR、企业微信入口复核准备 | 只有部署后才能给出真机验收结论 |
 | [真机公网测试清单](./trialrun/real-device-public-checklist.md) | 手机、企业微信、拍照/PDF 上传人工验证 | 用于上线前人工验收 |

@@ -90,7 +91,7 @@
 4. 要看“某个业务规则为什么这么定”：读 [产品口径文档](./product-decisions.md) 和对应规则文档。
 5. 要判断测试、视觉验证、SKIP、状态回填和提交规则：读 [测试规约与回归门禁](./测试规约与回归门禁.md) 和 [开发交付与变更管理规约](./开发交付与变更管理规约.md)。
 6. 要判断功能是否已经做过：读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。
-7. 要上线或真机验收：读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。
+7. 要上线或真机验收：读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、[发布试运行准备清单](./trialrun/release-readiness-checklist.md)、live smoke 清单和最新部署结果。

 ## 明确废弃或不进入首批

@@ -0,0 +1,7 @@
+ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
+R1,发布候选证据整理,"固定首轮主线 release candidate，汇总 A1-A8 提交、已通过门禁、SKIP 原因、未部署状态和回滚口径；本 Issue 不改业务代码。","1) 明确 release candidate commit；2) A1-A8 与 B1-B5 状态可追溯；3) 本地已通过门禁和 live smoke 缺项清晰；4) 不写入真实账号、密钥或样票路径。","流程级验证：人工核对 git log、主 CSV、批次 CSV 和发布准备清单；命令：python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-10_12-39-37-release-readiness-live-smoke.csv；命令：rg -n \"537e608|liveSmokeReady=false|liveOcrReady=false|未部署|SKIP\" docs/trialrun/release-readiness-checklist.md issues/2026-05-10_12-39-37-release-readiness-live-smoke.csv。","git|python3|rg|manual",DONE,DONE,DONE,"docs/trialrun/release-readiness-checklist.md|issues/2026-05-10_12-39-37-release-readiness-live-smoke.csv","[]","已固定 RC=537e608；公网、企业微信真机、真实 OCR 未在本轮执行，必须等 R4/R5 条件满足后补测；回滚优先回到上一稳定提交或恢复上次部署包。"
+R2,本地门禁与 Runbook 补强,"把 A8 本地回归真实需要的本地服务参数、命令顺序、live smoke 检查和 SKIP 规则写入当前操作手册，避免后续误判。","1) Runbook 写明 SERVE_CLIENT_DIST、OCR_PROVIDER、IM_NOTIFIER_ENABLED、FIELD_ENCRYPTION_KEY 和项目 feature env 的本地门禁用途；2) live smoke 清单链接到发布准备清单；3) 不新增业务 API、数据库迁移或部署操作。","流程级验证：人工阅读 Runbook 能复现 A8 本地门禁准备；命令：rg -n \"发布候选|SERVE_CLIENT_DIST|OCR_PROVIDER|IM_NOTIFIER_ENABLED|FIELD_ENCRYPTION_KEY|PROJECT_DOMAIN_ENABLED|release-readiness-checklist\" docs/trialrun-runbook.md docs/trialrun/live-smoke-readiness.md docs/文档索引.md。","rg|manual",DONE,DONE,DONE,"docs/trialrun-runbook.md|docs/trialrun/live-smoke-readiness.md|docs/文档索引.md","[\"R1\"]","仅补文档和清单；测试 FIELD_ENCRYPTION_KEY 只能用于本地回归，生产必须使用安全密钥且不得提交。"
+R3,权限直连审计,"在部署前用员工、主管、财务、管理员账号直连主路径和备用路径，确认导航隐藏没有掩盖服务端授权缺口。","1) 形成角色 x 路径允许/拒绝矩阵；2) 普通员工直连预算、AP、ERP、完整差旅、票据中心、合同台账、付款批次等备用路径不得获得越权数据；3) 若发现服务端权限缺口，先拆独立修复 Issue，不进入部署。","流程级验证：分别登录员工、主管、财务、管理员账号 -> 直连 /budgets、/ap、/integrations/erp、/travel、/invoice-pool、/contracts-registry、/payment-batches 和对应 API -> 记录 HTTP 状态、页面提示和是否泄露数据；命令：cd client && npm run test:e2e -- settings-governance.spec.ts login-portal-ux.spec.ts --workers=1；必要时补充人工矩阵。","playwright|curl|manual",TODO,TODO,TODO,"client/tests/e2e/*|server/src/routes/*|docs/trialrun/release-readiness-checklist.md","[\"R2\"]","涉及权限模型，发现阻断问题必须停止发布并另拆 Issue；不得仅靠前端隐藏判定通过。"
+R4,部署预检,"检查生产/公网环境变量、数据库迁移状态、备份、回滚命令、Caddy/systemd 状态、/ready 和前端资源版本；未经批准不部署。","1) 生产环境变量缺项和敏感项不打印；2) 数据库迁移状态明确且有备份/回滚路径；3) Caddy/systemd 或既有部署方式健康；4) /ready 与前端资源版本可核对；5) 若需要修改生产配置，必须先获得确认。","流程级验证：只读检查部署目录、服务状态和 /ready；命令：node scripts/qa/check-live-smoke-env.mjs；命令：LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh；生产变更前必须停止等待批准。","ssh|bash|node|manual",TODO,TODO,TODO,"deploy/*|scripts/qa/*|docs/trialrun/release-readiness-checklist.md","[\"R3\"]","本 Issue 默认只读预检，不执行 deploy；若远端迁移 drift 或配置缺失，另拆部署治理 Issue。"
+R5,公网企业微信和真实 OCR live smoke,"在 R4 预检通过且真实测试账号、企业微信配置和真实 OCR 样票齐备后，执行公网登录、企业微信入口、移动审批、报销/OCR 上传和通知 deeplink。","1) LIVE_SMOKE_* 从缺失变为可执行；2) 企业微信 config、OAuth 跳转和手机入口可验证；3) 真实 OCR 样票上传能进入可解释终态；4) 缺配置时继续 SKIP，不得宣称真机或真实 OCR 通过。","流程级验证：node scripts/qa/check-live-smoke-env.mjs --strict；命令：LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh；人工真机：手机企业微信工作台打开海音达工作台 -> deeplink 回 OA 审批或详情页 -> 记录结果。","node|bash|playwright|manual",TODO,TODO,TODO,"scripts/qa/*|docs/trialrun/live-smoke-readiness.md|docs/trialrun/real-device-public-checklist.md","[\"R4\"]","真实账号、企业微信凭据、OCR 凭据和样票路径只放环境变量或本机安全位置；不得提交到仓库。"
+R6,小范围试运行,"公网和真机 smoke 通过后，只开放 2-3 个内部用户按清单试运行报销、请假、采购、审批、企业微信移动入口、付款和导出；反馈转新 Issue。","1) 试运行名单、角色、时间窗口和回滚联系人明确；2) 员工提交、审批人审批、财务付款/导出、企业微信 deeplink 回 OA 均有记录；3) 每日问题只登记和分级，不现场扩大 P2 功能范围；4) 试运行结束形成继续/回滚/修复判断。","流程级验证：员工提交报销/请假/采购 -> 主管或财务审批 -> 财务付款或导出 -> 企业微信通知 deeplink 回 OA -> 管理员检查审计和状态；人工记录问题、截图和处理结论。","manual|playwright",TODO,TODO,TODO,"docs/trialrun/release-readiness-checklist.md|docs/trialrun/manual-trialrun-report.md|issues/*.csv","[\"R5\"]","小范围试运行前不得扩 P2 预算、ERP、AI、完整差旅、复杂 BPM；反馈必须进入新 Issue CSV。"