FlutterUnit v3.4.2 全端用户系统深度解析账号体系、头像荣誉、任务成就与匠心工坊【免费下载链接】FlutterUnitAll Platform Flutter Experience App项目地址: https://gitcode.com/GitHub_Trending/fl/FlutterUnit本篇以 FlutterUnit v3.4.2 版本发布说明为骨架结合仓库内modules/basic_system/authentication模块的真实源码逐条拆解本次全端更新的技术内涵用户账号系统的登录与会话管理、头像框与徽章的装配机制、每日任务与生涯成就的进度模型、以及用匠尘兑换虚拟荣誉的匠心工坊。读完本文你将不仅了解 v3.4.2 新增了哪些功能更能掌握这些功能在 Flutter 工程中的模块化实现方式BLoC 状态管理 Repository 数据层 服务端接口约定以及它们如何协同支撑一个跨 Android、iOS、桌面端Windows/macOS/Linux和 Web 的全平台体验应用。一、版本总览v3.4.2 更新了什么根据 doc/version/3.4.2.md 的发布说明本次版本的核心是全端用户体系的落地共包含 9 项要点上线用户账号系统完善登录、资料编辑与账号管理新增头像框与徽章可预览、装配并更换自定义头像新增每日任务与生涯成就完成任务可领取匠尘及荣誉奖励新增匠心工坊可使用匠尘兑换头像框和徽章并查看兑换记录优化桌面端我的账号、收藏与任务入口完善用户系统、任务成就及工坊的中英文显示优化工具宝库与组件 Logo 展示。这 7 条表面上是功能清单在源码层面则对应着authentication模块下四个清晰的功能子域会话与账号user / runtime、荣誉honors、进度progression、工坊workshop。下文按此脉络展开。二、用户账号系统登录、资料编辑与账号管理v3.4.2 的核心底座是用户账号系统它让收藏同步、任务进度、荣誉装配等能力有了身份前提。2.1 会话与凭据的宿主组装会话层由 user_runtime.dart 中的FlutterUnitUserRuntime统一组装。从源码看它基于 FrameworkX 的用户 SDK 构建FxUserSessionCubit承载登录状态机通过HttpFxUserRepository走 HTTP 认证接口FxPreferencesUserStore命名空间flutter_unit负责本地持久化凭据与快照HttpFxAvatarUploadTask负责头像上传注册了一个 Dio 拦截器当请求返回401且失败请求携带的Authorization头与当前BearerCredential一致时自动触发users.handleUnauthorized()实现失效凭据的统一续期/登出。值得注意的细节是_onCredentialChangedSDK 的凭据变化会被同步到UnitEnv.accessToken从而让 FlutterUnit 自己的统一请求 HostFxDio()FlutterUnitHost()自动携带认证头。也就是说登录态不是散落在各个页面里的而是通过全局单例 拦截器一条链路贯通的。2.2 登录与资料编辑的界面实现登录入口移动端 login_page.dart 提供 GitHub 登录与验证码登录两条路径文案群英荟萃匠心者也与错误提示验证码错误/失效、频率限制、邮箱格式、账号密码错误等均来自 app_zh.arb 的国际化键。资料编辑user_edit_name_page.dart与user_edit_signature_page.dart分别承载用户名最多 50 字符与个性签名最多 100 字符的修改对应的校验与提示文案同样在 arb 文件中可查usernameLimit、signatureLimit、nicknameUpdated等。账号管理user_page.dart汇聚了资料编辑、邮箱绑定bind/emailAlreadyBound/emailBound、密码修改/重置、退出登录与账号注销accountDeleted等操作并在 user_account.dart 中展示匠心 ID。头像更换avatar_crop_page.dart/avatar_crop_view.dart/avatar_update_flow.dart组成头像裁剪与上传流程仅支持 JPG、JPEG、PNG、HEIC、HEIF 格式unsupportedAvatarFormat。2.3 黑名单能力blacklist/子目录提供了完整的黑名单功能blocked_user.dart定义用户模型blacklist_repository.dart负责增删查接口blacklist_page.dart展示列表并支持解除拉黑unblock/userUnblocked。三、头像框与徽章荣誉系统的数据模型与装配逻辑新增头像框与徽章可预览、装配并更换自定义头像是 v3.4.2 的亮点之一它背后是一套完整的荣誉Honor子系统。3.1 荣誉模型 UserHonoruser_honor.dart 定义了用户已获得荣誉的统一模型code稳定业务编码装备/卸下的操作凭据kind荣誉类型当前为badge徽章或avatar_frame头像框name/description/assetUrl展示名称、说明与图片地址grantedAt/reason发放时间与发放原因equipped是否处于装配状态。模型通过UserHonor.fromApi从服务端 JSON 映射而来并提供copyWith({bool? equipped})用于本地装备状态的乐观更新——装配/卸下操作后客户端立即用副本更新状态避免全量刷新。3.2 荣誉接口与状态管理honor_repository.dart 定义了 5 个接口方法HTTP路径语义loadMyHonorsGET/user/honors拉取当前用户全部荣誉equipAvatarFramePUT/user/honors/avatar-frame装备指定头像框unequipAvatarFrameDELETE/user/honors/avatar-frame卸下当前头像框equipBadgePUT/user/honors/badges/{code}装配一枚徽章unequipBadgeDELETE/user/honors/badges/{code}取消装配徽章avatar_frame_cubit.dart 中的AvatarFrameCubit管理装配状态load()登录后同步装备的头像框equip()/unequip()负责头像框的装配与卸下equipBadge()/unequipBadge()处理徽章的装配服务端返回装配后的徽章列表客户端据此同步equipped标记clear()在退出登录时清空上一位用户的数据。可以看到徽章装配是多选的返回列表而头像框是单选的。3.3 展示页面avatar_honors_page.dart头像徽章页分我的头像框 / 我的徽章两个 Tab 展示空态文案为还没有获得头像框 / 还没有获得徽章equipped_badges.dart展示已装配徽章与全局头像组件 user_avatar.dart 联动实现更换自定义头像 头像框 徽章的组合展示。四、每日任务与生涯成就进度模型与匠尘奖励新增每日任务与生涯成就完成任务可领取匠尘及荣誉奖励对应progression/子域。4.1 数据模型 ProgressionItemprogression_item.dart 定义了任务/成就的通用模型code/name/description任务编码与展示信息progress/target当前进度与目标值completedgetter 依据status判断是否完成status服务端计算的当前状态取值包括in_progress进行中、claimable可领取、claimed已领取、unlocked已解锁rewardPoints领取后增加的匠尘数量rewards成就解锁后发放的多个荣誉奖励ProgressionReward即徽章/头像框凭证。同文件还定义了ProgressionCurrency匠尘的展示信息默认codecraft_dust、name匠尘与ProgressionOverview总览含taskDate、timezone、dailyTasks、achievements、pointsBalance其中时区默认值为Asia/Shanghai说明每日边界由服务端按该时区计算。4.2 接口与状态流转progression_repository.dart 提供方法HTTP路径语义loadOverviewGET/user/progression/overview查询任务与成就总览checkInPOST/user/progression/check-in今日签到claimDailyTaskPOST/user/progression/daily-tasks/{code}/claim领取已完成任务的奖励recordWidgetViewPOST/user/progression/widgets/{id}/view上报组件访问服务端按组件 ID 去重recordWidgetCollectionPOST/user/progression/widgets/{id}/collect上报组件首次收藏progression_cubit.dart 中的ProgressionCubit封装状态流转claimDailyTask注释明确服务端账本保证重复请求不会重复增加匠尘幂等recordWidgetView/recordWidgetCollection采取后台静默上报策略失败不影响组件页正常使用成功后才load()刷新进度——这解释了任务如何与既有组件浏览/收藏行为打通。4.3 界面呈现task_achievement_page.dart 与 progression_panel.dart 负责展示顶部分为每日任务 / 生涯成就每日任务含签到checkIn、进度条、领取按钮claim/已领取/待完成成就页展示荣誉奖励honorRewardNames格式为徽章 · 名称一、名称二未登录时提示登录后查看任务成就。五、匠心工坊匠尘兑换与兑换记录新增匠心工坊可使用匠尘兑换头像框和徽章并查看兑换记录对应workshop/子域是任务经济闭环的消费端。5.1 商品与订单模型workshop_item.dart 定义三类模型WorkshopProduct可兑换商品含pricePoints售价匠尘、owned是否已拥有、ownedAt以及目标荣誉信息honorCode/honorKind/honorName/honorAssetUrlWorkshopPurchase兑换记录含orderNo订单号、productCode、pricePoints、createdAtWorkshopPurchaseResult购买结果含真实落库的purchase与扣除后的pointsBalance。其fromApi做了严格校验——若响应中没有完整的purchase与整型points_balance会抛出FormatException(兑换未生成有效订单)避免把业务错误 JSON 误判为购买成功。5.2 接口与购买防重workshop_repository.dart 提供products([kind])商品列表可按avatar_frame/badge过滤、purchases()兑换记录分页 50 条与purchase(productCode)。购买请求体同时携带product_code与客户端生成的 UUID 风格order_no由Random.secure()构造的 v4 格式随机串配合服务端订单号唯一约束实现客户端幂等。5.3 状态管理与页面交互workshop_cubit.dart 中的WorkshopCubit是关键业务逻辑所在load(kind)默认加载avatar_frame分类owned是本地虚拟 Tab请求时不带 kind再由_visibleProducts过滤出已拥有商品列表过滤前两个 Tab 只展示未拥有商品ownedTab 展示全部已兑换商品排序未拥有商品按售价升序已拥有商品按获得时间倒序purchase(product)兑换期间用buyingCode互斥防止并发成功后_markOwned本地标记再刷新owned列表错误被归类为匠尘余额不足 / 你已拥有该商品 / 兑换失败。workshop_page.dart 的交互细节印证了完整闭环顶部_BalanceHeader实时显示我的匠尘余额数据来自ProgressionCubit_KindFilter用CupertinoSlidingSegmentedControl切换头像框 / 徽章 / 已拥有三个 Tab商品卡片展示价格与兑换按钮点击兑换弹出确认对话框使用 {amount} 匠尘兑换兑换成功后同步刷新ProgressionCubit与AvatarFrameCubit匠尘不足时弹窗引导跳转每日任务页完成每日任务可以获得更多匠尘已拥有商品点击则跳转佩戴页并激活对应 Tab通过AppRoute.honors querytab参数实现。右上角入口 workshop_purchase_page.dart 展示兑换记录。至此v3.4.2 形成了完整的**任务赚匠尘 → 工坊换荣誉 → 装配展示**循环ProgressionRepository负责收入侧WorkshopRepository负责支出侧HonorRepository负责资产侧三者通过各自的 Cubit 在登录用户下协同。六、桌面端入口优化与跨端体验优化桌面端我的账号、收藏与任务入口对应 desktop_user_page.dart。桌面端与移动端共用同一套 Repository/Cubit 数据层仅在视图层做适配桌面端将我的账号 / 我的收藏 / 任务成就整理为更贴近桌面交互的侧栏式入口。仓库还配套了桌面端测试 desktop_user_page_test.dart 与登录对话框测试 login_dialog_test.dart可据此了解该页面预期的行为契约。七、中英文显示完善与统一文案管理完善用户系统、任务成就及工坊的中英文显示在实现上依托 Flutter 官方 arb 国际化流程仓库根目录 l10n.yaml。以 app_zh.arb 为例v3.4.2 新增键覆盖了工坊workshop匠心工坊、任务dailyTasks每日任务、careerAchievements生涯成就、荣誉avatarFrames头像框、badges徽章以及兑换链路exchangeWithCraftDust、insufficientCraftDust、goToTasks等与英文 arb 成对维护编译期生成AppLocalizationsgen_l10n/app_localizations.dart页面中通过context.l10n.xxx统一取用保证多语言覆盖不遗漏。八、工具宝库与组件 Logo 优化最后一条优化工具宝库与组件 Logo 展示属于视觉与信息架构层面的打磨工具宝库tools_system/treasure_tools与组件 Logoassets/images/widgets/目录下大量 SVG/WebP 图标的展示优化让全端体验在功能上线之外保持视觉一致。该部分以资源与布局调整为主无新增数据模型可作为体验优化项理解。九、模块架构小结与延伸阅读从源码结构看v3.4.2 的用户体系呈现出清晰的分层数据层model/纯 Dart 模型 fromApi映射→repository/基于FxDio()FlutterUnitHost()的统一 HTTP 封装状态层bloc//cubit/flutter_bloc管理加载、错误与乐观更新视图层views/下按mobile/与desktop/拆分的页面跨端复用同一套数据与状态逻辑能力出口authentication.dart 以 library 方式统一导出全部公共类供宿主lib/src/flutter_unit.dart装配使用。这与仓库 doc/development/architecture.md 描述的模块化modules/basic_system、modules/widget_system等按能力域拆分、以独立 pub 包形式组织思路一致。若想深入验证接口行为可参考 integration_test 与 test 目录下的测试。结语v3.4.2 是 FlutterUnit 从工具型应用走向社区型应用的关键一跃账号系统赋予数据归属任务与成就制造留存动机匠尘与工坊形成经济闭环头像框与徽章则提供自我表达出口。本文所引用的模型字段、接口路径、状态流转均来自仓库源码读者可以直接在modules/basic_system/authentication目录下对照阅读将其作为实现账号 虚拟荣誉 任务经济类功能的一份可参考的 Flutter 工程范本。【免费下载链接】FlutterUnitAll Platform Flutter Experience App项目地址: https://gitcode.com/GitHub_Trending/fl/FlutterUnit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考