芯耀
与非AI
27
很多PDA项目把“支持二次开发”写在参数表末尾。真正开始集成时，厂家发来一个压缩包，里面可能只有旧版JAR、一个能响一下的扫码Demo和几页截图。开发人员能在样机上读到条码，却不知道怎样控制扫描键、处理连续扫描、适配系统升级、获取设备序列号、做静默安装，遇到模块错误也没有可查的错误码,这不是完整的二次开发交付。
PDA二次开发的目标，不是让某个样例程序运行一次，而是让企业应用在约定的设备、系统、扫描模块和外设版本上长期稳定工作。厂家需要提供的内容，至少包括开发包、接口文档、可编译样例、版本兼容矩阵、错误处理、调试日志和升级支持。若设备还有RFID、NFC、打印、证件、PSAM、指纹、红外或传感器，每一个模块都要有明确边界。
采购人员未必要看懂所有API，但必须能判断交付物是否足够让软件团队独立完成开发、测试和后续维护。下面这份清单，可以直接用于需求澄清、样机评估和验收。
先确定采用哪一种集成方式
PDA扫描结果常见四种接入方式：键盘模拟、广播或Intent、系统服务接口、厂家SDK。不同方式没有固定高低，适合的业务不同。
键盘模拟
扫描模块把条码当作键盘字符输入到当前焦点，应用几乎不用接SDK。网页、表单和旧系统可以快速适配。
它的限制也明显。焦点落错位置，码值可能进入数量、备注或搜索框；应用难以获得扫描开始、结束、失败原因和原始字节；连续扫描、不同条码制式和参数控制能力有限。需要可靠业务上下文的项目，应额外限制页面焦点和校验码值。
广播或Intent
扫描服务通过Android广播或Intent把结果发送给应用。接入相对轻，应用能收到码值、长度、类型或状态。厂家应说明Action、Extra字段、数据类型、字符编码、权限、是否为显式广播、Android不同版本下的限制和示例。
广播接口若没有权限保护，其他应用可能监听或伪造结果。厂家和开发方要采用受控包名、权限或签名方案，并在新系统版本上验证后台与组件导出规则。
系统服务或AIDL接口
应用通过系统服务控制扫描模块，能获得更明确的生命周期和状态。厂家要提供服务名称、绑定方式、接口定义、断连重连、线程模型和权限。服务被系统重启或应用进入后台后，怎样恢复也应有样例。
直接SDK
SDK通常以AAR、JAR和必要的原生`.so`库交付，应用可以控制打开关闭、触发、连续扫描、条码制式、提示音、解码参数和回调。能力更完整，版本耦合也更强。
厂家需要说明SDK支持哪些设备型号、扫描引擎、Android版本、API级别和CPU ABI。一个为旧型号编译的JAR，在新设备上能安装，不代表所有接口可用。
项目可以同时支持两种方式。例如通用应用使用广播，深度集成应用使用SDK；应在需求中明确主路径和降级路径，避免开发后期临时切换。
扫码SDK应该交付什么
最基本的开发包应包含：
- AAR或JAR文件； - 原生库及支持的CPU架构； - API文档； - Java和Kotlin可编译样例； - 最低与目标Android版本； - 支持的PDA型号和扫描引擎； - SDK版本号、发布日期和变更记录； - 混淆规则、依赖与许可证说明； - 错误码和日志获取方法。
API至少要覆盖扫描模块初始化、打开关闭、单次扫描、连续扫描、停止扫描、结果回调、超时、条码类型和失败状态。若设备有左右扫描键、顶部键和手柄扳机，还要提供按键码、映射方法和禁用策略。
参数设置应说明生效范围。开启或关闭某种码制，是只对当前应用有效、当前用户有效，还是修改系统全局扫描服务？应用退出或设备重启后是否保留？多应用同时调用扫描模块时谁获得结果？这些问题比方法名称更影响生产使用。
条码结果不仅有字符串。需要明确原始字节、字符编码、码制类型、长度、时间戳和附加信息。中文、特殊字符、GS1数据、前后缀和不可见分隔符要有处理说明。
连续扫描要有节流与停止机制。应用页面退出、锁屏、切换患者或任务后，扫描回调不能继续写入旧页面。样例应展示Activity、Fragment或服务生命周期，避免开发者只复制一个全局监听器。
错误处理不能只有“返回false”。扫描模块忙、未初始化、权限不足、硬件不存在、服务断开、参数不支持、超时和解码失败要能区分。厂家还应说明哪些错误可以重试，哪些需要重启服务或设备。
一个有价值的扫码样例，至少要演示这些场景
“点击按钮开始扫码，结果显示在TextView”只能证明最小接口可调用。
生产级样例应展示：
- 通过实体扫描键触发； - 单扫与连续扫描切换； - 页面前后台与锁屏后的注册、注销； - 相同码快速重复时的业务去重示例； - 码制与长度过滤； - 前后缀和字符编码； - 扫描超时与取消； - 服务断开后的重连； - 多应用或多页面竞争时的处理； - 日志和错误码输出； - Android不同版本的权限与组件配置。
样例不需要写成完整WMS，但必须可编译、有依赖版本、有README，并在交付样机上实际运行。截图和伪代码不能替代源码。
如果厂家担心开放全部系统源码，仍可以提供最小可运行项目和接口库。二次开发交付的重点不是让客户复制内部实现，而是让客户正确使用公开能力。
RFID SDK需要比“能盘点”多得多
UHF RFID设备的SDK应覆盖初始化、天线与功率、盘点开始停止、EPC回调、去重、过滤、会话、TID读取、用户区读写、锁定、销毁以及错误状态。具体能力按设备和协议确定，不能把不支持的功能写进通用文档。
厂家要说明适用频段和区域配置。不同市场的频率要求不同，应用不能通过一个参数任意突破设备许可范围。若设备面向国内与海外项目，应提供对应型号和配置说明。
盘点回调要说明线程和频率。高速读取时，若每读一次都直接更新界面或写数据库，应用可能卡顿。样例应展示批量处理、去重、停止条件和页面退出后的资源释放。
射频功率不是越大越好。SDK要允许在设备许可范围内配置，也要提供当前值读取、保存和恢复。应用可以按任务或区域下发参数，但需要记录实际配置，方便解释漏读和串读。
读写标签涉及密码、存储区、地址、长度和锁定状态。样例应明确字节序、十六进制格式、错误码和不可逆操作。锁定或销毁属于高风险接口，应用必须增加权限、确认和日志，不能照着Demo一键调用。
如果设备有多天线、手柄扳机或信号强弱反馈，还要提供相应接口和限制。RSSI可以辅助寻找，不能被样例包装成精确距离。
RFID验收不只看Demo读到标签，还要在真实物品上验证功率设置、金属液体影响、串读、漏读、停止响应、长时间运行和内存稳定。
NFC、低频和高频接口要说明支持的技术类型
“支持NFC”不能直接推导出能够读取所有卡片或标签。
厂家应列出设备支持的标签技术、频率、协议和读写范围，说明使用Android标准NFC API还是专用SDK。标准API可能涉及前台调度、Reader Mode和不同TagTechnology；专用模块则要提供连接、寻卡、认证、读写和错误处理接口。
项目要明确读取的是NDEF标签、MIFARE、CPU卡、身份证相关模块、低频动物标签还是其他介质。它们的协议、安全和授权条件不同，不能用一个NFC Demo替代。
样例应包括标签发现、技术类型判断、断开重连、超时、重复感应和页面生命周期。需要密钥、PSAM或安全模块时，厂家要说明接口和安全边界，不应在样例源码中写入真实密钥。
打印PDA的SDK要覆盖版式和异常
内置打印模块至少要提供初始化、文本、图片、条码、二维码、走纸、切纸或设备实际支持的功能。文档要说明纸张宽度、点密度、字库、编码、打印浓度、速度和最大图片尺寸。
中文打印要测试不同字体、字号和换行。条码不仅要打印出来，还要用实际扫描器验证可读性。标签模板中有Logo、表格和多语言时，样例要说明图片处理和内存限制。
缺纸、开盖、过热、低电量、卡纸和打印头异常应有状态回调。应用不能在打印失败后仍把业务标记为“标签已出”。重打需要记录原因与次数，避免同一任务产生多张都被视为有效的标签。
若PDA通过蓝牙或USB连接外部打印机，还要提供配对、断连重连、权限和兼容型号清单。打印Demo在桌面成功一次，不代表员工移动使用时稳定。
设备系统接口通常还包括什么
企业级应用往往需要设备序列号、型号、固件、扫描模块版本、电池状态和网络信息。厂家应提供受支持的读取方式，避免开发者使用隐藏接口、系统属性或不稳定的反射代码。
实体键映射、提示灯、蜂鸣器、振动、手电、摄像头、NFC、串口、USB、底座和传感器若可编程，也应分别给出接口。哪些是Android标准能力，哪些需要系统签名或厂家服务，要明确。
静默安装、卸载、开机自启、应用白名单、状态栏限制、系统时间、网络配置和远程控制属于高权限能力。厂家不能只给一个拥有系统签名的Demo，却不说明客户应用怎样获得授权。需要签名、证书、配置文件或MDM时，应写入交付流程。
高权限接口必须限制调用方，记录操作，并提供最小权限。一个普通第三方应用若能任意静默安装、修改系统或读取设备敏感信息，会带来安全风险。
设备标识也要遵循平台和企业安全要求。不要假设所有Android版本都允许应用读取相同硬件标识。厂家应提供稳定、受控并适合资产管理的设备ID方案，同时说明重置、主板更换和恢复出厂后的变化。
MDM、OTA和专用设备管理需要哪些接口
大量PDA部署后，企业需要批量配置、安装应用、查看状态、锁定丢失设备和分批升级。Android企业专用设备可以采用受管设备模式，由设备策略控制器或企业管理平台执行策略，具体能力取决于系统、厂商和管理方案。
厂家应说明设备是否支持主流企业管理方式，是否有自有MDM，能否提供注册、分组、应用分发、配置下发、远程锁定、恢复出厂限制、日志和升级。若必须使用厂家私有平台，要说明部署方式、数据位置、账号权限、费用和服务期限。
OTA接口或平台应支持查询当前版本、灰度升级、下载校验、失败重试和结果上报。生产设备不能在高峰期全部同时升级，项目需要分组、时间窗口和暂停策略。
升级还要能回退。新固件影响扫描、RFID或业务应用时，厂家是否提供旧版本、回退条件和数据保留说明，应在合同中确认。只承诺“持续更新”而没有兼容与回退，风险仍然存在。
设备日志要能定位硬件与系统问题，同时控制敏感数据。扫描服务崩溃、电池异常、网络切换和应用安装结果可以记录；患者、客户、密码和业务内容不应无边界写入日志。
版本兼容矩阵是二次开发最容易缺失的文件
开发包里有SDK版本号，却没有它对应的设备和系统版本，后续维护会非常困难。
一张实用矩阵至少列出：
- PDA型号与硬件版本； - Android或其他系统版本与构建号； - 扫描引擎、RFID和外设模块型号； - 系统服务版本； - SDK版本； - 支持的API级别与CPU ABI； - 已知问题； - 推荐升级路径； - 停止支持时间或维护策略。
企业应用每次发布时，也应记录使用的SDK和测试设备。设备固件升级后，先在代表性样机上跑回归，再分批发布。厂家若更换扫描模块但保持商品型号不变，必须通知接口与性能差异。
变更记录要说明新增、修复、行为变化和废弃接口。只把文件名从`SDK_v1`改成`SDK_new`，开发团队无法判断是否应该升级。
文档应该写到什么程度
API文档不能只有方法列表。每个接口应说明用途、参数单位、取值范围、返回值、线程、权限、生命周期、可能错误、支持型号和代码示例。
初始化是否耗时、能否在主线程调用，回调发生在哪个线程，停止扫描后是否还会收到残余结果，设备重启后设置是否保留，这些都需要明确。
文档还应提供最短集成路径与生产建议。最短路径帮助开发者快速跑通，生产建议提醒资源释放、重复扫描、日志、安全和升级。两者缺一，团队要么无法上手，要么把Demo直接带进生产。
接口文档、样例与SDK必须同版本。若文档描述的方法在库中不存在，或样例依赖内部未交付包，验收应失败。
厂家技术支持要能够回答到“哪一层出错”
二次开发联调中，问题可能出在业务应用、厂家SDK、系统服务、扫描引擎固件、RFID模块、Android权限或硬件本身。只用“重启试试”处理，会让双方反复甩锅。
厂家应提供明确的支持入口和问题模板。开发方提交设备型号、系统构建号、模块版本、SDK版本、应用包名、复现步骤、错误码、时间和必要日志；厂家根据版本矩阵判断是否为已知问题，再给出配置、补丁、升级或返修建议。
日志采集工具要能在不泄露业务数据的前提下导出关键状态。扫描服务启动、模块初始化、权限拒绝、服务断开、射频错误和系统崩溃应可定位。若日志必须由厂家远程连接设备获取，远程操作要经过企业批准，有时间、人员和范围记录。
问题处理还要区分临时绕过与正式修复。让应用每天开机重启一次，可能短期缓解服务泄漏，却不能作为长期交付；修改扫描参数规避某类标签，也可能影响其他条码。厂家应说明影响范围，并在正式版本中提供修复与变更记录。
合同可约定关键缺陷等级和响应，但不要只看“几小时响应”。更重要的是能否提供可复现结论、受支持版本和回归方法。工程师回复很快，却每次给出不同临时包，项目仍然难以维护。
建一个最小验收应用，比保存十个Demo更有用
企业可以保留一个很小的内部测试应用，用于验证所有采购范围内的设备能力。它不处理真实业务数据，只显示设备与模块版本，提供扫描、RFID、NFC、打印、按键、声音、振动和日志测试页面。
这个应用应使用企业正式接入方式和签名，依赖固定版本SDK。每次新设备到货、固件升级、SDK升级或模块换型，都在同一应用中跑一遍，并保存结果。相比供应商为每个模块提供一个不同风格Demo，统一验收应用更容易发现接口冲突和版本变化。
测试页面不需要追求精美，也不要变成第二套业务系统。它只回答：
- 当前设备和模块实际是什么版本； - 公开接口能否初始化和释放； - 正常、异常和长时间运行是否符合预期； - 应用切换、锁屏和重启后是否恢复； - 日志能否定位失败； - 升级前后的结果是否一致。
可把通过的设备、系统与SDK组合记录成白名单。业务应用发布前，选择白名单中的代表设备回归；未验证组合不直接进入生产。
这个最小应用还是供应商沟通的共同语言。出现故障时，先看同一问题能否在验收应用复现。如果能，问题更可能位于设备、系统或SDK；如果不能，再检查业务应用的线程、生命周期和数据逻辑。它不能自动断定责任，却能显著缩小范围。
SDK资料也需要安全审查
二次开发包可能包含系统权限、签名文件、调试账号、云平台地址和厂商内部工具。企业接收后应在本地受控环境保存，不把密钥、证书和内部地址提交到公开代码仓库。
样例源码中若带有固定密钥、默认口令或无限制导出组件，应在接入前移除。广播接口要检查权限，系统服务要限制调用包，静默安装和设备控制接口要采用授权机制。为了调试临时开启的USB、ADB或工程菜单，上线前应按企业策略关闭或管控。
第三方库也要记录版本与许可证。厂家SDK依赖多个旧库时，可能与企业应用冲突或带来维护风险。能使用Android标准API完成的能力，优先使用平台接口；只有扫描、RFID和系统特权等设备专有能力再依赖厂家SDK，能减少锁定范围。
安全审查不意味着企业要拿到厂家全部源码。公开接口、权限边界、依赖、数据流和更新责任清楚，已经能够处理大部分集成风险。
怎样验收厂家提供的SDK和样例
不要只看文件数量，直接在一台干净开发机上执行。
软件团队按照README安装指定工具和依赖，导入样例并编译。过程中不应依赖厂家电脑上的私有路径、未说明证书或手工复制文件。编译出的应用安装到交付样机，逐项调用接口。
扫描验收覆盖实体键、单扫、连续、不同码制、异常标签、页面切换、锁屏、服务重启和长时间运行。RFID覆盖功率、过滤、EPC与TID、读写错误、停止响应和大量回调。打印覆盖中文、条码、缺纸与重打。其他模块按业务范围测试。
然后把SDK接入一个最小企业测试应用，而不只运行厂家Demo。这样可以验证包名、签名、权限、混淆、Gradle版本和现有技术栈是否兼容。
随后模拟系统升级和应用升级。旧应用在新固件上能否工作，新应用在库存旧设备上能否运行，出现不兼容时厂家怎样定位和回退。
可以直接写进采购文件的交付清单
开发资料：
- 当前正式SDK及校验信息； - Java与Kotlin可编译源码样例； - API文档、集成指南和FAQ； - 版本兼容矩阵与变更记录； - 支持期限与技术支持入口。
扫码能力：
- 键盘模拟、广播、Intent或SDK接口说明； - 扫描键、单扫、连续、码制、超时、回调； - 原始字节、编码、前后缀和错误码； - 生命周期、线程与服务重连样例。
专用模块：
- RFID功率、过滤、盘点、读写锁定和错误处理； - NFC或低高频技术类型、认证与读写； - 打印版式、状态、异常和耗材规格； - 证件、PSAM、指纹、传感器等实际采购模块接口。
系统与管理：
- 设备型号、序列号、固件和模块版本读取； - 实体键、灯、声音、振动和外设控制； - 应用授权、系统签名或白名单流程； - MDM、OTA、灰度升级、回退和日志； - 丢失、维修、换机和恢复出厂的数据处理。
验收：
- 在指定开发环境可独立编译； - 在交付设备和正式系统版本上运行； - 关键接口通过场景测试； - 厂家Demo与客户最小应用结果一致； - 文档、SDK、样例和设备版本一致； - 已知限制和不支持项书面列出。
二次开发交付的标准，是能独立维护
PDA厂家提供SDK，不是交付一个压缩包就结束，还需要提供技术支持，要有专业技术人员的对接服务（例如国产pda手持机厂商-鸟鸟科技，在这方面就做得很到位，可以参考一下）。
完整交付要让开发团队知道用哪种方式接入、接口支持哪些设备和系统、怎样处理生命周期与异常、升级后如何回归，出现问题时能拿到错误码和日志。
扫码只是最基本模块。RFID、NFC、打印、证件、PSAM、指纹、传感器、设备标识、按键、MDM和OTA，都应按实际采购范围提供接口、样例与版本边界。没有购买的功能不必为了“齐全”索取，但所有生产必需能力都不能停留在口头承诺。
判断资料是否合格，可以用一句话：把一台干净电脑、一台交付样机和这套资料交给没有参与前期沟通的开发人员，他能否独立编译、调用、处理异常并完成升级回归。能做到，才叫支持二次开发；只能让厂家工程师远程改Demo，就还没有形成可维护的开发能力。
交付清单还应写明问题如何被复现。开发团队提交故障时，需要能够带上设备型号、固件版本、SDK版本、应用版本、模块状态、错误码和经过脱敏的日志；厂家则应说明由哪个接口或工具采集。缺少这条路径，项目后期遇到偶发漏扫、RFID停止回调或升级后权限变化，只能依赖视频和口头描述，定位时间会远高于补齐一份诊断说明的成本。
