Flutter与OpenHarmony跨端实践：从会员状态卡片到模块化架构

这个项目最后不是一张卡片的事，而是一场被卡片逼出来的跨端架构决策。Flutter 和 OpenHarmony 这套组合，在我实际负责的健身俱乐部会员端项目里，是从一张会员状态卡片开始出现的：前台要用它确认开卡、门禁一体机要用它验票、教练的平板要提醒哪节课该催哪个会员续费，到了后台 App 里，运营又要看同一份状态做账。真正做完我才意识到，如果把“会员状态组件”当成一个普通 Widget 写死，那它只能撑过第一台设备，撑不过第二台、第三台。

所以这篇文章不打算只给你看一个“漂亮的会员卡片”。我会完整讲一讲我是怎么从单张卡片的 UI 建模开始，一路把状态机、数据源抽象、跨端桥接、RK3568 真机调试和模块化重构成一条清晰的链路。内容更适合已经在做 Flutter、正要接触 OpenHarmony 设备，或者正在把某个“看着很小的业务组件”往业务系统方向做的团队。踩坑过程尽量写细，能帮你省几天时间。

1. 同屏困境：会员状态到底要出现在哪几个屏幕上

1.1 会员在健身房里会被“看”几次

先看一个典型场景。会员进门，第一步是在前台或者自助签到机上扫描会员码，机器要显示“当前是正常会员、还有几天到期”；前台工作人员确认之后放行。随后教练可能打开排课平板看一眼，系统如果发现这个会员即将到期，需要在会员资料旁边显示“只剩 3 天”的提醒。会员自己在手机上打开 App，看到的又是同一份状态。如果当天他临时提出冻结一个月，前台后台状态一起变。

这些设备里，签到机是一块竖屏触摸一体机，教练拿的是普通安卓平板，手机会员端跑 iOS/Android，而签到一体机因为采购渠道问题，跑的是 OpenHarmony 系统，底层芯片是 RK3568。如果按传统方案，安卓端写一套原生页面，一体机那边再让设备厂商配合改一套，结果就是两个团队维护两套 UI，每次业务状态新增一种颜色、一个新按钮文案，两边都要同步改。

1.2 为什么不是 H5，而是 Flutter 套一个 OpenHarmony 壳

有人会本能地问：这种状态卡片直接用 H5 做不是更省事吗，反正什么设备都有浏览器或者 WebView。第一次需求评审时我也这么想过，但后来发现三个问题。

第一个是离线问题。健身房前台经常断电重启网络设备，如果签到机完全依赖网页在线渲染，网络一抖会员就进不了门。Flutter 本地首帧渲染可以做到把最近一次已知状态缓存下来，即使断网也能显示“上次有效状态”，更符合门禁场景。

第二个是外设生态问题。真机上除了展示，还要接二维码扫描器、小票打印机、NFC 读卡器。H5 在浏览器沙箱里调用这些设备能力很别扭，而 Flutter 可以通过平台通道把能力下沉到 OpenHarmony 的原生侧。

第三个是 UI 一致性。Flutter 的组件树本来就是声明式的，主题系统成熟，做一套组件再通过 widget 尺寸适配，比维护两套 Web 页面更可控。最终我们决定的打法很直白：手机、平板、一体机上跑同一套 Flutter UI，OpenHarmony 只作为 Flutter engine 的运行底座。

1.3 Flutter 应用真的能在 OpenHarmony 上跑吗

这里必须先把一个容易混淆的问题说清楚。我们平时下载的官方 Flutter SDK 默认只支持 Android、iOS、Web、Windows、macOS、Linux 这几个平台，直接运行 flutter create 是看不到 OpenHarmony 选项的。社区方案是使用 OpenHarmony SIG 维护的 Flutter SDK 分支，用它替换掉本地 SDK，然后工程里才会出现 ohos 平台。

构建方式也不像 Android 出 APK 那样简单。用 flutter build hap 之后，产出的构建物是 OpenHarmony 的应用包 .hap，再通过 hdc 工具安装到开发板上。这个替换过程属于“环境搭建硬伤”，我后面单独讲。

这一段的结论很关键：难点不在 Flutter 侧，而在你必须在没有全套官方文档兜底的情况下，自己把设备选型、系统镜像、签名、依赖版本全都串起来。能串通，你的组件才能在 RK3568 这一类设备上稳定跑起来。

2. 状态不等于“还剩几天”：先定义会员状态机和切换路径

2.1 一张会员卡片背后到底有几种状态

需求文档最初写的是“显示会员是正常还是过期”，看着像个布尔值。但健身行业里的会员状态远不止这两种。我第一次梳理后端返回的状态码时，列出来至少有这 7 种。

最开始我只拿了 active 和 expired 两个字段进 UI，结果测试阶段就发现漏了：一个会员处于 expiring 状态时，卡片上还在显示绿色“正常”；另一个会员刚退卡，前端缓存里还挂着“正常”，结果一体机直接放行。这个教训告诉我，卡片组件在设计之前，必须先有一份状态定义，而且这份定义必须只来源于后端状态机。

2.2 客户端千万别自己去算“还有几天到期”

我见过很多团队喜欢在前端拿到一个 expireAt 后直接 DateTime.now() 相减，然后自己画状态。放到一般会员应用里问题不大，但在健身俱乐部里会出大问题，因为会籍有“冻结延期”规则。

举例：会员有效期原本是 2025 年 6 月 1 日到 2026 年 6 月 1 日，他中途出国休假一个月，申请了 2026 年 2 月 1 日到 3 月 1 日冻结。有效截止日应该自动顺延到 7 月 1 日。这个顺延逻辑可能在后台由规则引擎处理，也可能由运营手工改，客户端其实根本拿不到完整的冻结区间历史，所以拿 expireAt 死算就会在边界上出错。

我们的做法是让后端返回一个权威的状态快照：

dart复制class MemberStatusSnapshot {
  final String memberId;
  final String memberName;
  final String avatarUrl;
  final String levelName; // 例如 银卡 / 金卡 / 私教课包
  final MemberStatus status; // 上面定义的枚举
  final DateTime? validUntil; // 状态对应的截止时间
  final int remainingDays; // 后端已经算好的剩余天数
  final DateTime serverUpdatedAt; // 快照产生时间
}

客户端只负责展示这个快照，不负责推导。我知道这听起来像是把责任推给后端，但实际线上问题会少很多。remainingDays 可以为负数，一旦小于 0，说明后端状态还没来得及刷新，UI 不应该自己再改成 expired，而是等下一次轮询更新。

2.3 状态切换不是随便跳的，要画清楚每一条路径

状态机一旦进了设计阶段，就要把允许的切换路径写出来，否则前端代码里会出现大量“如果过期了就刷新成 active”之类的不合规逻辑。我整理了一套最常用的切换规则：

dart复制class MemberStatusTransition {
  static MemberStatus? next(MemberStatus current, MemberStatusEvent event) {
    return switch (current) {
      MemberStatus.pending => switch (event) {
        MemberStatusEvent.activate => MemberStatus.active,
        _ => null,
      },
      MemberStatus.active => switch (event) {
        MemberStatusEvent.expired => MemberStatus.expiring,
        MemberStatusEvent.freeze => MemberStatus.frozen,
        MemberStatusEvent.withdraw => MemberStatus.withdrawn,
        MemberStatusEvent.risk => MemberStatus.blacklisted,
        _ => null,
      },
      // ... 其余状态同理
      _ => null,
    };
  }
}

这套代码不复杂，核心价值是让非法状态转换在编译期和测试期就被兜住。比如某天后端接口异常，直接返回了一个“expired 续费成功后不经过 expiring 直接 active”的结果，我们在 UI 层至少能判断出事件顺序可疑，记录一条 error 日志而不是傻白甜地相信。

要注意的是，UI 并不是每分每秒都去触发状态机。大部分状态切换发生在后端，前端只是定期拉取结果。真正的“状态自更新”只有一件事需要处理，那就是跨午夜。

2.4 到了午夜，卡片要自己从不提醒变成“今日到期”

这是最容易漏的细节。会员剩余 1 天，今天 23:59 还显示“剩 1 天”，零点整应该立刻变成“已过期”或“剩 0 天”。如果你只在页面 push 时拉一次数据，那一个通宵留在签到机上的界面就会一直显示错误的剩余天数。

解决的办法不是每秒刷新，而是用一个精确定时器等到下一个 0 点：

dart复制Duration _durationUntilNextMidnight() {
  final now = DateTime.now();
  final nextMidnight = DateTime(now.year, now.month, now.day + 1);
  return nextMidnight.difference(now);
}

void _scheduleMidnightRefresh() {
  _timer?.cancel();
  _timer = Timer(_durationUntilNextMidnight(), () {
    debugPrint('跨天，刷新会员状态');
    _refresh();
    _scheduleMidnightRefresh();
  });
}

这个 Timer 必须在组件 dispose 时取消，否则页面关掉后还会触发状态更新回调，造成无谓的网络请求。更稳妥的做法是把刷新动作放在数据层，不让卡片组件本身持有 Timer。

3. 卡片组件只做一件事：把状态快照稳定地渲染出来

3.1 组件的对外契约，决定了它能活多久

很多人写“会员状态卡片”时，喜欢把所有业务判断都塞进 Widget 里：状态是过期就跳续费页、状态是冻结就弹窗、状态是黑名单就调接口拉黑。一开始很爽，到第二个业务方要用这个卡片时就完蛋了，因为第二个业务方根本没有续费页面，也不需要弹窗。

我后来把组件边界收敛成了一条铁律：卡片只接收状态快照，只负责渲染，所有动作通过回调抛给上层业务方决定。

dart复制class MemberStatusCard extends StatelessWidget {
  const MemberStatusCard({
    super.key,
    required this.snapshot,
    this.onTap,
    this.onRenew,
    this.onContactStaff,
    this.pattern = MemberCardPattern.regular,
  }) : super(key: key);

  final MemberStatusSnapshot snapshot;
  final VoidCallback? onTap;
  final VoidCallback? onRenew;
  final VoidCallback? onContactStaff;
  final MemberCardPattern pattern;

  @override
  Widget build(BuildContext context) {
    final visual = _visualFor(snapshot.status, context);
    return Card(
      child: ListTile(
        leading: CircleAvatar(backgroundImage: NetworkImage(snapshot.avatarUrl)),
        title: Text(snapshot.memberName),
        subtitle: Text(visual.description),
        trailing: _buildAction(context, visual),
        onTap: onTap,
      ),
    );
  }
}

onRenew 具体是跳转支付页面、还是打开续费商品页、还是弹窗告诉前台这个会员不符合续费条件，完全由调用方决定。卡片组件自身不写任何 Navigator.push 和 showDialog。这样同一套卡片才能同时用在手机 App、前台平板以及签到一体机上。

第三方的“续费动作”在这个业务域里差异巨大。手机端用户可能是自己在线续费；前台人员点同一个按钮，可能只是帮会员做一个延期申请。动作一样，但主体不一样，权限不一样，UI 的后续流程必然不同。只有让他们从回调里各自处理，组件才能通用。

3.2 状态和颜色不能散落在 build 方法里

新手容易写出这样的代码：

dart复制if (status == MemberStatus.expired) {
  color = Colors.red;
}

第一次没问题，第二次要分深浅色模式，第三次要支持品牌色切换，这个 if 就膨胀到没法看了。我们把状态对应的视觉描述收敛成了一个独立映射：

dart复制class MemberStatusVisual {
  const MemberStatusVisual({
    required this.label,
    required this.color,
    required this.icon,
    required this.description,
  });
  final String label;
  final Color color;
  final IconData icon;
  final String description;
}

MemberStatusVisual _visualFor(MemberStatus status, BuildContext context) {
  final scheme = Theme.of(context).colorScheme;
  return switch (status) {
    MemberStatus.active => MemberStatusVisual(
        label: '正常',
        color: scheme.primary,
        icon: Icons.check_circle,
        description: '可正常入场',
      ),
    MemberStatus.expiring => MemberStatusVisual(
        label: '即将到期',
        color: Colors.orange.shade600,
        icon: Icons.schedule,
        description: '剩余 ${snapshot.remainingDays} 天',
      ),
    // ... 其他状态
  };
}

这里有一个容易被忽略的点：正常状态的颜色不要直接写 Colors.green，而是用 Material 的 colorScheme.primary。为什么？因为业务 App 可能切换品牌主题，或者进入深色模式，绿色的对比度在某些背景上并不理想。只有“提醒性”状态，例如 expiring、expired、blacklisted，才应该有强烈的语义色，因为这些颜色在深色和浅色模式下都要保持统一警示。

3.3 刷新逻辑放在数据层，而不是卡片里

会员在签到机上扫码后，卡片会先显示本地缓存的上一份快照，同时网络层开始请求最新状态。等网络返回新快照，整个页面再更新。这个过程通常由 Riverpod 或者 Provider 管理，卡片组件本身应该保持无状态，这样单个组件就能做 golden test 和 widget test：

dart复制await tester.pumpWidget(
  MaterialApp(
    home: Scaffold(
      body: MemberStatusCard(
        snapshot: MemberStatusSnapshot(
          memberId: '001',
          memberName: '李小雨',
          status: MemberStatus.expired,
          remainingDays: -1,
        ),
        onRenew: () {},
      ),
    ),
  ),
);

expect(find.text('已过期'), findsOneWidget);

这种设计真正带来收益是在组件库沉淀之后。后来运营那边要做一个“会员列表页”，列表里的每一行其实也是一张更紧凑的会员状态卡片。我们基于同一个快照模型，只是换了一个 pattern，渲染成更矮的列表行，测试用例几乎全部复用。这就是从一张卡片变成一套小系统的第一个标志。

4. 跨端数据链：从 API、本地缓存到外设读头的数据源抽象

4.1 健身房里断网，状态卡片也得说话

项目接入一体机时，第一个被提出的硬性需求是“断网不能直接放行”，也不能因为网络抖动把会员卡在门外。更合理的是：如果一体机最近一次见过这个会员，并且知道他是正常状态，那么断网后短时间内仍然显示正常；如果缓存里是已过期，断网也绝不允许改判成正常。

所以数据源这一层不能直接让页面去 http.get。我们需要定义一个仓库接口，上层不知道数据将来自远端、本地缓存，还是某一个外设：

dart复制abstract class MemberStatusRepository {
  Future<MemberStatusSnapshot?> fetchStatus(String memberId);
  Stream<MemberStatusSnapshot> watchStatus(String memberId);
  Future<void> refreshStatus(String memberId);
}

接口写起来很简单，但它强制了所有调用方都走同一条读取通道。最开始的签名里我甚至没有 refreshStatus，结果发现签到机页面手动下拉刷新时直接调了 fetchStatus，而轮询又用另一个方法，数据更新源不统一，容易造成 UI 竞态。

4.2 远端和缓存分别实现，再用组合模式串起来

远端实现是常规 REST 请求：

dart复制class RemoteMemberStatusRepository implements MemberStatusRepository {
  final Dio _dio;

  @override
  Future<MemberStatusSnapshot?> fetchStatus(String memberId) async {
    final response = await _dio.get('/v1/members/$memberId/status');
    return MemberStatusSnapshot.fromJson(response.data);
  }
}

缓存实现就不能只存最后一份 JSON 了，还要记录快照时间和服务端版本。网络返回的顺序有时候会乱，比如同一个会员先请求了 A 版本，又请求了 B 版本，结果 B 先回来，A 后回来。如果无脑用最后到达的覆盖，页面就会闪回旧状态。所以我们给快照加了一个单调递增的 snapshotVersion，只有新版本大于当前版本时才覆盖。

组合方式用了一个简单的包装类：

dart复制class CachedMemberStatusRepository implements MemberStatusRepository {
  CachedMemberStatusRepository(this._remote, this._cache);

  final MemberStatusRepository _remote;
  final LocalStatusCache _cache;

  @override
  Future<MemberStatusSnapshot?> fetchStatus(String memberId) async {
    final cached = _cache.read(memberId);
    if (cached != null && !_cache.isExpired(memberId)) {
      return cached;
    }
    try {
      final remote = await _remote.fetchStatus(memberId);
      if (remote != null) {
        _cache.write(memberId, remote);
      }
      return remote;
    } catch (_) {
      // 断网时返回缓存
      return cached;
    }
  }
}

缓存过期时间不能设成一刀切。手机 App 里我会设成 5 分钟，因为用户可能随时买课续费，状态变化快；签到一体机上我会设成 15 秒，因为它的首要任务是防冒用，过期时间短一点更安全。缓存里存姓名和头像时还需要额外考虑隐私问题。一体机是公共设备，会员离开后不能把上一个会员的头像留在界面上，所以在页面退出或者超时后，组件要执行一次“清屏”，把内存中的状态快照置空。

4.3 外设接入会打破你“一套 Flutter 走天下”的幻想

门禁一体机上的二维码扫描器算是类 HID 设备，比较好处理。但如果我们想用 USB 读卡器读取会员卡，或者用 NFC 模块直接读卡，就不能只靠 Flutter 层面的插件了，因为市面上的 Flutter 插件普遍基于 Android embedding 实现，在 OpenHarmony 上没有对应的原生实现。

我们的最终方案是缩小原生桥面，只暴露一个非常窄的接口给 Dart：

dart复制class MemberCardReader {
  static const MethodChannel _channel = MethodChannel('club.device/member_card');

  Future<String?> readCardId() async {
    try {
      final String? cardId = await _channel.invokeMethod('readCardId');
      return cardId;
    } on PlatformException catch (e) {
      debugPrint('读卡失败: ${e.message}');
      return null;
    }
  }
}

在 Android 端，readCardId 由对应的 Activity 实现；在 OpenHarmony 端，则需要自行写一个 Ability 或者原生插件去调用系统 USB 服务。这里我踩过很深的坑就是：不要试图在 Dart 层针对 targetPlatform 写两套逻辑。Dart 层只需要知道读卡结果是成功还是失败，把真正的平台差异藏在 MethodChannel 后面。否则将来再增加一个新设备，你的业务代码会被各种 if(targetPlatform == ohos) 打满。

如果不想做原生插件，还有一条备选路径：把读卡器厂商的 SDK 直接跑在 OpenHarmony 上，看它是否提供了 ArkTS 接口。不少国产 USB 读卡器本身只是串口转 HID，OpenHarmony 上不一定有好用的现成库。这个工作越早验证越好，不要等 UI 全做完了才发现设备能力不满足。

5. RK3568 真机适配记录：设备树选择、签名与 hdc 排障

5.1 先确认板子能正常开机，再谈 Flutter 代码

在 OpenHarmony 的 RK3568 开发里，最常见的“假性环境问题”是：开发板拿了三块，系统镜像刷上去了，其中一块屏幕亮，另一块屏幕不亮，还有一块以太网不通。查到最后，问题出在设备树（device tree）选型上。

RK3568 在 OpenHarmony 社区里一套源码支持很多开发板，这些板子虽然主控一样，但内存颗粒、显示面板、以太网 PHY、GPIO 扩展都不同，所以内核里存在不止一份 dts/dtb。如果你是做应用层开发的，千万不要自己从 dts 文件名猜“哪个更接近我的板子”。正确做法是看开发板厂商提供的 product 型号和配套镜像，编译时通过产品配置指定，而不是手动替换 dtb。

bash复制# 以社区通用编译命令为例，不同版本可能不同
./build.sh --product rk3568

我后来养成了一个习惯：拿到项目的第一件事不是 flutter run，而是先确认设备的系统版本、内核启动日志、屏幕触摸和网络是否正常。如果在系统层都没有确定好板子配置，后面所有 Flutter 调试都会建立在沙地上。真机上一旦出现 Flutter 应用闪退，先看是不是系统镜像本身不稳定，而不是怀疑 Flutter 代码。

5.2 签名问题：不是“开发板就能随便装包”

OpenHarmony 的应用安装比 Android 严格。就算你只是调试，也经常需要一个签名过的 hap 包才能安装到设备上。第一次拿到错误日志的时候，我以为是包没编对，后来才发现是签名证书没配好。

社区通用做法是在 DevEco Studio 里配置自动签名，逻辑跟 Android 配置签名文件差不多，但 OpenHarmony 的证书体系和 Android 不是一套。开发阶段我们维护了两套包：一套用于手机端正常的 Flutter 构建，另一套专门为 OpenHarmony 一体机做签名构建。刚开始不想把签名文件提交进 Git，结果每个新同事加入调试都要重新配一遍，后来还是在内部文档里写清步骤，隐私文件单独走内部存储，不放进公开仓库。

5.3 hdc 连不上时，按这个顺序排查

OpenHarmony 的调试连接工具是 hdc，它对应 Android 世界里的 adb，但两边命令格式有差异。最常见的场景是输入 hdc list targets 后没有任何设备输出。我按以下顺序排查，几乎能解决 90% 的问题：

1. 换数据线。很多 Type-C 线只有充电能力，没有数据线。
2. 在开发板上打开开发者模式，并明确开启 USB 调试。
3. 确认当前 USB 口不是那种只给屏幕供电的口。
4. Linux 机器上检查 udev 规则是否放行，Windows 上检查设备管理器驱动。
5. 尝试 hdc kill 再 hdc start，重新拉起 hdc server。
6. 如果 USB 始终不稳定，直接用网络调试：hdc tconn <ip>:<port>。

bash复制hdc list targets
hdc install -r path/to/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.memberclub

hdc 安装成功后，如果应用秒退，可以通过 hilog 查看 Flutter 引擎输出：

bash复制hdc shell hilog | grep flutter

很多闪退问题其实是 Flutter 引擎版本和设备上 OpenHarmony 系统版本不匹配导致的。比如引擎用了比较新的 API，但设备系统镜像停留在旧版本。遇到这种情况，优先对齐 Flutter SDK、engine 和设备的 OpenHarmony 版本，而不是去改代码。

5.4 性能实测：一块简单卡片在 RK3568 上的表现

RK3568 属于中低端 SoC，但仅仅渲染一张状态卡片，完全没有性能压力。真正会让你觉得“卡”的往往是另外两个东西：首帧之前的网络图片加载，以及页面切换时的阴影和模糊效果。

会员头像全部通过 NetworkImage 加载，如果一体机网络慢，打开页面后头像位置会先空白一下。后来我把头像压缩到 96x96 的本地尺寸，并且提前在启动页预加载最近一位会员的头像缓存，首帧体验才稳定。另一个性能坑是 Flutter 容器在低端设备上的阴影绘制。列表项里的 Card 默认 elevation 会触发额外绘制，数量一多就有掉帧可能。实测后我们把签到机页面的卡片阴影关掉，改用 1 像素边框，肉眼几乎无差别，帧率明显更稳。

6. 从“一张卡片”抽成“一套系统”的模块化重构清单

6.1 先拆 domain，再拆 ui，最后才考虑平台工程

卡片组件在手机端跑通、一体机跑通之后，我意识到如果继续把状态模型、仓库实现、页面代码都堆在同一个 App 工程里，“复用”只是一句空话。真正的分水岭是单独拎出两个 flutter package 级别的模块：一个是纯 Dart 的领域模块，没有任何 Flutter 依赖，另一个是 UI 模块，依赖前者的模型，但只暴露组件。

一个可视化的目录结构是这样：

code复制member_domain/      # 纯 Dart，模型、状态枚举、状态机、仓库接口
member_data/        # Flutter/Dart 混合，包含 Dio、本地缓存、MethodChannel
member_ui/          # 专属会员卡片组件库
club_kiosk/         # 签到一体机主工程
club_mobile/        # 手机端主工程

这个拆分最直接的效果是：手机端和一体机端不能共享同一个物理代码路径，但它们能引用同一个 member_ui 包。后续任何状态展示的修改，例如增加“仅剩 3 天”的红色提醒，只需在 member_ui 里改一次。

同时，因为 member_domain 是纯 Dart 模块，Dart 单测可以在没有设备模拟器的情况下秒跑。这个优势在多人协作时尤其重要，CI 里只需要跑 dart test 就能快速验证状态机逻辑。

6.2 接口下沉，让 UI 包不反向依赖业务包

重构遇到的最大阻力其实是“依赖方向”。最自然的写法是 UI 组件 import 主工程里的各种 service，结果 UI 包和业务代码耦合，根本没法独立发版。我们后来把组件需要的所有数据都收敛到了 MemberStatusSnapshot 这一个不可变对象里，组件不直接认识 Dio、不直接认识 Firestore、不直接认识 MethodChannel。

一个实用的约定是：member_ui 包里禁止出现 http、MethodChannel、SharedPreferences 这三类依赖。所有交互一律通过构造函数传入的回调完成。这个约定听起来严格，但让 UI 包能独立做视觉回归测试。到后面我们甚至可以在一个纯 mock 快照集合上跑视觉验收，不需要任何后端连调环境。

6.3 同一个状态，在不同屏幕上要有不同的布局密度

从单张卡片到系统，另一个绕不开的问题是设备差异。手机 App 里可以放一张很大的卡片，包含头像、等级、状态说明、续费按钮；签到一体机屏幕上同样是这个卡片，但它希望信息一眼看全，按钮尽量大；后台管理列表里则只想要一行紧凑的状态。

我们在 UI 包中引入了一个 MemberCardPattern 枚举：

dart复制enum MemberCardPattern { full, compact, listTile }

组件内部通过 pattern 选择不同布局，但数据模型永远只有一份。这样设计避免了“列表里写死一个小卡片组件，详情页再复制一份大卡片”的情况。一个后续想接入第三方场馆看板