NFC 冷启动问题修复原理本文说明本项目为什么曾经需要碰卡两次以及如何通过 Android 启动入口、Intent 读取和页面结果交接让第一次碰卡即可唤起应用、获取 UID 并提交打卡。前端项目代码链接 https://github.com/bigxinyuan222/NFC-TAG1. 修复结论这次修复贯通了两段流程Android 把带卡片数据的 NFC Intent 交给正确的启动入口应用启动后立即读取这个 Intent再持续监听后续碰卡。原来的现象是APP 未打开时第一次碰卡只能启动 APPAPP 打开后再碰一次才取得 UID。第二次能够读到说明前台读卡流程可以工作但首次启动时的 NFC 数据交接不完整。修复后的关键变化如下环节原来存在的问题现在的处理卡片内容匹配现场卡片写的是包名启动记录仅处理mycheckin://不匹配增加 AAR 对应的 NDEF 过滤规则原生启动入口测试时曾把 NFC 入口挂到未对外导出的内部 Activity出现无法拉起 APP使用io.dcloud.PandoraEntry正常启动入口冷启动读取只等后续事件会漏掉已放进启动 Intent 的卡片onLaunch注册监听后立即主动读取当前 Intent初始化时序初次读取时桥接或卡片数据可能尚未就绪保留数据每隔 100ms 重试最多再试 5 次重复通知同一次启动可能被多次通知消费标记、UID 防抖、提交锁共同防重结果展示上传可能早于页面就绪只有事件通知容易漏掉弹窗先保存结果再由页面一次性消费并显示动画2. 现场卡片实际写入了什么NFC Tools 中的“启动应用”写入的是 Android Application Record简称 AARNDEF 记录类型External / android.com:pkg 记录内容uni.app.UNI35FA817 整条记录长度36 字节 本次实机卡片 UID5310C716430001现场记录的复现数据保存在 nfc-package-record.json。包名用于选择要启动的应用硬件 UID 用于本项目的卡片校验两者分别从不同位置取得。Android 对 External 类型记录使用vnd.android.nfc://ext/记录类型进行 Intent 匹配所以本卡片对应vnd.android.nfc://ext/android.com:pkg。AAR 还允许系统按包名选择应用因此“APP 被打开”本身不足以证明具体 Activity 已收到本次 NFC 数据。Android 官方说明本次排查据卡片内容、入口配置和复现现象定位到首次启动的分发链路。没有改写卡片也没有用包名或协议链接代替 UID。3. 第一步修正 Android 原生启动入口修改位置AndroidManifest.xml。现有 NFC 权限继续由 manifest.json 配置根目录清单补充 Activity 的 NFC 入口?xml version1.0 encodingutf-8?manifestxmlns:androidhttp://schemas.android.com/apk/res/androidpackageuni.app.UNI35FA817applicationactivityandroid:nameio.dcloud.PandoraEntryandroid:exportedtrueintent-filteractionandroid:nameandroid.nfc.action.NDEF_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT/dataandroid:schemevnd.android.nfcandroid:hostextandroid:path/android.com:pkg//intent-filterintent-filteractionandroid:nameandroid.nfc.action.NDEF_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT/dataandroid:schememycheckin//intent-filterintent-filteractionandroid:nameandroid.nfc.action.TAG_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT//intent-filter/activity/application/manifest三个过滤器分别负责现场包名启动卡片、mycheckin协议卡片以及走到TAG_DISCOVERED分发阶段的卡片。TAG_DISCOVERED是兜底入口不能替代现场 AAR 的精确匹配。为什么选择 PandoraEntry本次排查的 DCloud 运行时启动链路是系统 NFC Intent → io.dcloud.PandoraEntry → 初始化应用运行时 → 把原 NFC Intent 转交给 io.dcloud.PandoraEntryActivity → JS 通过 runtimeMainActivity().getIntent() 读取曾经将过滤器直接配置到内部的io.dcloud.PandoraEntryActivity。但现场安装的1.4.1APK 中该 Activity 最终没有对外导出ADB 发起同类启动请求时报出Permission Denial ... not exported这对应后来“碰卡有反应但打不开 APP”的故障。改用正常入口PandoraEntry后同类冷启动请求返回Status: ok。正常入口还承担运行时初始化因此保留它原有的启动和 Intent 转交流程。这个结论来自本项目实际打包产物和启动排查。后续升级 HBuilderX 时仍应检查最终 APK 合并后的清单。4. 第二步冷启动主动读取后续碰卡持续监听4.1 在 onLaunch 接住第一次碰卡修改位置App.vue 的 onLaunch 和 listenForNfcIntents。冷启动时NFC 数据可能已经存在于 Activity 的启动 Intent 中。后面才注册的newintent监听并不等于能重新收到这次启动事件。因此初始化时执行两个动作// listenForNfcIntents 的核心节选currentHandlerhandler unhandledIntentHandleronUnhandledIntentif(!intentListenerRegistered){plus.globalEvent.addEventListener(newintent,handleNewIntent)intentListenerRegisteredtrue}handleNewIntent()// 注册后主动读取当前启动 IntentApp.vue在onLaunch调用该方法冷启动或后台唤起走handleBackgroundNfc前台碰卡走handleNfcTag。两个入口共用同一套原生 UID 读取逻辑。这里的background是按收到事件时前台调度是否开启进行分类用来选择处理路径它不表示 APP 进程被关闭后仍有 JS 持续运行。冷启动仍由 Android NFC 分发负责唤起应用。4.2 优先读取 EXTRA_ID再读取 Tag.getId()修改位置readCurrentNfcIntent。核心节选如下省略了异常处理和消费标记检查constactivityplus.android.runtimeMainActivity()constNfcAdapterplus.android.importClass(android.nfc.NfcAdapter)constintentactivity.getIntent()if(!intent)returnnullplus.android.importClass(intent)letuidbytesToUid(intent.getByteArrayExtra(NfcAdapter.EXTRA_ID))if(!uid){consttagintent.getParcelableExtra(NfcAdapter.EXTRA_TAG)if(!tag)returnnullplus.android.importClass(tag)uidbytesToUid(tag.getId())}if(!uid)returnnullclearNfcExtras(activity,intent,NfcAdapter)return{uid}EXTRA_ID直接提供字节数组可减少对Tag对象反序列化的依赖没有它时继续尝试EXTRA_TAG。这两个字段的含义可见 NfcAdapter 官方参考。读取时以原生 extra 为依据没有限定“action 必须等于NDEF_DISCOVERED”。这样即使运行时包装了 action只要卡片数据仍在也有机会取得 UID。字节转字符串使用 bytesToUiduid(Number(bytes[index])0xff).toString(16).padStart(2,0) 0xff还原 Java 有符号 bytepadStart(2, 0)保留前导零最后统一转为大写。例如53:10:C7:16:43:00:01转为5310C716430001不反转字节顺序。4.3 读取失败时短暂重试成功后再消费修改位置dispatchCurrentTag 和 clearNfcExtras。启动时立即读一次如果桥接异常、Intent 暂未到位或 UID 暂时为空则每隔 100ms 重试最多再试 5 次。一次读取加五次重试最长约等待 500ms。读取失败时保留原 Intent取得有效 UID 后才移除EXTRA_TAG、EXTRA_ID、EXTRA_NDEF_MESSAGES并设置intent.putExtra(mycheckin.nfc.CONSUMED,true)activity.setIntent(intent)启动链接和其他参数继续保留。后续通知如果再次读到这个已消费的 Intent就直接结束避免把同一次碰卡错误地降级为“请再次碰卡”。重试只能处理数据到达时序不能补出系统没有传来的 UID。重试后仍只有普通mycheckin://链接时现有降级流程会要求再次碰卡验证。4.4 前台开启调度后台保留监听生命周期由 App.vue 管理时机操作作用onLaunch注册唯一的newintent监听并读取当前 Intent处理第一次启动携带的卡片onShowstartNfcScan()开启前台调度处理 APP 已打开时的碰卡onHidestopNfcScan()关闭前台调度保留事件监听继续接收后台唤起时的新 Intent前台使用可变PendingIntent让系统填入卡片数据本实现对 API 31 及以上设置FLAG_MUTABLE同时保留FLAG_UPDATE_CURRENT和FLAG_ACTIVITY_SINGLE_TOP。Android 前台调度官方说明5. 第三步一次碰卡只触发一次提交防重复分成三层分别处理不同情况机制处理的问题Intent 消费标记同一个启动 Intent 被冷启动、后续通知再次读取同 UID 1 秒防抖卡片贴在手机上时连续触发多个扫描通知全局提交锁前后台入口交叠或上一次打卡请求仍在处理中提交锁正常情况下在请求结束时释放30 秒是兜底释放时间并不要求用户每次打卡等待 30 秒。它属于客户端防重措施不能当作服务端永久幂等保证。冷启动、后台唤起时由 handleBackgroundNfc 直接调用打卡接口前台碰卡先暂存标签再由打卡页消费并提交。两条路径都先检查登录状态和现有时间限制。修复后的完整流程如下否是冷启动或后台是前台第一次碰卡Android 匹配 AAR 的 NDEF 过滤器PandoraEntry 初始化并转交原 IntentonLaunch 注册监听并主动读取后续前台或后台 newintent统一读取 EXTRA_ID 或 Tag.getId有效 UID消费标记、防抖、提交锁登录与现有时间限制通过登录引导或失败提示App 直接提交打卡暂存标签打卡页消费后提交保存接口结果交给打卡页按接口结果显示弹窗6. 成功弹窗为什么也需要结果交接读到 UID、服务器确认成功、页面显示成功是三个不同的阶段。api/checkin.js 把实际 UID、打卡点和设备标识提交至POST /api/checkin。当前成功条件为 HTTP200且业务码code 0。页面据此决定显示成功或失败。冷启动时接口可能先于页面返回。如果只发一个页面尚未订阅的事件成功提示就会丢失。1.4.5的处理是App.vue先用setPendingCheckinResult保存已完成请求的结果。当前已在打卡页时发送checkin-result-ready通知其他页面则返回打卡页。页面在onShow和收到通知时都调用showPendingCheckinResult。结果读取后立即移除超过一分钟失效退出登录也会清除。具体代码见 session.js 的结果交接函数 和 打卡页的结果消费方法。这里传递的是已提交请求的结果不把它重新当成待提交的标签因此不会为了弹窗再上传一次。原有猫咪结果组件 checkin-result/index.vue 已接回这条流程成功时展示庆祝动画、星光、确认勾、打卡时间和一次轻振失败时展示实际原因。页面内提示不依赖 Push 模块避免之前“打包时未添加 push 模块”的运行时弹窗。7. 验证结果与复现方法已保存的实机证据证据见 2026-11-04 实机验证记录。该记录位于本地构建目录可能不随 Git 提交因此关键结果列在下表检查实际结果手机vivo V2502AAndroid 161.4.2 / 102首次读卡验证碰卡前进程不存在第一次碰卡启动新进程取得5310C7164300011.4.3 / 103上传验证冷启动碰卡后HTTP200、业务码0、success: true服务器流水总数从87增至88新增 ID171时间2026-11-04 15:21:37成功 POST 次数观察到1次钉钉状态dingtalkSync: pending当时未验证最终回执以上证明首次 UID 读取和本应用服务器的打卡流水上传已通过实机验证。钉钉排队状态需要与最终同步结果区分。1.4.5 / 105已通过 30 项回归、4 种手机尺寸/状态预览以及最终 APK 的签名、版本、原生入口和编译资源检查截至本文整理时该版本尚未覆盖安装并再次实机碰卡。构建检查见 1.4.5 校验记录。本地回归与清单检查在根目录下运行node--test tests/nfc-checkin.test.cjs tests/checkin-window.test.cjs powershell-NoProfile-File tests/check-nfc-manifest.ps1回归覆盖冷启动已有 Intent、Intent 延迟到达、仅有EXTRA_ID、桥接短暂失败、前后台切换、重复通知、请求失败以及接口先返回或页面先加载两种结果交接顺序。时间窗测试调用现有函数校验原边界。手机连接并允许 USB 调试后可检查已安装 APK 的三类入口与版本powershell-NoProfile-File tests/check-nfc-device.ps1-AdbPathD:\Hbuilderx\HBuilderX\plugins\launcher-tools\tools\adbs\adb.exe该脚本应确认 AAR、mycheckin和 Tag 三类请求均匹配对外导出的io.dcloud.PandoraEntry且手机版本与源码一致。它只查询配置不模拟实际卡片。实际验收时登录后回到桌面退出 NFC Tools并确认应用进程已结束、不是仅切到后台也不是被设置为系统强行停止状态。保持手机解锁在允许时段碰实体卡一次并移开核对启动、接口结果和服务器新增流水再分别检查后台唤起、前台碰卡与连续通知。正式包的上传和远端流水摘要同时写入 Android 日志可通过以下命令查看D:\Hbuilderx\HBuilderX\plugins\launcher-tools\tools\adbs\adb.exelogcat-s NfcCheckin:I日志中的 UID、打卡点、HTTP 状态、业务码与远端流水用于串联读卡到上传的过程现有诊断日志不输出登录 Token。为什么必须完整打包NFC 启动入口属于原生清单。修改根目录AndroidManifest.xml后需要重新云打包或生成包含该配置的自定义基座热更新页面资源无法更新手机已安装 APK 的 Activity 入口。覆盖安装继续使用相同包名与签名并检查最终 APK 和已安装版本。ADB 能唤起 Activity 只能证明入口可达真实的 Tag/UID 数据仍需用实体卡验证。8. 后续维护时保留的关键点AAR 的 NDEF 过滤器继续挂在本项目正常启动入口PandoraEntry升级运行时后检查合并产物。onLaunch同时执行“注册监听”和“主动读取”onHide只停止前台调度保留newintent监听。取得有效 UID 后再消费 NFC extra保留已消费标记读取失败时允许短暂重试。冷启动/后台与前台各自提交一次已完成请求的结果只用于展示。本次改动的核心是让第一次碰卡产生的原生数据从系统启动入口一直传到 JS 提交逻辑重试、防重和结果交接则分别处理初始化时序、重复通知与页面加载时序。
NFC 冷启动问题修复原理本文说明本项目为什么曾经需要碰卡两次以及如何通过 Android 启动入口、Intent 读取和页面结果交接让第一次碰卡即可唤起应用、获取 UID 并提交打卡。前端项目代码链接 https://github.com/bigxinyuan222/NFC-TAG1. 修复结论这次修复贯通了两段流程Android 把带卡片数据的 NFC Intent 交给正确的启动入口应用启动后立即读取这个 Intent再持续监听后续碰卡。原来的现象是APP 未打开时第一次碰卡只能启动 APPAPP 打开后再碰一次才取得 UID。第二次能够读到说明前台读卡流程可以工作但首次启动时的 NFC 数据交接不完整。修复后的关键变化如下环节原来存在的问题现在的处理卡片内容匹配现场卡片写的是包名启动记录仅处理mycheckin://不匹配增加 AAR 对应的 NDEF 过滤规则原生启动入口测试时曾把 NFC 入口挂到未对外导出的内部 Activity出现无法拉起 APP使用io.dcloud.PandoraEntry正常启动入口冷启动读取只等后续事件会漏掉已放进启动 Intent 的卡片onLaunch注册监听后立即主动读取当前 Intent初始化时序初次读取时桥接或卡片数据可能尚未就绪保留数据每隔 100ms 重试最多再试 5 次重复通知同一次启动可能被多次通知消费标记、UID 防抖、提交锁共同防重结果展示上传可能早于页面就绪只有事件通知容易漏掉弹窗先保存结果再由页面一次性消费并显示动画2. 现场卡片实际写入了什么NFC Tools 中的“启动应用”写入的是 Android Application Record简称 AARNDEF 记录类型External / android.com:pkg 记录内容uni.app.UNI35FA817 整条记录长度36 字节 本次实机卡片 UID5310C716430001现场记录的复现数据保存在 nfc-package-record.json。包名用于选择要启动的应用硬件 UID 用于本项目的卡片校验两者分别从不同位置取得。Android 对 External 类型记录使用vnd.android.nfc://ext/记录类型进行 Intent 匹配所以本卡片对应vnd.android.nfc://ext/android.com:pkg。AAR 还允许系统按包名选择应用因此“APP 被打开”本身不足以证明具体 Activity 已收到本次 NFC 数据。Android 官方说明本次排查据卡片内容、入口配置和复现现象定位到首次启动的分发链路。没有改写卡片也没有用包名或协议链接代替 UID。3. 第一步修正 Android 原生启动入口修改位置AndroidManifest.xml。现有 NFC 权限继续由 manifest.json 配置根目录清单补充 Activity 的 NFC 入口?xml version1.0 encodingutf-8?manifestxmlns:androidhttp://schemas.android.com/apk/res/androidpackageuni.app.UNI35FA817applicationactivityandroid:nameio.dcloud.PandoraEntryandroid:exportedtrueintent-filteractionandroid:nameandroid.nfc.action.NDEF_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT/dataandroid:schemevnd.android.nfcandroid:hostextandroid:path/android.com:pkg//intent-filterintent-filteractionandroid:nameandroid.nfc.action.NDEF_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT/dataandroid:schememycheckin//intent-filterintent-filteractionandroid:nameandroid.nfc.action.TAG_DISCOVERED/categoryandroid:nameandroid.intent.category.DEFAULT//intent-filter/activity/application/manifest三个过滤器分别负责现场包名启动卡片、mycheckin协议卡片以及走到TAG_DISCOVERED分发阶段的卡片。TAG_DISCOVERED是兜底入口不能替代现场 AAR 的精确匹配。为什么选择 PandoraEntry本次排查的 DCloud 运行时启动链路是系统 NFC Intent → io.dcloud.PandoraEntry → 初始化应用运行时 → 把原 NFC Intent 转交给 io.dcloud.PandoraEntryActivity → JS 通过 runtimeMainActivity().getIntent() 读取曾经将过滤器直接配置到内部的io.dcloud.PandoraEntryActivity。但现场安装的1.4.1APK 中该 Activity 最终没有对外导出ADB 发起同类启动请求时报出Permission Denial ... not exported这对应后来“碰卡有反应但打不开 APP”的故障。改用正常入口PandoraEntry后同类冷启动请求返回Status: ok。正常入口还承担运行时初始化因此保留它原有的启动和 Intent 转交流程。这个结论来自本项目实际打包产物和启动排查。后续升级 HBuilderX 时仍应检查最终 APK 合并后的清单。4. 第二步冷启动主动读取后续碰卡持续监听4.1 在 onLaunch 接住第一次碰卡修改位置App.vue 的 onLaunch 和 listenForNfcIntents。冷启动时NFC 数据可能已经存在于 Activity 的启动 Intent 中。后面才注册的newintent监听并不等于能重新收到这次启动事件。因此初始化时执行两个动作// listenForNfcIntents 的核心节选currentHandlerhandler unhandledIntentHandleronUnhandledIntentif(!intentListenerRegistered){plus.globalEvent.addEventListener(newintent,handleNewIntent)intentListenerRegisteredtrue}handleNewIntent()// 注册后主动读取当前启动 IntentApp.vue在onLaunch调用该方法冷启动或后台唤起走handleBackgroundNfc前台碰卡走handleNfcTag。两个入口共用同一套原生 UID 读取逻辑。这里的background是按收到事件时前台调度是否开启进行分类用来选择处理路径它不表示 APP 进程被关闭后仍有 JS 持续运行。冷启动仍由 Android NFC 分发负责唤起应用。4.2 优先读取 EXTRA_ID再读取 Tag.getId()修改位置readCurrentNfcIntent。核心节选如下省略了异常处理和消费标记检查constactivityplus.android.runtimeMainActivity()constNfcAdapterplus.android.importClass(android.nfc.NfcAdapter)constintentactivity.getIntent()if(!intent)returnnullplus.android.importClass(intent)letuidbytesToUid(intent.getByteArrayExtra(NfcAdapter.EXTRA_ID))if(!uid){consttagintent.getParcelableExtra(NfcAdapter.EXTRA_TAG)if(!tag)returnnullplus.android.importClass(tag)uidbytesToUid(tag.getId())}if(!uid)returnnullclearNfcExtras(activity,intent,NfcAdapter)return{uid}EXTRA_ID直接提供字节数组可减少对Tag对象反序列化的依赖没有它时继续尝试EXTRA_TAG。这两个字段的含义可见 NfcAdapter 官方参考。读取时以原生 extra 为依据没有限定“action 必须等于NDEF_DISCOVERED”。这样即使运行时包装了 action只要卡片数据仍在也有机会取得 UID。字节转字符串使用 bytesToUiduid(Number(bytes[index])0xff).toString(16).padStart(2,0) 0xff还原 Java 有符号 bytepadStart(2, 0)保留前导零最后统一转为大写。例如53:10:C7:16:43:00:01转为5310C716430001不反转字节顺序。4.3 读取失败时短暂重试成功后再消费修改位置dispatchCurrentTag 和 clearNfcExtras。启动时立即读一次如果桥接异常、Intent 暂未到位或 UID 暂时为空则每隔 100ms 重试最多再试 5 次。一次读取加五次重试最长约等待 500ms。读取失败时保留原 Intent取得有效 UID 后才移除EXTRA_TAG、EXTRA_ID、EXTRA_NDEF_MESSAGES并设置intent.putExtra(mycheckin.nfc.CONSUMED,true)activity.setIntent(intent)启动链接和其他参数继续保留。后续通知如果再次读到这个已消费的 Intent就直接结束避免把同一次碰卡错误地降级为“请再次碰卡”。重试只能处理数据到达时序不能补出系统没有传来的 UID。重试后仍只有普通mycheckin://链接时现有降级流程会要求再次碰卡验证。4.4 前台开启调度后台保留监听生命周期由 App.vue 管理时机操作作用onLaunch注册唯一的newintent监听并读取当前 Intent处理第一次启动携带的卡片onShowstartNfcScan()开启前台调度处理 APP 已打开时的碰卡onHidestopNfcScan()关闭前台调度保留事件监听继续接收后台唤起时的新 Intent前台使用可变PendingIntent让系统填入卡片数据本实现对 API 31 及以上设置FLAG_MUTABLE同时保留FLAG_UPDATE_CURRENT和FLAG_ACTIVITY_SINGLE_TOP。Android 前台调度官方说明5. 第三步一次碰卡只触发一次提交防重复分成三层分别处理不同情况机制处理的问题Intent 消费标记同一个启动 Intent 被冷启动、后续通知再次读取同 UID 1 秒防抖卡片贴在手机上时连续触发多个扫描通知全局提交锁前后台入口交叠或上一次打卡请求仍在处理中提交锁正常情况下在请求结束时释放30 秒是兜底释放时间并不要求用户每次打卡等待 30 秒。它属于客户端防重措施不能当作服务端永久幂等保证。冷启动、后台唤起时由 handleBackgroundNfc 直接调用打卡接口前台碰卡先暂存标签再由打卡页消费并提交。两条路径都先检查登录状态和现有时间限制。修复后的完整流程如下否是冷启动或后台是前台第一次碰卡Android 匹配 AAR 的 NDEF 过滤器PandoraEntry 初始化并转交原 IntentonLaunch 注册监听并主动读取后续前台或后台 newintent统一读取 EXTRA_ID 或 Tag.getId有效 UID消费标记、防抖、提交锁登录与现有时间限制通过登录引导或失败提示App 直接提交打卡暂存标签打卡页消费后提交保存接口结果交给打卡页按接口结果显示弹窗6. 成功弹窗为什么也需要结果交接读到 UID、服务器确认成功、页面显示成功是三个不同的阶段。api/checkin.js 把实际 UID、打卡点和设备标识提交至POST /api/checkin。当前成功条件为 HTTP200且业务码code 0。页面据此决定显示成功或失败。冷启动时接口可能先于页面返回。如果只发一个页面尚未订阅的事件成功提示就会丢失。1.4.5的处理是App.vue先用setPendingCheckinResult保存已完成请求的结果。当前已在打卡页时发送checkin-result-ready通知其他页面则返回打卡页。页面在onShow和收到通知时都调用showPendingCheckinResult。结果读取后立即移除超过一分钟失效退出登录也会清除。具体代码见 session.js 的结果交接函数 和 打卡页的结果消费方法。这里传递的是已提交请求的结果不把它重新当成待提交的标签因此不会为了弹窗再上传一次。原有猫咪结果组件 checkin-result/index.vue 已接回这条流程成功时展示庆祝动画、星光、确认勾、打卡时间和一次轻振失败时展示实际原因。页面内提示不依赖 Push 模块避免之前“打包时未添加 push 模块”的运行时弹窗。7. 验证结果与复现方法已保存的实机证据证据见 2026-11-04 实机验证记录。该记录位于本地构建目录可能不随 Git 提交因此关键结果列在下表检查实际结果手机vivo V2502AAndroid 161.4.2 / 102首次读卡验证碰卡前进程不存在第一次碰卡启动新进程取得5310C7164300011.4.3 / 103上传验证冷启动碰卡后HTTP200、业务码0、success: true服务器流水总数从87增至88新增 ID171时间2026-11-04 15:21:37成功 POST 次数观察到1次钉钉状态dingtalkSync: pending当时未验证最终回执以上证明首次 UID 读取和本应用服务器的打卡流水上传已通过实机验证。钉钉排队状态需要与最终同步结果区分。1.4.5 / 105已通过 30 项回归、4 种手机尺寸/状态预览以及最终 APK 的签名、版本、原生入口和编译资源检查截至本文整理时该版本尚未覆盖安装并再次实机碰卡。构建检查见 1.4.5 校验记录。本地回归与清单检查在根目录下运行node--test tests/nfc-checkin.test.cjs tests/checkin-window.test.cjs powershell-NoProfile-File tests/check-nfc-manifest.ps1回归覆盖冷启动已有 Intent、Intent 延迟到达、仅有EXTRA_ID、桥接短暂失败、前后台切换、重复通知、请求失败以及接口先返回或页面先加载两种结果交接顺序。时间窗测试调用现有函数校验原边界。手机连接并允许 USB 调试后可检查已安装 APK 的三类入口与版本powershell-NoProfile-File tests/check-nfc-device.ps1-AdbPathD:\Hbuilderx\HBuilderX\plugins\launcher-tools\tools\adbs\adb.exe该脚本应确认 AAR、mycheckin和 Tag 三类请求均匹配对外导出的io.dcloud.PandoraEntry且手机版本与源码一致。它只查询配置不模拟实际卡片。实际验收时登录后回到桌面退出 NFC Tools并确认应用进程已结束、不是仅切到后台也不是被设置为系统强行停止状态。保持手机解锁在允许时段碰实体卡一次并移开核对启动、接口结果和服务器新增流水再分别检查后台唤起、前台碰卡与连续通知。正式包的上传和远端流水摘要同时写入 Android 日志可通过以下命令查看D:\Hbuilderx\HBuilderX\plugins\launcher-tools\tools\adbs\adb.exelogcat-s NfcCheckin:I日志中的 UID、打卡点、HTTP 状态、业务码与远端流水用于串联读卡到上传的过程现有诊断日志不输出登录 Token。为什么必须完整打包NFC 启动入口属于原生清单。修改根目录AndroidManifest.xml后需要重新云打包或生成包含该配置的自定义基座热更新页面资源无法更新手机已安装 APK 的 Activity 入口。覆盖安装继续使用相同包名与签名并检查最终 APK 和已安装版本。ADB 能唤起 Activity 只能证明入口可达真实的 Tag/UID 数据仍需用实体卡验证。8. 后续维护时保留的关键点AAR 的 NDEF 过滤器继续挂在本项目正常启动入口PandoraEntry升级运行时后检查合并产物。onLaunch同时执行“注册监听”和“主动读取”onHide只停止前台调度保留newintent监听。取得有效 UID 后再消费 NFC extra保留已消费标记读取失败时允许短暂重试。冷启动/后台与前台各自提交一次已完成请求的结果只用于展示。本次改动的核心是让第一次碰卡产生的原生数据从系统启动入口一直传到 JS 提交逻辑重试、防重和结果交接则分别处理初始化时序、重复通知与页面加载时序。
