DartNative 试点别看宣传：1–2 周 POC 验收清单
一份面向移动团队的 DartNative 试点验收清单：用真实业务屏和现有基线验证工具链、列表输入、插件、日志、发布、双端一致性、许可采购与退出标准。
DartNative 目前最适合做的不是“看营销对比后直接换栈”，而是在 1–2 周内拿团队自己的真实基线做一次可复现验收。它的路线很清楚：Dart AOT、真实 UIKit / Android View、Yoga 布局、主线程同栈更新，不走 JavaScript bridge，也不把标准控件重新画成像素。这个方向对列表、输入、键盘、导航和系统控件体验有吸引力，但官方材料同时也给出了边界：项目仍处在 preview，框架实现主要在私有仓库，构建自有应用需要有效订阅和 license key，iOS 需要 macOS 与 Xcode 26.3+，Android 需要 Android SDK 36。验收的重点不是证明它“比谁快”，而是判断它能不能在你们现有产品、人员、交付节奏和采购制度里替代真实基线。
POC 目标：只回答能否进入下一阶段
这次验证不应该扩成一次完整重写。建议选一个对团队最有代表性的移动端纵切面：一个主列表、一个详情页、一个输入/编辑流程、一个登录或系统能力调用、一次崩溃与日志采集、一次 release 构建。基线必须是团队今天正在维护的真实方案，例如现有 Flutter、React Native、原生双端或混合方案；不要用空白 demo、供应商 playground 或“hello world”作对比。
| 验收问题 | 通过定义 | 不通过信号 |
|---|---|---|
| 能否搭起来 | 新同事按文档从零安装、运行、构建，步骤可复现 | 依赖个人机器、私聊补丁或不可解释缓存 |
| 能否还原真实屏 | 代表性屏幕能覆盖列表、输入、导航、状态和插件 | 只跑官方 demo，绕开产品最难交互 |
| 能否定位问题 | Dart 与原生日志、崩溃、构建产物都能被团队采集 | 问题只能由供应商远程解释 |
| 能否采购与退出 | license、订阅、私有实现、停更承诺和回滚方案可接受 | 法务、采购、运维或发布流程无法放行 |
第 0 天：准备边界与基线
- 冻结对比对象：选择当前团队真实基线的同一业务屏，不允许临时简化数据结构、删除错误态或换一个更容易的设计稿。
- 冻结设备清单：至少包含一台 iPhone 或 iOS 模拟器、一台 Android 真机或模拟器；如果产品重视高刷新、低端机、折叠屏或无障碍，也要列入验收设备，但不要预设性能结论。
- 冻结度量口径：记录启动、滚动、输入、构建大小、崩溃、日志、发布流程的采集方法。没有采集方法的指标不要写进结论。
- 冻结范围：POC 只做一条纵切面，不迁移账号体系、不改后端协议、不重做设计系统；任何新增范围必须写入变更记录。
环境与工具链验收
DartNative 官方 getting started 对工具链要求很具体：iOS 构建只能在 macOS 上完成，需要 Xcode 26.3 或更新版本；Android 需要 Android SDK 36 和对应 build-tools，dn doctor 会报告缺失项。POC 要把这些要求变成团队自己的安装手册，而不是只记录“某台机器跑通”。
| 检查项 | 验收动作 | 证据 |
|---|---|---|
| CLI 安装 | 执行官方安装命令，记录 dn --version、PATH 调整和首次下载缓存位置 | 安装日志、版本号、失败恢复步骤 |
| Android SDK 36 | 在干净环境执行 dn doctor，缺失时用 SDK Manager 或 sdkmanager 补齐 | doctor 输出、SDK 路径、CI 镜像变更 |
| iOS/Xcode | 确认 macOS、Xcode 26.3+、签名 Team、Bundle Identifier、模拟器/真机路径 | Xcode 版本、签名截图或文字记录 |
| 编辑器 | VS Code/Android Studio 能补全、调试、热重载；必要时关闭普通 dart pub get 自动触发 | 项目内配置说明，不提交个人绝对路径 |
| 依赖锁定 | 提交 pubspec.lock 与 dn_plugins.lock，记录 dn upgrade 前后差异 | 锁文件 diff、升级回滚命令 |
代表性屏幕：不要只做静态页面
候选屏幕应尽量接近产品真实压力。例如消息列表、订单列表、评论流、设置表单、搜索页或内容编辑页。它必须同时包含网络数据、空态、错误态、加载态、刷新、分页、图片、导航返回、键盘弹出和至少一个设备能力调用。DartNative 的价值主张集中在真实原生控件和主线程同步更新上，如果 POC 避开列表、输入和键盘，就没有验证到核心。
- 数据真实性：使用脱敏线上样本或测试环境接口，保留真实字段长度、图片尺寸、缺失字段和异常状态。
- UI 真实性：复用当前设计系统的间距、字体、深浅色、状态色和交互，不因为框架限制改设计。
- 操作真实性：让产品、设计、测试各自用同一脚本操作，记录哪些体验接近原生，哪些行为与基线不同。
- 代码真实性：不要把所有逻辑写死在一个 demo 文件里；至少要有路由、状态、服务调用、错误处理和测试入口。
列表、输入、键盘、导航、无障碍验收表
| 能力 | 必须验证 | 通过标准 |
|---|---|---|
| 长列表 | ListView.builder 与官方 FastList/FastGrid 思路是否适合当前数据量、图片和分页 | 滚动、回到顶部、分页、图片缓存、快速滑动后定位都可解释；不写供应商未复现实测数字 |
| 输入 | 单行、多行、格式化、提交键、选择、复制粘贴、中文输入法、表情符号 | 行为与平台习惯一致，关键回调可稳定触发，异常有日志 |
| 键盘 | 底部输入栏、表单字段遮挡、横竖屏、交互式收起、Android 返回键 | 内容不被遮挡，输入栏移动符合平台习惯；iOS/Android 差异被记录 |
| 导航 | push/pop、iOS 侧滑返回、Android 系统返回、深链或命名路由、热重启后状态 | 返回栈、动画、状态恢复和埋点都可控 |
| 无障碍 | Dynamic Type/字体缩放、屏幕阅读器标签、焦点顺序、暗色模式、RTL 如有业务需要 | 不因真实原生控件而漏掉语义；无法覆盖项进入缺口清单 |
插件覆盖与原生能力
官方材料提到一批一方插件，包括存储、权限、分享、音频、媒体、相机、视频、WebView、地图、通知、购买等方向；文档也强调插件通过 FFI/JNI 与原生侧连接。POC 不需要把插件全试一遍，必须把团队产品依赖列成矩阵：已有 Flutter/RN/原生库对应哪个 DartNative 一方插件，是否需要自研插件，是否有 iOS/Android 对等实现，是否能在测试包和 release 包中同时工作。
| 产品依赖 | DartNative 替代项 | 验收动作 | 结论 |
|---|---|---|---|
| 本地存储 | dartnative_shared_preferences、secure storage、Hive、SQLite 等 | 读写、迁移、异常数据、卸载重装、加密边界 | 通过/缺口/不适用 |
| 权限与系统信息 | permissions、system 类插件 | 首次授权、拒绝、二次打开设置、版本号读取 | 通过/缺口/不适用 |
| 媒体与相机 | media picker、camera、audio、video 等 | 真机采集、后台切换、权限拒绝、文件大小 | 通过/缺口/不适用 |
| WebView/支付/登录 | 官方插件或自研 FFI/JNI 插件 | OAuth 回调、Universal Link/App Link、购买回执或支付结果 | 通过/缺口/不适用 |
| 自研 SDK | 自写插件 | 最小 FFI/JNI 调用、回调、线程、错误码、打包 | 通过/缺口/不适用 |
崩溃、日志与现场定位
DartNative 的官方材料强调统一日志流：Dart print() 与 Swift/Kotlin 侧日志可以进入同一个 dn run 终端，DartNativeLogger 还可以保存到应用沙盒文件。POC 要验证它是否融入团队已有的 Sentry、Crashlytics、ELK、移动端日志拉取或客服诊断流程。
- 人为制造异常：Dart 层异常、原生插件异常、网络解析异常、权限拒绝异常都要有可读日志。
- 制造一次崩溃：debug 与 release 各记录一次崩溃采集路径，确认符号化、设备信息、版本号和用户操作路径是否完整。
- 离线日志：打开
saveToFile类能力，验证文件大小、轮转、隐私脱敏、用户导出方式和客服读取流程。 - 原生回调日志：至少记录一次滚动、输入或插件回调从原生侧进入 Dart 侧的完整链路。
App Size 与 release build：只记录自己的产物
官方 README 给过新 app 与 Flutter 空项目的体积示例，也说明可选 dartnative_skia 会增加体积；Skia 文档进一步提示 iOS 与 Android 的体积影响不同，且当前 tier 选择仍有 caveat。这些数字只能作为背景，不能直接写进团队结论。POC 应当用同一业务屏、同一资源、同一签名方式生成自己的 release 产物。
| 产物 | 记录口径 | 注意事项 |
|---|---|---|
| iOS archive / ipa | 构建命令、Xcode 版本、签名方式、压缩后大小、安装后大小 | 是否引入 Skia、是否包含调试符号要分开记录 |
| Android apk/aab | ABI、min/target SDK、R8/ProGuard、资源压缩、安装后大小 | 确认 Android SDK 36 要求与现有发布渠道兼容 |
| 基线产物 | 同样功能、同样资源、同样构建类型 | 不要拿空项目或旧版本对比 |
| 启动与交互 | 只记录已定义采集方法下的观测结果 | 没有独立采集就写“未验证”，不要补数字 |
Android / iOS parity：把差异当成一等结果
DartNative 的方向不是把两个平台做成完全一致，而是尽量使用真实平台控件。验收时不能只看“视觉是否一模一样”，还要看差异是否符合平台习惯、是否被设计和测试接受、是否影响埋点与自动化脚本。
- 平台控件：导航栏、返回手势、日期选择器、系统弹窗、权限弹窗分别按 iOS/Android 习惯验收。
- 键盘与输入法：中文输入、候选栏、表情、复制粘贴、提交键、Android 返回键都要双端录屏。
- 深浅色：跟随系统外观切换，并记录运行中切换是否触发重建。
- RTL/国际化：如果产品有阿语、希伯来语或混排需求，验证 Directionality、start/end、焦点顺序和文本截断。
- 自动化：确认现有 UI 自动化工具能否定位真实原生控件；如果测试框架要更换，算入迁移成本。
升级、复现与供应风险
官方说明中有两个必须被认真对待的事实：公共仓库包含文档、playground、教程、插件示例和 issue tracker，但框架自身在私有仓库中开发；更新通过重新运行安装命令、dn upgrade 和 dn pub upgrade 获取，preview 期间变更频繁。团队要把这件事验收到工程流程里。
| 风险 | POC 验收动作 | 决策问题 |
|---|---|---|
| Preview 变更频繁 | 固定一个版本跑通后，再执行一次升级，记录破坏性变化和修复成本 | 团队能否接受每周跟进变更 |
| 私有实现 | 列出无法自行调试的层：CLI、引擎、平台绑定、license 校验 | 生产故障时是否能等供应商响应 |
| 构建可复现 | 在第二台机器或 CI 上重建；缓存清空后重建 | 发布不能依赖单人电脑 |
| 包源依赖 | 验证 dartpub.dev、私有 registry、license key 存储和网络访问 | 内网、海外网络、离线构建是否受影响 |
| 锁文件 | 提交并审查 pubspec.lock、dn_plugins.lock、SDK 版本记录 | 能否回到上一个可发布状态 |
许可、采购与合规
官方 license 写明 DartNative 是 Presence Network Inc. 的专有产品，使用、构建和部署自有应用需要有效 license token；license 是有限、非独占、不可转让、不可再授权的权利。已在有效订阅下分发给终端用户的应用，在订阅到期后可以继续运行，但订阅到期会停止继续使用软件构建和部署新应用的权利。license 也包含停更后的源代码释放承诺：达到约定的 discontinued 条件后，在限定时间内发布当时源代码与一方插件，但不包括商标、license 基础设施、凭据和签名密钥等。
- 采购：确认价格、付款主体、发票、续费周期、席位或项目限制、试用与正式 license 的差异。
- 法务：审查不可转让、不可修改、不可逆向、token 管理、停更承诺、管辖法律和免责声明。
- 安全：license key 不进仓库、不进日志、不进截图；CI 使用密钥管理系统注入。
- 开源组件：记录 Zero、Flutter/Dart、Yoga、FlexLayout、Skia 等第三方 notice 是否进入发布包并符合公司合规流程。
- 供应商响应：明确 issue、邮件、紧急问题 SLA 预期；preview 阶段不要把社区响应当成合同 SLA。
回滚与退出标准
POC 最后一天要产出一个明确判断：继续扩大、只保留观察、或停止。为了避免“已经写了就继续写”的沉没成本，退出标准应在开始前写好。
| 结论 | 触发条件 | 后续动作 |
|---|---|---|
| 进入下一阶段 | 代表性屏幕双端可发布；关键插件可用；日志/崩溃/构建/采购无阻断项 | 选择一个低风险真实模块，制定 4–6 周迁移计划 |
| 继续观察 | 核心体验有优势，但存在 preview、插件缺口、采购或 CI 风险 | 保留 POC 分支，每两周跟随 changelog 复测阻断项 |
| 停止引入 | 任一硬阻断无法接受：无法合法采购、无法稳定 release、关键插件缺失、双端差异不可控、无法回滚 | 归档报告，保留可复现步骤，不再投入产品代码 |
最终交付物清单
- 一份从零安装到 release 构建的团队内部 runbook。
- 一个可运行的 POC 仓库或分支，包含锁文件、构建脚本、版本记录和 README。
- 一张功能覆盖矩阵：列表、输入、键盘、导航、无障碍、插件、日志、崩溃、发布、双端差异。
- 一份对比报告：只写团队真实基线与 POC 的可验证差异，不引用未独立复现的供应商 benchmark。
- 一份风险与采购意见：preview、私有实现、license、供应商依赖、停更承诺、密钥管理。
- 一份回滚方案：如果 POC 进入真实模块，如何保留原实现、如何按开关切回、如何清理新依赖。
如果团队在 1–2 周后只能说“官方 demo 很顺”或“宣传上看起来更原生”，这次 POC 就没有完成。合格的结论应该能被工程、测试、产品、法务和采购同时阅读：哪些地方确实比现有基线更适合你们，哪些地方还不能赌，下一步最多投入到什么范围，什么时候必须退出。