先说结论:OpenHarmony上用Flutter做业务App,真正的难度不在Flutter本身,也不在API协议设计,而在生态的“信息差”。SDK怎么选、插件怎么适配、设备怎么连、驱动怎么烧,每一个环节都能卡住你半天。这个电子合同签署App项目做下来,我把整条签署API链路彻底打通了,从合同模板、实名认证、签署动作到归档存证,中间踩过的坑、验证过的方案,整理成这篇实战记录,给准备在OpenHarmony设备上搞Flutter的团队做个参考。
做这个项目前,团队已经在Android上积累了一套Flutter业务组件库,所以技术栈很快就定了:Flutter for OpenHarmony + ArkTS桥接系统能力。设备端是rk3568/rk3588的OpenHarmony盒子,带触摸屏,部分网点还有外接指纹仪和高拍仪。业务形态是用户在柜面一体机上完成合同签署,整个过程涉及身份核验、合同预览、手写签名、活体检测、短信验证码等多个环节,背后对应一串REST API和OpenHarmony系统API。这篇就把这些API集成实现的关键点、坑位和思考过程完整展开,适合三类人看:准备在OpenHarmony上跑Flutter的团队、做电子合同或电子签章类应用的开发者,以及被设备适配折磨过的硬件集成工程师。
1. 项目整体设计与技术选型,先想清楚再动手
1.1 电子合同签署App的核心需求拆解
合同签署看起来就是个“上传PDF然后签字”的事,落到具体业务里远没那么简单。我们接到的明确需求是:用户在网点一体机上完成一份信贷类合同的签署,流程里必须包含身份实名认证、合同条款展示、手写签名采集、人脸活体检测、短信验证码双重校验,签完后能实时查询签署状态并下载已归档的合同文件。
拆成API清单就成了下面这张表:
| 接口方向 | 用途 | 关键参数 |
|---|---|---|
| 实名认证 | 对接身份核验服务,校验用户身份证与活体 | 姓名、证件号、活体检测token |
| 合同模板 | 拉取模板并填充业务变量,生成待签PDF | 模板编号、业务字段Map |
| 合同发起 | 创建签署流程,分配给签署方 | 合同编号、签署方列表、签署顺序 |
| 签署提交 | 上传手写签名图片并提交签署动作 | 合同编号、签名图片、验证码、客户端请求ID |
| 状态查询 | 查询签署进度 | 合同编号 |
| 合同下载 | 下载已归档PDF | 合同编号、归档版本号 |
这个清单看着简单,但每个接口背后的状态流转、幂等策略、安全校验才是真正要下功夫的地方。比如合同不能重复发起签署、签名图片不能被篡改、验证码不能重放,这些需求会直接决定API集成层的实现方式。
1.2 为什么选Flutter for OpenHarmony,而不是ArkUI或RN
技术选型时我们其实做过一轮对比。ArkUI是OpenHarmony的原生声明式框架,生态和工具链最正统,但团队里没有ArkTS开发经验,从零学一套新UI框架再重写业务组件,成本和时间都不允许。React Native for OpenHarmony当时也有社区方案,但三方库适配情况更不稳定,而且我们现有Flutter组件库没法直接复用。
选Flutter for OpenHarmony有几个现实理由:第一,Flutter是自绘渲染引擎,UI在不同OpenHarmony设备上的呈现效果一致性明显好于WebView方案,不会出现“这个盒子上按钮错位”的问题;第二,我们现有业务组件库可以平移到OpenHarmony,只需处理平台通道的适配;第三,Flutter的Dart层网络、状态管理、文件处理等能力完全跨端通用,API集成的大部分代码可以原样复用。
但这个选择不意味着不用写原生代码。OpenHarmony上的Flutter工程同样需要ArkTS侧的能力支持,比如相机、活体检测、系统权限、生物识别,这些都得通过MethodChannel或EventChannel桥接到ArkTS实现。说白了,Flutter管UI,ArkTS管系统能力,API集成层则是两者之间的桥梁和业务中枢。
1.3 一条完整的签署业务链路长什么样
把需求还原成一条真实链路,大概是这样的:用户在终端上点击“开始签署”,App先从服务端拉取待签署合同列表,选择合同后进入身份认证环节,调起活体检测完成实名核验,然后服务端返回合同详情和签署页面签名区坐标。用户在签名区手写签名并输入短信验证码,App把签名图片和验证码提交到服务端,服务端校验通过后完成签署,合同进入归档状态,同时生成存证记录。
整条链路的API集成必须围绕状态机设计。合同状态至少包含:草稿、待签署、签署中、已完成、已归档、已作废。前端界面根据状态驱动按钮的可用性和提示文案,比如“签署中”状态下不能重复提交,“已归档”状态下只能查看和下载。如果状态管理没做好,最容易出现的问题就是用户重复点击提交,导致服务端生成多条签署记录。
提示:电子合同签署类业务,接口设计时一定要把“幂等”放在第一位。签署动作是不可逆的,重复提交的后果不是多一条记录,而是可能产生法律纠纷。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
