Pure Live Firebase 邮箱认证布局与生命周期审计：注入接缝、事务边界与回归验证

本文以 Pure Live 仓库审计文档 FIREBASE_EMAIL_AUTH_LAYOUT_AND_LIFECYCLE_AUDIT_2026_09_12.md 为骨架展开。Pure Live 通过 Firebase 邮箱登录、注册、密码重置与 GitHub 登录入口构建账号体系，本轮审计聚焦登录页的确定性输入、布局、事务与路由生命周期：引入可注入认证后端接缝，用请求代次（generation）封堵异步竞态，并补齐跨平台密码重置入口与可访问性。读完本文，你将掌握这套邮箱认证组件的源码级实现、七类红测问题的根因与修复方式，以及"替身测试通过 ≠ 真实认证通过"的验收边界划分。

一、审计范围与基线

本轮审计以提交 eab239ff49e495d9ee547c73466a4ad9cbda7bb8 为基线，范围覆盖：

• Firebase 邮箱登录（sign-in）；
• 邮箱注册（sign-up）及注册资料元数据；
• 密码重置（forgot password / reset password）；
• GitHub 登录入口；
• 登录页完成回调与返回路由。

审计方式限定为源码阅读、确定性单元/Widget 回归、静态分析与仓库审计，全程未连接手机、未访问真实 Firebase/GitHub 服务、未构建安装包或发布版本。这意味着审计结论全部建立在仓库内可复现的确定性证据之上，真实账号链路留待后续验收。

二、红测复现：七类问题与根因

引入可注入认证后端接缝（即 FirebaseEmailAuthBackend）后，对旧行为进行红测（Red Test），有效结果为 1/7 PASS。七个失败点逐一对应下列根因：

1. 密码重置入口的平台限制

旧实现把"忘记密码"入口硬编码限制在 Android，Windows 桌面端维护中没有入口。修订后改为按后端能力呈现：FirebaseEmailAuthBackend.supportsPasswordReset 返回 true，所有维护平台统一渲染密码重置入口，不再由平台分支决定。

2. 注册元数据可覆盖规范字段

注册资料提交时，自定义元数据可以覆盖规范 email 与 created_at 字段，破坏账号身份标识与注册时间。根因是资料构造直接拼接用户输入与系统字段，缺少字段隔离。

3. 认证进行中仅主按钮失效

认证请求进行中只禁用了主按钮，邮箱、密码、元数据、密码显示开关、"忘记密码"与登录/注册模式切换仍可改动，导致提交快照与界面状态分裂——用户看到的是 A 状态，实际提交的是 B 状态。

4. 密码校验与提交不一致

密码校验使用原始文本，而提交时对密码做了首尾 trim() 裁剪，造成"校验通过却被静默改写"的边界错误。例如密码首尾含空格时，校验通过、实际提交的是裁剪后的版本。

5. 退出登录页后的迟到回调

登录页退出（dispose）后，迟到的失败结果仍会触发可见回调；成功回调也未被等待，云端配置同步与返回路由之间缺少完整事务边界。典型场景：Navigator 已弹栈、页面已销毁，异步结果仍然尝试弹出 SnackBar 或驱动路由。

6. 密码重置失败无反馈

密码重置失败在未注入错误回调时没有任何可见提示；而其余认证失败直接展示后端原始异常文本，用户看到的是未经本地化、面向诊断方而非普通用户的错误内容。此外，固定 46 像素高的按钮缺少随系统可访问字号增高而增长的余量，在大字号缩放下按钮可能显示不全。

三、修订方案：八项修复措施

针对上述根因，本批修订共八项：

1. 注入接缝统一后端：新增 FirebaseEmailAuthBackend，统一封装邮箱登录、GitHub 登录、注册资料保存与密码重置四类调用；所有维护平台按 supportsPasswordReset 能力呈现密码重置入口。
2. 纯函数构造注册资料：注册资料由纯函数 buildFirebaseSignUpProfileData 构造，规范 email 与 created_at 由组件独占写入，保留字段不可被自定义元数据覆盖；其余键与值统一裁剪空白。
3. 单一活动事务 + 请求代次：认证动作使用单一活动事务与递增请求代次（_actionGeneration）；请求期间锁定所有会改变提交语义或认证模式的控件；页面退出后迟到结果不再产生任何界面回调。
4. 密码原样提交：密码按用户输入原样提交（不再 trim），邮箱继续规范化（trim）。
5. 成功回调升级为可等待：onSignInComplete / onSignUpComplete 签名升级为 FutureOr<void>，加载态覆盖后续云端同步与路由收尾的完整时间窗。
6. 等待同步再返回：登录页在成功回调中先等待 AuthController.acceptAuthenticatedUser（含云端配置同步），检查挂载状态后再使用本地 Navigator 返回，避免依赖可能已失效的全局 Get.context。
7. 双语通用失败提示：密码重置、邮箱、GitHub 认证统一补齐双语（中/英）通用失败文案；精确异常仍通过注入错误回调交给诊断方；GitHub 用户主动取消保持静默。
8. 可访问性：认证按钮改用最小高度（kMinInteractiveDimension），密码显示按钮增加双语 tooltip；在 320×480 / 3.0 倍英文环境下，所有入口仍可滚动到达。

四、源码级实现解读

以下实现全部可在 firebase_email_auth.dart 中验证。

4.1 认证后端接缝

FirebaseEmailAuthBackend（firebase_email_auth.dart）是纯 Dart 类，默认实现直连 FirebaseAuth / FirebaseFirestore：

• signInWithEmail → FirebaseAuth.instance.signInWithEmailAndPassword；
• createUserWithEmail → createUserWithEmailAndPassword；
• saveUserProfile → 写入 Firestore users/{userId} 文档；
• sendPasswordResetEmail → sendPasswordResetEmail；
• signInWithPopup / signInWithProvider / signInWithCredential → GitHub 等第三方登录。

FirebaseEmailAuth 组件与 SignInPage 都接受 authBackend 参数且默认值为 const FirebaseEmailAuthBackend()，这使得单元测试与 Widget 测试可以注入替身后端，无需触碰真实 Firebase。

4.2 注册资料纯函数构造

buildFirebaseSignUpProfileData 的关键是保留字段集合：

const reservedFields = {'email', 'created_at', 'createdAt', 'config', 'update_at', 'version', 'canUpload'};

• email 与 created_at 由函数内部写入（email 经过 trim()，created_at 使用 FieldValue.serverTimestamp()）；
• 遍历元数据时，键先 trim()，空键或命中保留字段的一律跳过；
• 其余键值统一 trim()。

这样自定义元数据只能补充扩展字段，无法污染账号身份与注册时间。该保留集合与 firebase_manager.dart 中配置上传载荷的字段（config、email、version、update_at、created_at）保持同源一致，防止注册资料与配置上传互相覆盖。

4.3 单一活动事务与请求代次

状态机由四个辅助方法构成（firebase_email_auth.dart）：

• _beginAction()：未挂载或已加载中则返回 null；否则 ++_actionGeneration 并置 _isLoading = true，返回当前代次；
• _isCurrentAction(generation)：mounted && generation == _actionGeneration；
• _finishAction(generation)：仅当仍是当前代次时清除加载态；
• dispose() 中先 _actionGeneration++ 再释放控制器，使已开始的异步动作在页面销毁后自动"过期"。

所有异步处理器（登录/注册、GitHub 登录、密码重置）都遵循同一模板：

1. _beginAction() 获取代次，为 null 则直接返回；
2. await 后端调用；
3. 结果落地前检查 _isCurrentAction(generation)，否则静默返回；
4. catch 中同样先检查代次，再决定是否上报错误；
5. finally 中 _finishAction(generation)。

因此退出页面后迟到的失败不会触发 SnackBar，成功回调也不会再驱动过期路由。请求期间 enabled: !_isLoading 覆盖了邮箱、密码、元数据、密码显示、忘记密码与模式切换按钮，杜绝提交快照与界面状态分裂。

4.4 密码边界与成功回调

在 _handleSubmit（firebase_email_auth.dart）中：

• 邮箱：_emailController.text.trim()；
• 密码：_passwordController.text 原样提交，与校验逻辑（非空、长度 ≥ 6）使用同一输入；
• 注册成功后通过 buildFirebaseSignUpProfileData 构造资料并 saveUserProfile；
• 成功回调通过 await Future.sync(() => widget.onSignInComplete(credential)) 等待，配合 FutureOr<void> 签名，加载态一直保持到云端同步与路由收尾全部完成。

4.5 GitHub 登录的平台分支

_handleGitHubSignIn（firebase_email_auth.dart）按平台分流：

• Web：signInWithPopup；
• Windows：拉起 Firebase Hosting 中间页 FirebaseManager.middlePageUrl，引导用户在浏览器授权后把 purelive://auth?credential=... 链接粘贴回应用，解析出 accessToken 后经 signInWithCredential 完成登录，随后恢复/置顶窗口；
• macOS / Linux：明确抛出 Unsupported desktop platform；
• 其余（Android/iOS 等）：signInWithProvider。

Windows 侧依赖 firebase_manager.dart 中定义的自定义 scheme purelive 与中间页 URL，FirebaseManager 在初始化时会通过 registerWindowsCustomScheme 在注册表 Software\Classes\purelive 下登记 URL Protocol 与启动命令。

4.6 登录页完成回调与返回路由

sign_in_page.dart 的 _handleSignInComplete 是"等待同步再返回"的具体实现：

1. 取出 credential.user；
2. 判断提供方（Email 或 GitHub）并打日志；
3. await Get.find<AuthController>().acceptAuthenticatedUser(user)——该方法最终进入 auth_controller.dart 的 _applyAuthUser，完成登录态写入与云端配置同步（含收藏/备份配置的 downloadConfig）；
4. 再次检查 mounted；
5. 弹 Toast 提示登录成功；
6. await Navigator.of(context).maybePop() 返回上一页。

关键点在于：同步失败不阻断登录（acceptAuthenticatedUser 内部对可选同步异常做容错），但成功回调本身被等待，加载态与路由收尾构成完整事务边界；返回动作使用本地 context 而非全局 Get.context，避免全局上下文过期导致路由失效。

五、验证结果与证据

本轮验证数据（来自审计文档，可在仓库的构建记录与审计产物中追溯）：

• 红测：旧行为 1/7 PASS；六项失败覆盖跨平台密码重置、保留字段、进行中门禁、密码边界、退出后迟到结果与失败反馈。
• 修订后新增用例：8/8 PASS，其中包含"密码重置完成回调未结束前保持加载态"的时序断言。
• 回归范围：Firebase 认证/配置/个人中心、用户目录/管理、备份页面/布局/往返与翻译合同共 9 个文件，最终 111/111 PASS。
• 静态分析：全库 analyze No issues found（耗时 414.7 秒），质量记录位于 local-artifacts/build-records/20260912T001050421Z-quality-focused.json。
• 仓库审计：local-artifacts/repository-audits/20260912-firebase-email-auth-final.json，错误 0，保留既有警告 2。

翻译合同的验证与双语提示对应 assets/translations/zh.json 与 assets/translations/en.json 中的 firebase_* 文案键（如 firebase_sign_in、firebase_sign_up、firebase_show_password、firebase_reset_password、firebase_email_sign_in_failed、firebase_github_sign_in_failed 等），组件内全部通过 i18n(...) 取词。

六、验收边界与剩余闭环

• 宏观验收条目 A1-05 与 A2-01 继续保持 RUN：本批只闭环邮箱认证的确定性输入、布局、事务与路由生命周期，不把替身测试（注入后端 + 确定性断言）记作真实认证通过。
• 最终候选仍必须使用真实邮箱、GitHub 账号与真实 Firebase 项目验证：登录、注册、密码重置、资料同步，以及 Android / Windows 两端真实的返回体验。
• 截至本批审计，宏观验收状态为 20 PASS / 33 RUN / 9 NR，共 42 组未闭环。

七、给同类 Flutter 应用的移植建议

从本轮审计可以提炼出几条可复用的工程经验：

1. 认证层务必抽象后端接缝：以 FirebaseEmailAuthBackend 为范式，把 Firebase Auth/Firestore 调用收敛到可注入类中，单元与 Widget 测试即可用替身覆盖全部时序分支。
2. 系统字段与用户字段必须隔离：用纯函数 + 保留字段集合构造资料载荷，任何自定义元数据都不能覆盖身份与时间戳字段。
3. 异步 UI 用"请求代次"而不是布尔开关：_isLoading 只解决并发禁用，generation 才解决页面销毁后的迟到回调；dispose 中递增代次是收尾的关键一步。
4. 回调签名用 FutureOr<void>：让加载态覆盖"回调内部的所有异步收尾"，避免界面先恢复、逻辑后执行的竞态。
5. 路由操作绑定本地 context：等待同步完成后检查 mounted 再 Navigator.pop，不依赖全局上下文。
6. 桌面端第三方登录要有兜底链路：Windows 无法直接弹 OAuth 的平台上，中间页 + 自定义 scheme + 粘贴链接是可落地的替代方案，且用户取消应保持静默。

延伸阅读

• FIREBASE_AUTH_CONTROLLER_SESSION_AUDIT_2026_09_12.md：与本文同批的 AuthController 会话生命周期审计；
• FIREBASE_CONFIG_PREVIEW_AND_METADATA_AUDIT_2026_09_12.md：云端配置与元数据字段约定审计；
• auth_controller.dart：登录态生命周期、身份代次与配置同步；
• firebase_manager.dart：Firebase 初始化、Windows 自定义 scheme、配置上传下载与权限角色模型。