1. "享家社区"为什么把登录模块交给Flutter：选型与边界
1.1 社区类App登录场景的特殊性
"享家社区"是一个面向小区住户的社区服务App，登录模块是它最基础也最容易出问题的部分。住户通过它交物业费、报修、开门禁、收通知，登录态一旦失败，用户第一反应不是去检查网络，而是直接卸载。所以登录模块的稳定性、兼容性、安全性，优先级比功能迭代还要高。
社区类App的登录场景有几个和其他类型App不太一样的地方。一是用户群体年龄跨度大，从二三十岁的年轻人到六七十岁的老年人都有，手机型号从最新的旗舰机到四五年前的百元机都会出现；二是使用场景碎片化，进出小区大门、电梯口、地下车库这些地方信号都不好，弱网、断网、超时的情况非常常见；三是登录方式多样化，手机号验证码登录、微信登录、华为账号登录要同时支持，部分老旧设备还依赖密码登录兜底。
这直接决定了登录模块的技术选型不能只考虑功能实现，还要考虑后续在鸿蒙系统上的适配成本。鸿蒙生态的设备量这两年涨得非常快，小区周边的智能门禁、智慧屏、车机很多已经跑在鸿蒙上，"享家社区"如果只做Android和iOS，用户换到鸿蒙设备时就会遇到"应用未适配"的提示，体验非常割裂。所以从一开始，团队就定下了Flutter作为跨端方案，一套代码同时覆盖Android、iOS和HarmonyOS。
1.2 Flutter在鸿蒙生态的可行性判断
提到Flutter跑鸿蒙，很多人的第一反应是"flutter run"能不能编译出HAP（鸿蒙应用安装包）。这里需要先理清一个概念：HarmonyOS NEXT（纯血鸿蒙）不再兼容Android APK，必须使用HAP格式和应用市场分发机制。而Flutter官方目前并没有直接支持HarmonyOS的正式版本，我们实际用的是Flutter的OpenHarmony分支，以及社区维护的ohos适配层。
这不是一个简单改改Gradle配置就能解决的工程量。Flutter框架本身涉及Dart运行时、Engine（Impeller/Skia渲染引擎）、Platform Channel三大部分的鸿蒙化。Dart运行时在OpenHarmony上已经可以正常编译，Engine部分需要把Skia的渲染后端切到鸿蒙的图形栈上，Platform Channel则要对接鸿蒙的Ability和ArkTS运行时。团队在做技术调研时，核心判断依据是三点：一是登录模块用到的Flutter基础组件在鸿蒙分支上的覆盖度，二是MethodChannel/EventChannel在鸿蒙侧的稳定性，三是shared_preferences、dio、provider这些常用三方库是否有鸿蒙适配版本。
实测下来，Flutter的OpenHarmony分支对登录模块所需的UI组件（TextField、Button、Checkbox、Scaffold、SnackBar）覆盖度已经超过90%，Platform Channel在基础类型传输上表现稳定，dio网络库可以正常跑，shared_preferences有社区适配版。这套配合在2024年底到2025年初的时间节点上是可用的，但需要注意一些边界问题，下面会展开讲。
1.3 登录模块的技术架构
"享家社区"的登录模块分成五层：
- UI层：登录页、验证码页、协议页、忘记密码页，采用Flutter Widget实现；
- 状态层：使用Provider管理登录状态、倒计时状态、协议勾选状态；
- 网络层：dio封装统一请求入口，处理Header、超时、重试、401拦截；
- 存储层：shared_preferences存储Token、用户基础信息，敏感信息单独加密；
- 原生桥接层：MethodChannel调用鸿蒙侧短信验证码SDK、设备信息获取、系统权限申请；EventChannel订阅鸿蒙侧推送的登录生命周期事件。
这五层里，前三层和普通Flutter项目基本一致，真正容易出问题的是第五层。鸿蒙的Ability模型和Android的Activity模型差异很大，MethodChannel的注册方式和作用域也不同，后面会单独用一个章节专门讲桥接层的坑。
2. 鸿蒙环境的搭建与版本匹配：这一步错，后面全是泪
2.1 Flutter SDK和鸿蒙SDK的版本关系
先说结论：不要用最新版Flutter，也不要用最新的DevEco Studio，二者偶合版本要比Android开发严格得多。
"享家社区"的鸿蒙分支锁定的版本组合是：Flutter SDK采用3.22.x的OpenHarmony分支（flutter_flutter的ohos分支），Archived后的版本是3.24.x；DevEco Studio使用5.0.3 Release（API 12）；SDK配套使用12.x版本。这个组合在社区生态里已经验证过至少两年，踩坑文档最多，遇到问题搜索引擎能搜到答案。
为什么不能用官方稳定版Flutter跑鸿蒙？因为官方稳定版里没有ohos平台目录，运行flutter create时压根不会生成鸿蒙工程的目录结构，编译时直接报错找不到platforms。必须使用带ohos适配的分支，拉取之后切到ohos分支，再执行flutter doctor检查。
环境变量方面，除了常规的ANDROID_HOME外，还需要配置DEVECO_SDK_HOME，指向DevEco Studio内置的SDK目录。如果本机之前装过旧版本的HarmonyOS SDK，建议全新安装，因为API版本升级后，老的hvigor构建工具和新的SDK之间经常出现兼容性报错，这个报错信息很迷惑，看起来是Gradle问题，实际是SDK版本不一致。
2.2 项目级配置：从Android工程迁移到hap构建
在Flutter的OpenHarmony分支下创建新工程，生成的目录结构和标准Flutter工程不太一样，多了一个ohos目录：
my_app/ ├── android/ ├── ios/ ├── ohos/ # 鸿蒙工程目录 │ ├── entry/ │ │ ├── src/main/ │ │ │ ├── ets/ # ArkTS入口代码 │ │ │ ├── resources/ # 资源文件 │ │ │ └── module.json5 # 模块配置 │ ├── build-profile.json5 # 签名配置 │ └── hvigorfile.ts # 构建配置 └── lib/首次跑鸿蒙编译时，需要留意build-profile.json5里的签名配置。DevEco Studio支持自动签名，但自动签名要求登录华为账号，并且要先把设备连接到电脑开启开发者模式。如果公司网络环境对华为账号登录不友好，也可以使用本地调试签名，在项目里配置一个临时的p12和cer文件，这种方式适合内部自测，上架时再替换为正式签名。
还有一个容易踩的坑是minSdkVersion。鸿蒙的API 12对应设备的最低版本，如果项目里某些三方库要求更高的API，构建时不会直接报错而是运行时会出现奇怪的崩溃。建议在module.json5的abilities节点里显式声明minAPIVersion，避免出现"开发机能跑但用户设备崩溃"的情况。
2.3 真机调试与签名配置
第一次在鸿蒙真机跑Flutter项目，最大的问题是热重载经常失效。Android和iOS上按r键就能热重载改动，鸿蒙分支的插件通道有时没有完全打通，改完Dart代码后，界面还是旧的状态，按r没有反应，最后只能flutter run --hot重新启动。这个问题在OpenHarmony分支的某些小版本上随机出现，没有规律。我们的做法是：小改动直接配合日志打印逻辑，大改动干脆冷重启，实测比重复按r等待失败要节省时间。
鸿蒙真机调试还需要注意设备类型。手机、平板、开发板、智慧屏的屏幕分辨率差异巨大，登录页在手机上正常显示，放到平板上布局就乱了，放到电视上焦点控制又会丢。如果项目规划覆盖多端，建议开发时就把MediaQuery和自适应布局尽早做上，别等联调阶段再改，那会儿要改的东西会是现在的好几倍。
3. 登录页面的UI实现：验证码输入、隐私协议和键盘避让
3.1 登录表单的结构与组件选型
"享家社区"的登录页走了最常规的手机号+验证码模式，同时保留了密码登录入口。表单最核心的组件是手机号输入框和验证码输入框。
手机号输入框用TextField，但需要限制输入类型为数字，用keyboardType: TextInputType.phone，同时配合inputFormatters限制长度为11位。这里有一个交互上的小细节：用户输入手机号时，不应该限制粘贴操作，很多老年用户记不住手机号，会从短信或者微信里复制过来，如果禁用粘贴会把他卡死。正确的做法是允许粘贴，但粘贴后做一次完整的正则校验，不通过就给出错误提示。
验证码输入框的UI有两种做法：一种是单输入框，简单直接；另一种是6位独立输入框，视觉上更清晰，适合老年用户。"享家社区"最终选了后者，用6个独立的TextField组合，每个输入框宽度60px左右，当前激活的框加边框高亮。但实现时有个麻烦：焦点管理。用户输完第一位自动跳到下一位，删空当前位回退到上一位，这个逻辑做起来不难，难的是鸿蒙分支上TextInput的焦点回调有时不稳定，自动聚焦请求偶尔失效。解决方式是用FocusNode列表，配合一个计数器，在输入变化的回调里手动控制下一个节点的requestFocus。用一个简洁的版本：
class VerificationCodeInput extends StatefulWidget { // 外部只需要监听完整的6位验证码 final ValueChanged<String> onCompleted; // 倒计时结束后清空验证码时，通过key强制重建组件 final Key? resetKey; } class _VerificationCodeInputState extends State<VerificationCodeInput> { late List<TextEditingController> _controllers; late List<FocusNode> _focusNodes; @override void initState() { super.initState(); _controllers = List.generate(6, (_) => TextEditingController()); _focusNodes = List.generate(6, (_) => FocusNode()); } String get _code => _controllers.map((c) => c.text).join(); void _onChanged(int index, String value) { if (value.isNotEmpty && index < 5) { FocusScope.of(context).requestFocus(_focusNodes[index + 1]); } if (_code.length == 6) { widget.onCompleted(_code); } } @override Widget build(BuildContext context) { return Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: List.generate(6, (index) { return SizedBox( width: 44, height: 52, child: TextField( controller: _controllers[index], focusNode: _focusNodes[index], keyboardType: TextInputType.number, maxLength: 1, textAlign: TextAlign.center, style: const TextStyle(fontSize: 22, fontWeight: FontWeight.bold), onChanged: (value) => _onChanged(index, value), decoration: InputDecoration( counterText: '', contentPadding: const EdgeInsets.only(bottom: 8), border: OutlineInputBorder( borderRadius: BorderRadius.circular(8), borderSide: const BorderSide(color: Color(0xFFDDDDDD)), ), focusedBorder: OutlineInputBorder( borderRadius: BorderRadius.circular(8), borderSide: const BorderSide(color: Color(0xFF1677FF), width: 2), ), ), ), ); }), ); } }这套代码在Android和iOS上表现良好，鸿蒙分支上需要多测一个场景：快速连续输入时焦点是否错位。实测在鸿蒙上偶发"输完第2位直接跳到第4位"的问题，原因是TextInput的通道在快速事件下出现丢帧，焦点丢失后靠手动补一次requestFocus恢复。
3.2 短信验证码倒计时的实现细节
倒计时按钮的逻辑不算复杂，但有两个细节常被忽略。一是倒计时期间要禁用按钮，防止重复点击产生多条短信；二是页面销毁时必须清理Timer，否则用户退出登录页后倒计时还在跑，重新进入页面时会出现两个倒计时互相覆盖。
"享家社区"的做法是把倒计时状态放在Provider里，而不是放在Widget的State里。原因很实际：如果放在State里，点完发送验证码后退到后台，再切回前台，倒计时显示会归零，但实际上短信已经发出去了，用户会以为又被重置了。放在Provider里，用AppLifecycleState监听前后台切换，后台时只暂停计时，回前台时恢复剩余秒数，体验就顺了。
发送验证码的按钮还需要处理"手机号未填满"的置灰态。我们做的规则是：手机号长度小于11位时，按钮为灰色不可点；达到11位且是合法号码时，按钮高亮。这需要监听手机号输入框的onChanged，在Provider里维护一个computed字段。代码量不大，但能给用户非常明确的操作反馈。
3.3 隐私协议的合规交互
登录页的隐私协议勾选是合规要求的必须项，但很多App做得很难用——默认勾选、小到看不清的复选框、只有一行小字。这些做法都不可取，尤其面向小区住户这种真实信息公开的场景，一旦被投诉，问题远大于用户体验。
"享家社区"的协议交互是这样设计的：复选框区域就是一个可点击的完整组件，不单独画一个小方框，因为小方框在触屏上很难点准，尤其老年用户手指接触面积大。点击整个区域可以切换勾选状态，文字部分用富文本RichText，分三段："我已阅读并同意"、《用户服务协议》、《隐私政策》、《个人信息保护指引》。协议两个字用蓝色下划线标识，点击跳转到对应H5页面。
有一个细节值得说：协议文字里"已阅读"这个状态，很多App只是本地记一个布尔值，勾上就算已阅读。我们做了个稍微严格一点的逻辑——用户必须点击过至少一次协议链接，才能勾选完成。目的是防止有纠纷时说"用户根本不知道协议内容"。这个逻辑不复杂，就是在Provider里维护一个hasOpenProtocol的标记，勾选时判断该标记是否为true。
3.4 键盘弹出时的布局避让
登录页的键盘弹出避让，在Android上用的是Scaffold的resizeToAvoidBottomInset，默认就能把输入框顶上去。但鸿蒙分支上这个默认行为不可靠，实测在某些版本上键盘弹出后布局不动，输入框被键盘完全挡住。
排查下来，问题出在鸿蒙分支对flutter的viewInsets上报频率不完整，SystemChrome.setEnabledSystemUIMode里的键盘模式配置也没有完全实现。绕过去的方法是手动监听键盘高度变化：在主页面用WidgetsBindingObserver监听didChangeMetrics，通过MediaQuery.of(context).viewInsets.bottom拿到键盘高度，然后给底部表单区域加一个等于键盘高度的padding。实测这种方法在鸿蒙上比依赖Scaffold默认值更稳定。
另外输入框弹出后还涉及滚动定位的问题。如果登录页内容超过一屏，键盘弹出后应该自动滚动到当前聚焦输入框的可视区域，这个用Scrollable.ensureVisible配合FocusNode就能实现。在鸿蒙上这个API行为正常，不需要额外处理。
4. 登录状态的设计：Provider状态管理、Token存储与自动续期
4.1 为什么登录状态要独立管理
社区类App的登录状态贯穿整个生命周期：启动时判断是否有Token、请求接口时带上Token、Token过期时自动刷新、用户手动退出时清除所有登录状态。如果用setState在页面内管理，登录状态一变，所有依赖它的页面都要手动刷新，很快就乱成一团。Provider的好处是单一数据源，所有页面通过同一个状态对象读取登录态，变更时自动通知依赖方。
"享家社区"的登录状态模型分了三个层级：AuthState（当前登录用户信息）、AuthStatus（枚举：loading / unauthenticated / authenticated / expired）、AuthActions（login、logout、refreshToken、updateUserInfo）。UI层只关心AuthStatus和AuthState，具体网络请求细节全部封装在AuthActions里。这样登录页、个人中心页、请求拦截器三处共享同一个状态，不会出现"首页显示已登录，个人中心显示未登录"这种割裂问题。
4.2 Token的结构与安全存储
Token设计上，我们用了access_token + refresh_token双Token结构。access_token有效期2小时，refresh_token有效期7天。为什么不用单Token？小区门禁场景很特殊，用户可能每天进出小区多次，每次都用脸部识别，但如果哪天App请求发现access_token过期了又要重新输验证码登录，体验很差。refresh_token让App在后台静默续期，用户无感知。
存储方面，access_token、refresh_token、用户ID这几项不能直接用shared_preferences明文存。原因很简单：鸿蒙系统和Android一样，shared_preferences的数据落在应用私有目录里，不root本身是安全的，但登录态的完整性直接影响门禁权限和物业缴费功能，一旦被协议分析工具截取，用户可以伪造请求打开别人家的门禁。所以敏感信息我们用鸿蒙侧提供的安全存储能力，通过MethodChannel封装成Flutter侧一个token_manager工具类，对外只暴露read/write两个方法。
class TokenManager { static const MethodChannel _channel = MethodChannel('com.xj.community/token'); static Future<void> saveToken(String accessToken, String refreshToken) async { await _channel.invokeMethod('saveToken', { 'accessToken': accessToken, 'refreshToken': refreshToken, }); } static Future<String?> getAccessToken() async { final result = await _channel.invokeMethod<String>('getAccessToken'); return result; } static Future<void> clearToken() async { await _channel.invokeMethod('clearToken'); } }这个设计的好处是，如果后续要切换到Keychain（iOS）或更高级的安全方案，只需要改鸿蒙侧原生代码，Flutter侧完全不用动。
4.3 请求拦截与401自动刷新
登录态失效的处理是登录模块里最容易写崩的部分。很多项目直接在请求回调里判断401，然后跳转登录页，但这样做在并发请求场景下会出问题：用户在个人中心页一次发出三个请求，三个请求都带着已经过期的access_token，结果返回三个401，三次跳转登录页，用户还没看清就直接被弹回登录页，体验极差。
正确做法是统一的dio拦截器里做Token过期检测和刷新队列。思路如下：
class AuthInterceptor extends Interceptor { bool _isRefreshing = false; final List<Completer<void>> _waiters = []; @override Future<void> onError(DioException err, ErrorInterceptorHandler handler) async { if (err.response?.statusCode == 401) { if (_isRefreshing) { // 已有请求正在刷新Token，当前请求挂起等待 final completer = Completer<void>(); _waiters.add(completer); await completer.future; // 刷新完成后重试原请求 final retry = await _retryRequest(err.requestOptions); handler.resolve(retry); return; } _isRefreshing = true; try { final newToken = await AuthActions.refreshToken(); if (newToken != null) { // 更新全局Header里的access_token _waiters.forEach((w) => w.complete()); final retry = await _retryRequest(err.requestOptions); handler.resolve(retry); } else { // 刷新失败，重新登录 _waiters.forEach((w) => w.complete()); AuthActions.setStatus(AuthStatus.unauthenticated); handler.reject(err); } } catch (e) { _waiters.forEach((w) => w.complete()); handler.reject(err); } finally { _waiters.clear(); _isRefreshing = false; } return; } handler.next(err); } Future<Response> _retryRequest(RequestOptions options) async { // 复制原请求配置，更新Authorization头 final opts = options; opts.headers['Authorization'] = 'Bearer ${await TokenManager.getAccessToken()}'; return Dio().fetch(opts); } }这套逻辑的关键在于_isRefreshing和_waiters队列。第一个401触发刷新，后续的401等待第一个刷新完成后再重试，不会出现多个并发的刷新请求，也不会出现重复跳转登录页。实测在"享家社区"的联调环境里，一次刷新流程可以正确处理并发请求，Token刷新成功后所有排队的请求依次重试，用户无感知。
4.4 多端登录互踢的处理
社区App还有多端登录的需求：用户可能在手机上登录，又在平板上登录，门禁系统还可能下发一个临时会话。我们的处理方式是服务端维护一个会话列表，每次登录生成新的sessionId，旧会话做一次互踢下线。
互踢下线的通知机制用过两种方案：短轮询和WebSocket长连接。社区App的业务特点决定了登录态不能有明显的延迟感知，最终选的是WebSocket方案。后台服务在登录成功后建立WebSocket连接，服务端主动下发kick事件，Flutter侧通过EventChannel接收原生WebSocket回调，然后清理Token并跳转登录页，提示"您的账号在其他设备登录"。
这个方案的坑在鸿蒙上同样存在：WebSocket的断线重连机制需要自己实现。鸿蒙的WebSocket API（ohos.net.webSocket）在断线时不自动重连，需要监听onClose事件后手动发起新连接。Flutter侧接的是EventChannel，原生WebSocket在什么时候重连、重连失败怎么办，这些逻辑建议都放到原生侧，Flutter侧只负责收事件。如果放在Flutter侧，App切后台时WebSocket容易假死，回到前台时状态不对，处理成本很高。
5. 鸿蒙原生能力桥接：验证码通道、安全键盘与权限
5.1 MethodChannel：调用鸿蒙原生短信能力
Flutter调用鸿蒙原生的能力，靠的是MethodChannel，这一点和Android保持一致。但鸿蒙侧有一个架构差异：Android的MethodChannel是通过MainActivity里的onCreate获取FlutterEngine，然后注册channel handler；鸿蒙侧则需要在UIAbility的窗口加载Flutter页面后，通过FlutterEngine实例注册channel handler。
"享家社区"的短信验证码SDK是鸿蒙原生实现的，接入方式是在鸿蒙侧注册一个名为com.xj.community/sms的MethodChannel，暴露sendCode和verifyCode两个方法。Flutter侧通过invokeMethod调用，传参包括手机号、场景类型（登录/注册/重置密码），鸿蒙侧返回操作结果。
这里有一个非常容易踩的坑：MethodChannel的调用超时。鸿蒙侧如果接到MethodChannel调用后要弹窗让用户确认或等待网络回调，必须及时返回结果，否则Flutter侧的Future会一直挂着，用户以为是卡死了。正确做法是鸿蒙侧MethodChannel方法里做成异步，立即返回"已受理，结果稍后通过EventChannel回传"，异步结果再通过EventChannel推送。这和Android上MethodChannel的推荐用法其实是一样的，但鸿蒙分支上更容易踩到，因为鸿蒙原生的异步回调链比Android多了一层。
5.2 EventChannel：订阅验证码与登录生命周期事件
EventChannel在"享家社区"里承担两类事件：一是短信验证码结果事件，二是账号互踢下线事件。
验证码SDK在鸿蒙侧收到服务端下发短信的结果后，原生代码把结果透传给EventChannel，Flutter侧在登录页面订阅这个流，更新倒计时状态和错误提示。要注意EventChannel的生命周期管理：页面销毁时要取消订阅，否则又会遇到"旧页面还在监听，新页面重复弹Toast"的经典问题。
鸿蒙侧推送互踢事件时，Flutter侧需要判断当前页面栈。如果用户正在登录页，那说明账号本身还没登录成功，互踢事件应该被忽略；如果用户正在首页或缴费页，则执行强制登出并跳转登录页。这个判断放在Provider里做，EventChannel只负责把原生事件翻译成Dart对象，业务逻辑上层决定。
5.3 鸿蒙权限申请与Android的差异
登录页涉及的权限不多，但如果需要获取设备信息用于风控和设备绑定，就会牵扯到权限申请。Android上用的是permission_handler插件，一键申请；鸿蒙分支上这个插件不可用，需要原生实现。
鸿蒙的权限模型与Android差异很大。Android的权限途径是在AndroidManifest.xml里声明uses-permission，运行时再动态申请。鸿蒙在module.json5的requestPermissions节点里声明权限，然后通过abilityAccessCtrl的requestPermissionsUserGrant方法发起动态申请。如果没有声明直接在运行时申请，鸿蒙会直接静默拒绝，不留任何错误提示，排查起来非常费劲。
"享家社区"在这块遇到的具体问题是：鸿蒙纯血版把Device ID这类标识符默认收紧了，不申请ohos.permission.READ_DEVICE_INFO就只能拿到模糊的设备信息。我们最初用这个模糊信息做设备绑定，结果同一台设备在不同时间上报的设备指纹不一致，导致"登录有效，但门禁服务端认为设备未绑定"的怪问题。后面统一改成鸿蒙提供的唯一设备标识API，不再依赖AndroidIMEI那套逻辑，问题才解决。
5.4 安全键盘和输入法覆盖问题
鸿蒙系统对键盘安全性的要求比Android严格，系统默认有自己的安全键盘，可以防止第三方输入法窃取输入内容。但Flutter的TextField在鸿蒙弹安全键盘时，出现了几个奇怪的表现：一是安全键盘弹起后，输入框的光标会变得不可见；二是安全键盘偶尔会盖住输入框底部；三是字符录入在安全键盘下会有明显的延迟。
从"享家社区"的实测看，鸿蒙的安全键盘在Flutter内确实不如普通输入法稳定。我们的过渡方案是：登录页的验证码输入框不强制走安全键盘，而是接受系统默认输入法，因为验证码本身有时效性和校验码逻辑，即使被输入法读取也无法二次使用；但对于支付密码类输入框，则完全使用自绘的数字键盘，不依赖系统输入法，确保安全。两个场景分开处理，既保证安全又兼顾体验。
6. 联调中遇到的高频问题：错误码、超时与弱网
6.1 登录接口的错误码需要统一映射
登录接口联调起来比想象中费劲，原因在服务端返回的错误码和客户端判断逻辑对不上。比如服务端返回602表示"验证码已失效"，603表示"验证码错误"，604表示"手机号未注册"，613表示"操作频繁请稍后再试"，这些数字在服务端文档里各自有完整定义，但客户端如果直接把数字展示给用户，体验会很抽象。
"享家社区"在Flutter侧做了一层错误码映射：网络层拿到业务状态码后，统一转成App自定义的AuthError枚举，UI层根据枚举展示对应提示文案。这层映射同时承担了下发埋点的职责——每一次登录失败，错误码和失败原因会打到日志系统，方便运营侧发现问题，比如某段时间验证码短信通道出现大面积延迟，就是从错误码统计里发现的。
6.2 超时重试要区分幂等操作
登录接口的超时设置不能拍脑袋。验证码请求和登录请求两者性质不同：验证码请求是幂等操作，重复发送不会产生数据错误，所以超时后可以重试；但登录请求如果超时后重试，服务端会重新校验验证码，存在"第一次请求成功但响应超时，第二次重试又触发一次校验"的情况，极端情况下会白白消耗一次验证码。
我们的策略简单明确：验证码请求超时设置为10秒，允许自动重试1次；登录请求超时设置为15秒，不自动重试，超时后弹出提示让用户手动再点一次。这个设置经过测试后，实际体验比"全部自动重试"要稳定，因为少了很多重复校验导致的混乱。
6.3 弱网下的登录成功回调丢失
这是"享家社区"上线前压测时发现的一个边界问题：用户在电梯里点登录，请求实际已经到达服务端并成功创建了会话，但响应包在弱网下没有回到客户端，客户端显示"网络异常请重试"。用户再点一次，服务端提示"验证码已使用"，用户一脸懵。
处理方案分成两步。第一步，客户端在登录请求超时后，不立刻判定失败，而是先把"登录请求已发出但结果未知"这个状态缓存到本地，提示用户"如果登录成功，请勿重复操作"。第二步，客户端提供一个"刷新登录状态"的静默接口，用户重新联网后可以去服务端查会话是否已建立，如果已建立则直接恢复登录态。这套机制不算复杂，但对小区这种弱网场景帮助极大，减少了很大一部分客诉。
7. 上线前的回归清单：鸿蒙真机上最容易翻车的几个点
7.1 冷启动闪退与热重载失效
鸿蒙分支的Flutter在热重载失效这个问题上基本是随机出现的。开发期影响效率，但上线前影响更大的是冷启动闪退。我们排查过的闪退原因集中在两类：一是某些三方库在鸿蒙上的原生实现缺失，比如某SDK引用了Android的Build.VERSION.SDK_INT常量，在鸿蒙上拿不到，直接NPE；二是Flutter engine在鸿蒙上的内存布局差异，导致同一个页面在Android正常，在鸿蒙上OOM。这些都要逐个库在鸿蒙真机上回归。
如果团队没有专门的鸿蒙测试组，最实际的做法是上线前置备一台鸿蒙手机作为必测设备，每一次发版前至少跑一遍登录、首页、缴费、报修全流程。这四个流程覆盖了90%的住户日常操作，只要它们不崩，其他低频功能可以后续补测。
7.2 系统返回键与手势冲突
Android返回键天然被Flutter处理，但鸿蒙上返回键的逻辑不同：页面返回会触发Flutter的PopScope（旧版本叫WillPopScope），如果不加处理，用户在登录页按返回键会直接退出App。在"享家社区"里，登录页的返回键行为要和当前状态联动：如果当前没有执行网络请求，允许退出；如果正在请求中，拦截返回并提示"登录中请稍候"。
这段逻辑在Android上写好后一次通过，鸿蒙上测试发现PopScope的回调时机和Android不同——鸿蒙在页面已经退出后才调用回调，导致拦截失效。后面通过改用RouterPage的能力在原生侧拦截返回事件，再转发给Flutter判断，最终才做到两端行为一致。
7.3 App后台切换后登录态失效
鸿蒙的后台调度策略比Android更严格，App进入后台一段时间后，进程可能被系统冻结甚至杀掉，恢复前台时需要重新检查登录态。如果只是简单地在AppLifecycleState.resumed事件里判断Token是否还有效，用户切后台再切回来，所有页面都会经历一次重新加载，体验很差。
"享家社区"的方案是：resumed时先静默检查refresh_token的有效期，如果refresh_token还有效，则保持当前页面栈，只在后台刷新access_token，用户无感知；如果refresh_token也过期了，则只能跳登录页。这个方案的实测效果是，App在后台挂一小时再切回来，登录态基本不会丢，用户不需要重新登录。
7.4 升级与降级兼容
最后聊一个很少有人关注但真实存在的问题：鸿蒙设备的系统升级路径。鸿蒙从API 11升到API 12后，部分原生API的返回值格式发生了变化，比如设备唯一标识从26位字符串变成了32位，如果客户端代码里硬编码了长度校验，升级后会突然出现"设备校验失败"。
我们的做法是给设备标识的解析逻辑加自适应：不校验数字位和长度，只校验是否非空，拿到什么存什么，下次使用重新获取。同时在做版本兼容时，尽量不在Flutter侧维护鸿蒙API版本的判断逻辑，所有版本判断都放原生侧，Flutter侧拿到的永远是统一的返回格式。这套原则执行了一年，后续多款机型升级系统后没有出现设备绑定相关的问题，算是回头补课补对了一回。
