Appearance
mobile-one-tap-login
1. 实验目标与工程要点
这个 Flutter host 实验不演示真实运营商 SDK，而是用可稳定运行的状态机模型还原一键登录真正需要解决的工程问题：
- 协议勾选是不是前置条件
- 当前网络是否满足一键登录拉起条件
- 授权页成功、取消、失败、超时分别如何收口
- 为什么成功后不能立刻跳主页，而要先拉用户信息
- 为什么短信验证码必须是一级兜底路径
它真正验证的不是“按钮能不能调起”，而是一条登录尝试在 Flutter / Android 工程里如何被建模成稳定事件流。
2. 深入原理与生活浅显比喻
2.1 生活浅显比喻
把一键登录想成“商场停车场的快速入场通道”：
- 运营商能力像停车场的车牌识别闸机，只有满足条件时才能快速通行。
- 授权页像人工确认窗口，用户可能确认、取消，或者窗口暂时不可用。
- 业务服务端像商场前台，闸机放行不代表你已经拿到会员卡；还要去前台登记，才能享受完整服务。
- 短信验证码像人工柜台，快速通道不可用时，必须立刻给出可走的人工入口。
所以“闸机抬杆”不等于“已经完成整个业务流程”。
2.2 底层原理分析
一键登录链路至少包含四段状态收敛：
- 前置条件收敛：协议是否勾选、当前网络是否允许走运营商能力。
- 原生授权收敛：授权页是否成功返回凭证，是否被取消或超时。
- 业务会话收敛：服务端是否把凭证换成业务 token。
- 用户态收敛：用户信息、实验开关、首页前置依赖是否准备完成。
实验源码把这些阶段拆成显式 step，而不是用一个 bool isLoading 混过去。这样做的工程收益是：
- UI 能知道当前应该展示 loading、错误提示，还是直接切短信验证码
- 页面销毁后仍可通过 controller/session 保存当前尝试结果
- Android / Flutter / iOS 可以统一业务语义，而不强求底层回调完全一样
2.3 方案对比矩阵
| 方案 | 通俗比喻 | 底层原理 | 保证特性 | 吞吐性能 | 运行开销 | 适用场景 |
|---|---|---|---|---|---|---|
| 朴素 SDK 直调 | 按按钮直接叫闸机抬杆 | 只暴露 success / fail / cancel 回调 | 能快速接通最小能力 | 高 | 低 | Demo、PoC、短期验证 |
| 工程化状态机封装 | 把闸机、前台、人工柜台都接进同一流程单 | 前置校验 + 授权页 + token 换发 + profile 收敛 + fallback | 状态可观测、回退可控、跳转时机稳定 | 中 | 中 | 真正上线的 Android / Flutter 登录入口 |
| 纯短信验证码 | 直接走人工柜台 | 普通 HTTP 登录链路 | 对网络依赖更通用、无运营商授权页 | 中 | 中 | 一键登录不可用或需要兜底时 |
「吞吐性能」与「运行开销」分开看：朴素 SDK 直调最快接通，但稳定性收益最低；工程化状态机会多一层组织成本，却能显著降低线上错位与跳转事故。
3. Android / 移动端实战场景与误配事故
3.1 实战场景
本实验模拟的典型链路：
- 登录页先要求用户勾选协议
- 点击一键登录后先检查网络条件
- 若当前网络不满足条件，立即回退短信验证码
- 若授权页成功，继续模拟服务端换发 token
- token 成功后继续拉用户信息
- 只有用户信息收敛完成，才把状态标记成“可进入主页”
3.2 常见误配与事故注意事项
- 误把授权成功当登录完成：导致主页空态、二次回跳登录。
- 只弹 toast 不切兜底路径：用户不知道下一步该干什么。
- 切网后仍盲目等待授权成功：最终表现成“按钮没反应”或“授权页一闪而过”。
- 把 session 状态绑死在页面 state：页面销毁后回调回来，容易重复跳转或
setState after dispose。
3.3 排障思路
先不要盯 SDK code，而要先问这四件事：
- 这次尝试卡在前置校验、授权页、token 换发，还是用户信息收敛？
- 失败后有没有明确进入 fallbackSms，而不是停在 failed？
- 跳主页条件是
completed还是“只要有 token 就跳”？ - Wi‑Fi/蜂窝切换时，错误是如何被归一化的？
4. 实验源码与运行验证
关键源码
关键参数 / 开关
agreedProtocol：是否勾选协议；未勾选时禁止开始一键登录。carrierAvailable：是否满足运营商能力条件；关闭时直接走短信验证码兜底。simulateUserCancel：模拟用户主动关闭授权页。simulateProfileFailure：模拟 token 换发后用户资料收敛失败。
运行方式
bash
cd labs/flutter/host
flutter pub get
flutter run启动后在首页进入 移动端一键登录工程化。
预期控制台运行输出
text
[checkingPrerequisites] 校验协议与当前网络环境
[presentingAuthPage] 运营商授权页已拉起，等待用户确认
[exchangingToken] 获取凭证成功，向业务服务端换发 token
[fetchingProfile] 业务 token 建立成功，开始拉取用户信息
[completed] 用户信息收敛完成，可安全进入主页页面内还能切换失败分支：
- 未勾协议 → 直接 failed
- 运营商不可用 → fallbackSms
- 用户取消授权页 → failed
- profile 收敛失败 → failed（但不会误跳主页）
5. 对应知识库文档
- 理论主文档：移动端一键登录工程化
这份 README 负责承载 Flutter host 中的真实入口与运行说明；机制分析、Android / Flutter / iOS 对照、误配与排障请回主文档看。
6. 反向关联治理
- 模块总览：
docs/09-specialized-topics/README.md - 相关专项写法参考：
docs/09-specialized-topics/01-bluetooth-ble.md（同样强调“状态机先于按钮能跑”）