hyb-oa/.trellis/tasks/archive/2026-10/09-07-e2e-auth-preconditions/prd.md

E2E 认证前置统一

2026-10-11 收口记录（已完成范围收口，后续阶段取消；待归档批准）

已完成的范围（任务记录提交 096576d8，证据在 artifacts/qa-flow/e2e-auth-preconditions/）：

• 立项与认证状态合同、范围边界：用户 2026-09-07 批准。
• 阶段 0：一次本地定向启动条件取证（单条原合同用例、1 worker、零重试、trace=on，结果 timedOut，未改源码）及静态盘点；用户已独立复核批准，对应 AC1。证据 phase0-20260907-01/02/03。
• 在线对照：一次相同原用例，确认原生 navigator.onLine=true，认证前置断言通过、下游“更多”超时，不记为整条通过；online-20260907-01/closeout-receipt.json valid=true。用户认可该结果并撤回默认迁移。

取消的后续阶段：阶段 1 的 31+2 文件迁移、状态合同回归、固定矩阵验证、剩余失败归类及独立复核，均从未获批、未执行，按“取消”记录，不补记为验收通过。AC2–AC6 保持未勾选；207 原浏览器清单撤销决策资格的结论不变，原件保留，不倒写为逐条已证明假失败。

转由其他任务跟进，不随本任务关闭：环境启动合同沿 09-06-release-gate-integrity 的 R2/R6 与设计 §10；登录后的线上冒烟由发布门禁任务的发布后公网必跑项跟进（凭据准备另见公司借款任务后续第 6 项）。场景 8、经理权限缺口与 R1 启用不在本任务范围，亦未因收口改变。

Goal

先确定合成浏览器验收的运行前提与认证起点，再决定修正环境合同还是认证夹具；不预设需要批量迁移 spec。覆盖登录、会话恢复和注销的真实边界，任务独立于 release-gate-integrity，不以修复全部浏览器红项或启用发布门禁作为完成条件。

Confirmed Background

• 用户同意另立任务及认证状态规则；创建轮只做规划，随后明确批准阶段 0 的一次本地观测及静态依赖盘点，不授予批量修改权限。使用 inline，不派 implement/check 代理。
• 已有 24 文件字面交集中，22 文件合并 login/refresh 无条件返回成功，login-portal-ux 另有混合场景；共 23 文件含矛盾路径。local-candidate-witnesses 的有状态处理器不属于此类。24 不是传递依赖扫描所得的全仓上限。
• 原完整诊断中，这 23 文件对应 133 条结果（127 失败、6 通过），文件外另有 80 条失败。这是观测及文件交集，不是逐条确证的同根因清单。来源：artifacts/qa-flow/release-gate-integrity/auth-refresh-readonly-20260907-01/inventory.json。
• 代表性合同用例在单条 1 worker 和全套 4 workers 中都卡登录前置。单条 trace 的首文档和 refresh 请求均未带会话 cookie，后续才出现带标记的 mock fulfill 和 /me 请求。“谁在 /login 前种下 cookie”不能作为已成立的前提；原始证据与限制见 design.md §1。
• AuthContext.tsx:370 的条件还取决于 navigator.onLine；无会话提示不意味着必定跳过 refresh。旧 trace 没有记录该浏览器值或证明首次 refresh 的调用入口，仍不得倒填历史条件。
• 阶段 0 新现场已记录：首次 bootstrap 的 sessionHint=false、online=false、offlineSnapshotAvailable=false，经 bootstrap-primary-refresh → runRefresh 发出一次网络 refresh；无 login 请求，原合同用例仍在登录表单前置 timedOut。仅实验副本追加观测，未改真实源码或判定条件。详见 design.md §3.1。
• 静态盘点覆盖当前 65 个非 manual spec 及本地 import/export 依赖：30 文件存在成功 refresh 与表单路径共存（原 23 + 新 7），另 1 文件为访客提示页路径。原“矛盾”标签只表示条件性风险候选，不能直接当成内在缺陷或迁移必要性。另 2 个认证恢复建模缺项继续分开列示。
• 已批准的在线对照已完成：相同源码、mock 和 114 份观测构建文件，实际首个 bootstrap 的 online=true、hint=false、无快照，进入 guest-ready；登录前 refresh=0、login=1，登录及合同前置断言通过。整条用例仍为 1 timedOut，停在旧“更多”按钮，续约/归档未到达。执行端撤回默认迁移 31 文件的建议，详见 design.md §6.1。

Scope

阶段 0 已独立复核批准；后续单条在线对照已执行，当前交审。阶段 1 的原 31+2 清单及接口保留为历史提案，暂缓且不再作为默认下一步。环境启动合同或夹具改动、后续运行矩阵均须重新明确范围并批准；本次在线授权已用完，不追加运行。

Requirements

以下 R1–R5 为原阶段 1 设计约束，不表示已经确诊 31 文件必须修改。在线对照后，修复对象及范围仍待决定；只有本轮取证与边界约束生效，不启动迁移或环境门禁实现。

R1 — 显式认证状态

• 驱动表单的场景以未认证状态开始；显式登录前 refresh 返回未认证，不能凭固定成功 mock 恢复身份。
• 登录成功后允许 refresh 恢复会话，注销后恢复未认证；不能把 refresh 永久设为 401。
• 权限投影、视觉及业务流可显式从已认证状态开始，但不再重复驱动表单；保留导航、刷新、/me 和原业务断言。
• 正确访客、有状态和真实后端登录场景不得被无差别替换。参照 client/tests/e2e/local-candidate-witnesses.spec.ts:199、:241、:252、:260。

R2 — 触发条件先于修复

• 阶段 0 仅在获批本地合成环境观察会话标记存在性、navigator.onLine、离线快照可用性及首次 refresh 调用入口，不采集 credential、身份或存储原文。
• 已有 trace、新实验和源码推论分别标注；不把新观测倒写成旧现场，不预设 cookie 污染或离线环境问题。
• 观测不改变产品认证语义、不改写网络状态凑通过，也不具有发布资格。阶段 0 运行授权独立于任务创建授权。

R3 — 场景级范围

• 在已有 24 文件清单基础上追踪共享 helper、TEST_IDS、route 注册和调用路径，登记场景起点、refresh 行为、登录方式及证据锚点。
• 以场景而非整文件决定迁移。阶段 1 的精确写入清单须单独获批；新发现同类文件不自动进入写入范围。
• 文件外 80 条本轮不继续归因。已知认证前置解释清楚后，再单列同类候选、独立问题、前置阻断和证据不足；不将它们整体纳入修复承诺。

R4 — 保留验证意图

• 不放宽业务、权限、导航和会话恢复断言；不增加 retry、缩减集合、移入 manual、开启 live 或降低全局并发来制造通过。
• 零重试保持；单 worker 定向证据与默认 4 workers 全套诊断分列。重复运行事先固定目的和次数，不重试至绿。
• 认证前置恢复后暴露的业务失败只报告。合同“更多”漂移、详情入口及续约/归档断言仍由门禁任务阶段 B 处理，不自动视为通过。

R5 — 完成不等于发布

• 本任务交付认证夹具合同、获批迁移、针对性验证和剩余失败分类，不要求无关红项清零。
• 不修改发布入口、R1/R2/R3 机制、skip 或回执消费。R1 启用仍需红项处置、普通 full-local 全绿实测成本、可复现性证据及单独批准。

Acceptance Criteria

• AC1（R2）：阶段 0 给出来源绑定的条件观测或明确缺项；区分请求 cookie、mock 调用和未观测的浏览器状态，不预设 cookie 污染。阶段 0 已获用户独立复核批准；后续在线对照另行交审。
• AC2（R3）：形成包括间接 helper 的场景清单及冻结写入范围；保留原 24/23 口径与新增发现差异，不覆盖旧回执。静态清单已复核，31+2 迁移暂缓，不能把候选清单当成最终写入授权。
• AC3（R1）：获批夹具覆盖登录前未认证、登录后恢复、注销后未认证及显式已认证起点；正常访客和真实后端场景不被误迁移。
• AC4（R4）：命令及 trace 绑定候选和实际用例集合，零重试、原集合及业务断言不变；认证前置到达下一阶段有可核对证据，不冒称整条用例通过。
• AC5（R3/R4）：后续诊断保留剩余失败分类、失败位置及未覆盖状态；合同后续断言、场景 8 和其他问题没有夹带修复。
• AC6（R5）：交审 diff 与获批范围一致；主会话验证不代替独立复核，完成不授予 R1 启用、提交、push、归档或部署资格。

Out Of Scope

产品认证或权限逻辑、经理及付款主体数据、场景 8、合同业务入口修复、发布门禁机制及启用、真实账号和生产数据、live/公网测试、完整绿路径成本测量及未经批准的其他浏览器红项修复。

Test Plan

阶段 0 实际只执行一条原合同用例，1 worker、零重试、trace=on，结果 timedOut；两次准备/收集错误均执行 0 条浏览器用例，分列保留。静态盘点及源码/资源/文档验证不增加浏览器运行。后续实施拟验证四类认证状态及原业务断言，针对性矩阵与全套诊断须各自批准；不把未运行或中断结果补成通过。

后续另批的在线对照也只执行一次相同原用例，1 worker、零重试、trace=on；空白页原生 online/context 隔离检查通过，实际用例 trace 再次确认 online=true。认证前置通过与下游“更多”超时分别计入回执，不记为整条 PASS，不用于普通全绿成本。

Approval And Next Decision

• 已批准：独立立项方向、认证状态合同及范围边界。
• 创建轮已做：planning task、已有 trace 核对和方案；未运行实验。
• 最新批准（2026-09-07）：用户批准 design.md §3 的阶段 0，已 task start；仅一次本地定向启动条件取证及静态盘点。阶段 1 的迁移清单和运行矩阵仍待后续批准。
• 上轮交审：阶段 0 结果及阶段 1 的 31+2 文件/接口提案；该提案随后暂缓，未实施。
• 后续批准（2026-09-07）：阶段 0 已经用户独立复核批准；阶段 1 暂缓，仅批准一次确认原生 navigator.onLine=true 的本地合同定向实验，零重试、trace=on。当前状态仍为 in_progress，不是 planning；已有清单不构成迁移授权。
• 当前交审：在线对照及来源/资源回执。建议下一项先审环境启动前提与显式 offline 用例的边界，不继续原 31 文件默认迁移；这不是环境修复授权。场景 8、经理缺口和 R1 不变。
• 最新结论（2026-09-07）：用户认可在线对照及撤回默认迁移。207 原浏览器清单整体撤销真实红项/工作量/R1 等决策资格，原件保留，不能倒写成逐条均已证明假失败。环境合同归 release-gate-integrity 的 R2/R6 与设计 §10，本 task 不重复定义实现合同；31+2 方案继续暂缓，阶段 B 仅保留原合同业务范围。当前仅规划交审，无实施或运行授权扩展。