恢复付款入口与常开基线（08-01-reimbursement-notification-progress-clarity）

2026-08-01 23:12:23 +08:00
@@ -1404,3 +1404,79 @@ DEPLOY_SERVER=<approved-ssh-target> \
 ```json
 {"preserve_original":["FIELD_ENCRYPTION_KEY"]}
 ```
+
+## Scenario: Formal Feature-Flag Baseline And Reversible QA Window
+
+### 1. Scope / Trigger
+
+- Trigger: a feature is formally enabled after an earlier short-window rollout, or a QA runner temporarily changes an existing feature flag.
+- Purpose: prevent a new database, stale `.env` or QA cleanup path from silently returning a formal capability to its old disabled state.
+
+### 2. Signatures
+
+- Hard gate: `PAYMENT_BATCH_ENABLED=true` in `deploy/trialrun/.env.example` and the active production env.
+- Database baseline: `payment_batch_v1` is first-created as `force_on/global`; `seed:config` still uses create plus `P2002` preservation and never updates an existing row.
+- Deployment assertion: `smoke-trialrun-runtime.js` requires both the env value and effective `FEATURE_FLAG_KEYS.paymentBatch` result.
+- QA snapshot helper: `node scripts/qa/payment-batch-flag-snapshot.mjs capture|restore --snapshot-file <private-json>`.
+- Mobile entry: `/mobile/payment-batches`; PC remains `/payment-batches`.
+
+### 3. Contracts
+
+- Formal enablement is a three-layer contract: env hard gate, database feature flag and runtime smoke. Changing only one layer is incomplete.
+- A short QA window captures `overrideMode`, `rolloutType`, `departmentIds` and `note` before its first flag write and restores those fields in `finally`; it must work when the caller starts either enabled or disabled.
+- A formal-enable runner keeps `force_on` only after every acceptance step passes. Any failed step restores its caller snapshot, not a hard-coded `force_off`.
+- Snapshot files use mode `0600`, contain configuration only and remain under the ignored QA report directory. Credentials and access tokens never enter the snapshot or output.
+- Mobile links must target the mobile route. Enterprise-messenger routing maps a PC-only payment path back to the mobile workbench, so a PC path is not a valid mobile deep link even when the underlying page is responsive.
+- Mobile and PC payment routes share the same permission guard; adding reachability must not broaden `payment.batch.manage|payment.batch.review|risk.review.manage`.
+
+### 4. Validation & Error Matrix
+
+- Env false or absent -> runtime smoke fails before deployment is accepted.
+- Database flag absent/disabled -> runtime smoke fails with the feature-flag reason; do not hide the failure by changing navigation only.
+- Seed meets an existing flag -> `P2002` is preserved with zero update/upsert calls.
+- QA capture fails -> stop before the temporary window; do not run with an unknown rollback target.
+- QA action or later matrix fails -> restore the caller snapshot and keep the run failed.
+- Snapshot restore version conflicts -> fail visibly; never fall back to `force_off`.
+- Mobile finance entry points at `/payment-batches` -> small-screen routing returns to `/mobile`; treat this as an unreachable entry and use `/mobile/payment-batches`.
+- User lacks payment permission -> both routes remain forbidden even if the feature is enabled.
+
+### 5. Good/Base/Bad Cases
+
+- Good: env true + seed first-create force-on + effective runtime smoke pass; a temporary off/on test restores an original allowlist and note byte-for-byte.
+- Base: a database already contains an operator-managed flag; deployment seed preserves it and runtime smoke reports whether it matches the formal baseline.
+- Bad: change only the DB flag while env remains false, or make the mobile card visible but link it to a path that the mobile shell redirects home.
+- Bad: every QA cleanup writes `force_off`, erasing a formal-on state that existed before the test.
+
+### 6. Tests Required
+
+- Seed unit test asserts first-create `force_on/global` and proves `P2002` performs no update/upsert.
+- Snapshot helper tests cover an original `force_off` allowlist and an original `force_on` global configuration, including note restoration.
+- Deployment contract test asserts the env baseline, runtime-smoke flag assertion and absence of fixed-off cleanup helpers.
+- Mobile Playwright covers zero batches/zero exceptions with the feature enabled, a visible “进入付款” link, successful `/mobile/payment-batches` navigation and no finance card for an unrelated role.
+- Run client typecheck/build, Prisma validate, shell/Node syntax, task/governance/process/sensitive gates and `git diff --check`.
+- Public rollout additionally verifies active env, effective flag reason, finance navigation and eligible candidate count without creating, reviewing or executing a real batch.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```bash
+# Cleanup assumes disabled was always the caller's state.
+PUT payment_batch_v1 '{"overrideMode":"force_off"}'
+```
+
+```tsx
+<Link to="/payment-batches">进入付款</Link>
+```
+
+#### Correct
+
+```bash
+node scripts/qa/payment-batch-flag-snapshot.mjs capture --snapshot-file "$REPORT_DIR/flag-before.json"
+# temporary test writes
+node scripts/qa/payment-batch-flag-snapshot.mjs restore --snapshot-file "$REPORT_DIR/flag-before.json"
+```
+
+```tsx
+<Link to="/mobile/payment-batches">进入付款</Link>
+```
@@ -54,3 +54,25 @@
 - 文案改动可直接回滚；共享映射回滚不会影响服务端事实。
 - 付款通知若出现收件范围错误，关闭对应通知类型/代码路径即可，不撤销已经创建或复核的付款批次。
 - 本轮不合并财务复核与组批；累计 5–10 张真实单后的用户访谈是重新立项条件，不是当前发布门禁。
+
+## 7. 付款入口与正式常开防复发
+
+### 7.1 已确认根因
+
+- 当前生产库 `payment_batch_v1` 为版本 1，创建时间等于更新时间，`updated_by` 为空，且没有任何 `FEATURE_FLAG_UPDATED` 审计。
+- 这证明当前库是在初始化时由 seed 首次创建默认 `force_off`，不是 seed 覆盖已有值，也不是 QA runner 或控制台在当前库执行了关闭。
+- 当前运行环境同时为 `PAYMENT_BATCH_ENABLED=false`，因此数据库即使改成 `force_on` 也会被 `env_hard_off` 拦截。
+- 当前唯一 active 财务人员具备 `payment.batch.manage`，但付款入口和已批准候选均因功能门控被隐藏；权限不是根因。
+
+### 7.2 稳定基线
+
+- 试运行正式基线把 `PAYMENT_BATCH_ENABLED` 设为 true，并把 seed 中 `payment_batch_v1` 的首次创建默认值设为全局 `force_on`；seed 继续只创建缺失记录，不更新已有记录。
+- 部署/runtime smoke 明确断言付款批次有效开启，防止换库、换 `.env` 或恢复后再次静默关闭。
+- QA 短窗口保存进入前完整快照并在 finally 恢复该快照；只有明确的正式启用流程在成功时保留 `force_on`，失败才恢复调用前状态。
+
+### 7.3 入口规则
+
+- PC 继续使用现有“付款”导航。
+- 移动财务工作台在付款能力开启时固定显示财务卡片，不再要求先存在批次或异常；卡片进入受同一付款权限保护的 `/mobile/payment-batches`，复用现有响应式付款页，避免企微小屏把 PC 路径重定向回首页。
+- 入口只对真实 finance/finance_mgr 且具备付款权限的人员显示；不向普通员工或仅审批人开放创建能力。
+- 本轮不自动打开创建面板、不自动选择报销、不代替真实财务动作。
@@ -39,11 +39,34 @@
 - [x] 运行客户端 typecheck/build、相关 PC/移动 Playwright 和动作标签单测。
 - [x] 运行 Prisma validate、task/governance/process/sensitive/diff 门禁。
 - [x] 因涉及 workflow/付款职责和通知收件范围，实施后执行只读 reviewer 检查，不允许 reviewer 改代码。
- [ ] 部署与公网检查另行批准；未部署前不通知用户可以测试，企微实际到达必须真机确认。
+- [x] 已获批部署并完成公网检查；企微实际到达仍必须由新业务事件和真机确认，不能用历史 WMSG1 或自动化替代。

 只读审查结论：首次检查发现站内通知中心缺少 `payment_batch` 目标链接，已补 PC/移动统一直达付款页并增加回归；复查未发现阻断项。通知记录与付款动作同事务，IM 投递发生在提交后且失败不回滚；复核人解析排除制单人，付款责任人解析排除复核人；重复创建/复核由既有锁和状态校验拒绝，不重复通知。生产仍无启用且匹配的企微渠道，属于已知部署后配置门，不得表述为企微通知已恢复。

+生产发布记录（2026-08-01，脱敏）：
+
+- 已将已发布提交 `aa6b9bc` 按既有安装固化入口部署；环境合同、迁移状态、`/ready`、外部依赖 smoke、运行时 smoke、公网构建标识和前端资源扫描通过。
+- 历史 WMSG1 已证明当前企微应用具备应用消息发送能力；本轮没有另发渠道测试消息。
+- 生产仅启用 1 条 `wecom_app_message` 渠道，限定 workflow/reimbursement 域和 7 类审批、报销、付款通知；非相关业务类型不匹配。
+- `EMAIL_ENABLED=false` 已在新容器生效；没有创建邮件通知渠道。
+- 渠道创建写入 1 条审计；没有扫描、补发或重放任何历史通知。
+- 当前仅证明“新事件可匹配企微渠道”；仍待王芝玲财务复核/创建付款批次等真实新动作产生 delivery，并由收件人真机确认消息到达与 Deeplink 回流。
+
 ## 6. 运行观察

 - [x] 运行约定为每周集中建立一次付款批次，不建设排程功能。
 - [ ] 王芝玲累计处理 5–10 张真实报销后触发一次访谈，决定财务复核与加入批次是否值得另立合并任务（未来触发条件，当前尚未发生）。
+
+## 7. 付款入口与常开恢复
+
+- [x] 先查生产 R54 变更历史、当前 flag 版本、创建/更新时间、updated_by 和环境硬开关，不先恢复。
+- [x] 确认当前库没有 `FEATURE_FLAG_UPDATED` 审计；根因是当前库首次初始化与 `.env` 均采用关闭默认值，不是 QA runner 或人工关闭。
+- [x] 将正式试运行环境默认硬开关和 seed 首次创建默认值改为付款常开，seed 仍不得覆盖已有记录。
+- [x] 修复 QA 窗口 runner：结束时恢复调用前快照，不无条件写死 `force_off`；正式启用 runner 成功保持 `force_on`、失败恢复原值。
+- [x] 移动财务工作台在付款能力启用但尚无批次时仍显示“付款”入口；PC 入口保持不变；新增移动付款路由避免小屏自动回首页。
+- [x] 补测试覆盖新环境初始化、runner 原值 on/off、移动端零批次入口、普通员工不可见和已批准候选可读。
+- [ ] 通过只读审查后提交、部署；受控设置生产环境硬开关 true 和数据库全局 `force_on`，写审计并验证候选计数，不创建真实批次。
+
+本地验证（2026-08-01）：seed/部署合同/Portal 聚焦单测 19 passed；flag 快照 helper 的原值 `force_off department_allowlist` 与 `force_on global` 两类恢复测试 2 passed；移动信息架构 6 passed；客户端 typecheck/build、Prisma validate、脚本语法、Trellis/task/process/sensitive/diff 门禁通过。
+
+只读审查（2026-08-01）：未发现阻断项。PC 与移动付款路由使用同一权限集合，普通员工不会因新增移动路由获得付款能力；移动财务卡片同时受真实财务角色/付款权限和后端 `financeSummary` 门控；env、DB flag 与 runtime smoke 三层缺一即失败；短窗口在任何临时写入前保存完整快照，成功/失败分支均不会把调用前 `force_on` 或 allowlist 静默改成固定关闭。审查未修改代码。
@@ -20,6 +20,8 @@
 - 保留付款 maker-checker：付款批次创建人与复核人不得相同，当前只需一次非制单复核，不增加更多复核层级。
 - 通知以“新的责任人需要行动”为准：提交后通知主管、主管通过后通知财务、创建付款批次后通知非制单复核人、付款复核后通知财务/批次创建人继续付款、付款完成后通知申请人。
 - 每周集中建立一次付款批次作为当前运行约定，不在本任务建设定时排程、自动组批或强制付款日。
+- 修复财务首次使用时的入口死锁：付款能力正式常开时，即使尚无付款批次，财务人员也必须能在 PC 和移动工作台看到“付款”入口并进入创建页。
+- 恢复生产 `payment_batch_v1` 正式常开基线，并防止新环境初始化或 QA 窗口收尾把正式常开状态静默改回关闭。

 ## Requirements

@@ -29,6 +31,9 @@
 - 普通员工页面不突出“付款批次”内部对象名；有付款批次权限的人员仍可通过现有权限门控入口查看批次。
 - 共享动作标签是唯一事实源；PC、移动和打印页不得继续维护互相漂移的局部映射。
 - 不删除主管审批、财务复核或付款复核，不放宽自审，不把付款完成伪装成审批通过。
+- 付款开关恢复前先查询 R54 变更历史；若当前库无变更审计，必须区分“seed 首次创建默认值”和“seed 覆盖已有值”，不得把不存在的 runner/人工操作写成根因。
+- QA 短窗口结束时必须恢复调用前快照；正式启用流程成功后保持常开，失败才回滚，不得无条件写死 `force_off`。
+- 正式环境和新初始化的试运行环境必须同时满足环境硬开关与数据库开关常开；任何一层关闭都应由部署/运行门禁发现。

 ## Acceptance Criteria

@@ -39,6 +44,9 @@
 - [ ] 创建付款批次后通知实际可复核人员；复核通过后通知实际付款责任人；付款完成继续通知申请人，且同一事件不会重复创建/投递。
 - [ ] 付款复核仍强制非制单人且仅一轮；既有付款批次、审批快照和历史记录不迁移、不改写。
 - [ ] PC/移动相关组件测试、通知路由/服务测试、付款 maker-checker 回归、前端 typecheck/build 与 Trellis 门禁通过。
+- [ ] 财务人员在尚无付款批次但存在已批准待付款报销时，PC 与移动端均可看到“付款”入口，并能看到该报销作为新建批次候选。
+- [ ] 正式初始化基线为付款批次常开；QA 窗口测试覆盖原值为 on/off 两种情况并恢复原值，不再硬编码关闭。
+- [ ] 生产恢复后只验证入口和候选可见，不代替财务创建批次、负责人复核或执行付款。

 ## Out of Scope