ZhctTrayBindingMachine 性能测试埋点方案

版本：V1.0（待确认）

目的：在不改变人盘绑定业务结果、不新增网络依赖的前提下，为每一笔绑盘流程生成可离线解析的性能与结果记录。

1. 方案结论

建议采用“本地会话轨迹日志”而不是第三方埋点平台：每次有效读到餐盘后创建一个会话，关键节点写入 /sdcard/Log/ 下按日追加的文本文件；每行使用固定键值格式，后续可通过 ADB 拉取并自动汇总为测试报告。

现有工程已经使用 LocalFileRecorder 写入 /sdcard/Log/，本方案仅在已有主流程节点增加轻量记录，不上传人员信息、不改变接口请求或页面行为。

埋点硬约束：不影响现有业务

埋点仅旁路读取当前状态和时间，不修改绑盘状态机、页面跳转、读卡器/扫码器/相机启停、超时策略或接口参数。
日志写入必须异步执行；写入异常、存储不可用或格式化失败只能静默降级，不得阻塞主线程、抛出业务异常或改变本笔绑定结果。
不新增网络请求、第三方 SDK、数据库表或可见页面；不调整现有成功/失败提示和音效。
每个埋点调用都不得成为主流程的前置条件；删除或关闭埋点后，现有流程行为应与改造前一致。

2. 统计口径

指标	起点	终点	说明
读盘处理耗时	收到有效餐盘条码回调	已切入人员识别流程	衡量设备收到餐盘码后的应用处理与页面切换，不包含用户实际把餐盘放上读头前的物理时间。
二维码识别耗时	进入人员识别流程并启动二维码读取器	收到有效二维码数据	反映等待扫码到收到码的时间。
刷卡识别耗时	进入人员识别流程并启动刷卡读取器	收到有效卡号	反映等待刷卡到收到卡号的时间。
人脸识别耗时	开始本次人脸识别	获得有效人员匹配结果或失败/超时	记录匹配结果与失败原因。
绑定接口耗时	调用 `bindPlate` 前	收到接口回调	分别记录 HTTP/网络异常和业务返回码；HTTP 200 但业务失败不记为成功。
移盘复位耗时	收到移盘事件	完成返回等待放盘状态	记录移盘前所在流程状态，验证不会残留上一笔信息。
全流程耗时	收到有效餐盘条码回调	收到绑定最终响应；若未绑定则记录中断原因	用于整体体验统计；绑定成功后移盘时另补充“含移盘复位总耗时”。

3. 每笔会话的记录字段

字段	示例	说明
`session_id`	`20260714-135049-12`	每个有效餐盘生成一次；新餐盘、移盘或重置后结束旧会话。
`event`	`TRAY_ACCEPTED`	固定事件名，见第 4 节。
`at_ms`	`1720936249485`	设备当前毫秒时间，用于精确差值计算。
`elapsed_ms`	`1142`	当前事件相对会话起点或相对节点起点的耗时。
`tray_code`	`8888****`	仅记录脱敏餐盘码；报告可按需要显示完整码，但默认日志不写完整人员信息。
`recognition_method`	`QR` / `CARD` / `FACE`	实际先完成识别的方式。
`result`	`SUCCESS` / `FAIL` / `CANCELLED`	事件结果。
`reason`	`TRAY_ALREADY_BOUND`	稳定的错误分类，不依赖展示文案。
`api_code`	`0` / `1`	仅绑定接口结果事件记录。
`flow_state`	`RECOGNIZING`	用于排查串盘或旧结果回写。

不记录姓名、头像、完整 UUID、完整卡号或完整二维码。若排查需要关联人员，记录不可逆短摘要或由现场另行提供对应关系。

4. 必需埋点项目

编号	事件名	建议代码节点	记录内容	对应统计
T-01	`SESSION_START`	`handleTrayCodeScanned` 通过合法性/防抖后	新建会话、餐盘脱敏码、当前流程状态	全流程起点
T-02	`TRAY_RECOGNITION_READY`	`beginRecognitionWithTrayCode` 完成页面切换调用后	读盘处理耗时	读盘处理耗时
T-03	`QR_READER_READY`	`openQrCodeScanner` 成功打开后	二维码等待开始时间	二维码识别耗时
T-04	`QR_RESULT`	`handleQrCodeResult` 校验通过/失败处	耗时、二维码类型（人员/消费码/非法）、结果原因	二维码识别耗时
T-05	`CARD_READER_READY`	`openSwipeCard` 成功打开后	刷卡等待开始时间	刷卡识别耗时
T-06	`CARD_RESULT`	刷卡 `onResult` 通过状态校验后	耗时、卡号短摘要、结果	刷卡识别耗时
T-07	`FACE_START`	`startFaceRecognitionForCurrentSession` 实际启动后	人脸开始时间	人脸识别耗时
T-08	`FACE_RESULT`	人脸成功、失败及超时分支	耗时、成功/失败、失败分类	人脸识别耗时
T-09	`RECOGNITION_COMPLETE`	`completeRecognition`	实际完成的识别方式、从会话起点的耗时	识别链路与方式判定
T-10	`BIND_REQUEST`	`uploadInfo` 发起 `bindPlate` 前	API 开始时间、会话、识别方式	绑定接口耗时
T-11	`BIND_RESPONSE`	`bindStaffAndTray` 回调的成功、业务失败、网络失败分支	API 耗时、业务码、错误分类	绑定接口耗时、成功率
T-12	`TRAY_REMOVED`	`handleTrayRemoved`	移盘时间、移盘前状态	移盘复位耗时
T-13	`FLOW_RESET`	`resetFlowToScanning` 完成后	移盘/超时/人工重置原因、复位耗时	移盘复位、恢复能力
T-14	`SESSION_END`	成功绑定后移盘复位，或异常/超时/新餐盘中断时	会话总耗时、最终结果、结束原因	完整性校验

5. 错误分类

分类	触发条件
`TRAY_INVALID`	餐盘码为空或不合法。
`TRAY_DUPLICATE`	同一餐盘重复读码被防抖拦截。
`QR_INVALID`	二维码为空、格式不符合人员/消费码规则。
`CARD_INVALID`	卡号为空或读取器返回无效数据。
`FACE_NOT_FOUND`	未匹配到已录入人员。
`FACE_TIMEOUT` / `RECOGNITION_TIMEOUT`	人脸或通用人员识别超时。
`NETWORK_UNAVAILABLE`	发起绑定前网络不可用。
`NETWORK_ERROR`	绑定接口网络/解析异常。
`TRAY_ALREADY_BOUND`	接口返回“此餐盘已绑定”。
`BIND_BUSINESS_REJECTED`	其他非零业务返回码。
`TRAY_REMOVED` / `MANUAL_RESET`	操作未完成即移盘或人工复位。

6. 日志格式与保留

建议新增独立文件前缀 binding_trace_，避免与现有 local_log_ 的自由文本混杂。每行一条 UTF-8 记录，例如：

2026-07-14 13:50:49.485|session_id=20260714-135049-12|event=SESSION_START|at_ms=1720936249485|tray_code=8888****|flow_state=SCANNING_TRAY
2026-07-14 13:50:50.860|session_id=20260714-135049-12|event=BIND_REQUEST|elapsed_ms=1375|recognition_method=QR
2026-07-14 13:50:51.080|session_id=20260714-135049-12|event=BIND_RESPONSE|elapsed_ms=220|result=FAIL|api_code=1|reason=TRAY_ALREADY_BOUND

继续沿用现有按日文件、异步写入与低存储空间清理机制。
对性能统计读取 binding_trace_YYYYMMDD.txt；不再依赖易覆盖的 logcat。
测试结束后通过 ADB 拉取该文件，由报告脚本按会话聚合。

7. 实施任务清单

任务 1：会话与轨迹记录基础

新增轻量记录器，生成会话号、统一事件格式、耗时计算、餐盘/身份信息脱敏，并复用异步文件写入。

验收：不影响正常绑盘流程与接口参数。
验收：每行都含 session_id、event、at_ms、result。
验收：设备本地生成独立的 binding_trace_YYYYMMDD.txt。

任务 2：读盘、识别与复位节点

在 T-01 至 T-09、T-12 至 T-14 对应节点添加记录；识别方式以实际完成回调判定。

验收：二维码、刷卡、人脸任一方式都能生成完整节点序列。
验收：无效码、超时、移盘、新餐盘中断均有结束原因。
验收：同一会话不会因旧异步回调生成错误成功事件。

任务 3：绑定接口节点

在绑定请求、响应、网络异常和业务失败分支写入 T-10、T-11。

验收：能区分接口耗时、HTTP/网络失败与业务拒绝。
验收：“餐盘已绑定”记录为 TRAY_ALREADY_BOUND，而不是绑定成功。

检查点：设备验证

用未绑定餐盘分别完成二维码/刷卡/人脸中的现场启用方式。
完成一次“中途移盘”和一次“识别超时”。
拉取本地轨迹文件，确认每笔都有闭合的 SESSION_START 至 SESSION_END。
统计各指标的次数、平均值、最大值、P95、成功率和失败原因分布。

8. 不纳入本次范围

不上传行为日志到新服务端，不引入第三方 SDK。
不新增可见页面、测试开关或对用户的提示。
不记录姓名、头像、完整证件/卡号/二维码等敏感信息。
不把“用户把餐盘放到读头”的物理动作计入读盘处理耗时；该起点在现有硬件回调前不可观测。

9. 请确认的决策

是否同意使用本地独立轨迹文件 binding_trace_YYYYMMDD.txt？
是否同意默认只写脱敏标识，现场需要完整餐盘码时再通过人工关联？
现场验收是否采用：平均值、最大值、P95、成功率和失败原因分布这五类输出？
是否需要额外记录设备 CPU、内存、网络类型？建议本期先不纳入，避免扩大范围。

10. 埋点硬约束与验收

埋点仅旁路读取当前状态和时间，不修改绑盘状态机、页面跳转、读卡器/扫码器/相机启停、超时策略或接口参数。
日志写入必须异步执行；写入异常、存储不可用或格式化失败只能静默降级，不得阻塞主线程、抛出业务异常或改变本笔绑定结果。
不新增网络请求、第三方 SDK、数据库表或可见页面；不调整现有成功/失败提示和音效。
每个埋点调用都不得成为主流程的前置条件；删除或关闭埋点后，现有流程行为应与改造前一致。
验收须包含一次模拟日志写入失败：读盘、识别、绑定和移盘复位仍按原逻辑正常执行。

11. 已确认的配置决策

使用本地独立轨迹文件 binding_trace_YYYYMMDD.txt。
在现有高级设置页提供“性能测试记录”开关，默认关闭；关闭时不创建会话、不写入性能轨迹文件。
轨迹仅保存脱敏餐盘码与识别方式，不保存姓名、头像、完整 UUID、卡号或二维码。
测试报告输出次数、平均值、最大值、P95、成功率和失败原因分布；CPU、内存与网络类型不纳入本期。