李进 / checkInCar

  # 手持核销车辆系统 — 开发方案
  
  > 状态：**方案已按评审意见细化界面与流程，待最终确认后开发（暂不写代码）**
  > 日期：2026-09-25
  > 目标设备：新大陆 NLS-MT95L 手持机（当前 ADB 已连接：MT95LTFFD00631），同时兼容通用安卓手机
  > 识别引擎：百度车牌识别安卓离线 SDK V7.5
  > 包名（已确认）：com.ectrip.checkincar
  > 本期策略：**先模拟跑通全流程（识别 + 核销），百度 SDK 同步集成但等授权到位后启用**
  > 本次细化：第 5 章界面与交互（线框图 + 核销页 5 状态机 + 异常分支 + 硬件键/反馈 + 适配）
  
  ---
  
  ## 1. 需求概述
  
  在手持机上开发一个竖屏安卓 App，供核销员工使用：
  
  1. **主界面**：两个大按钮 —— 「车辆核销」「系统设置」。
  2. **车辆核销流程**：调起后置摄像头拍摄/对准车牌 → 调用百度离线 SDK 识别车牌 → 展示识别结果并允许人工修正 → 调用后台预约平台接口完成核销 → 展示核销结果（预约信息）。
  3. **系统设置页**：显示/配置
     - 本机 IP 地址（自动获取、只读、可刷新）
     - 本机 MAC 地址（自动获取、只读）
     - 核销员工 ID（可编辑保存）
     - 后台核销地址（可编辑保存）
     - （附加）设备 SN、百度授权设备指纹、授权状态、识别引擎与模拟开关、版本号
  4. 今天（第一期）后台与识别均先**模拟**，界面与流程按真实业务设计，后续只替换引擎与接口实现，不改界面。
  
  ---
  
  ## 2. 实测环境
  
  ### 2.1 目标手持机（ADB 实测）
  
  | 项目 | 实测值 |
  |---|---|
  | 厂商/型号 | Newland（新大陆）NLS-MT95L |
  | 序列号 SN | MT95LTFFD00631 |
  | 系统 | Android 11（API 30），固件 MT95L-X_V1.01.002_111006 |
  | CPU ABI | arm64-v8a（8 核） |
  | 内存/存储 | 2.8GB RAM；/data 20GB（仅用 593MB） |
  | 屏幕 | 720 × 1440，density 320（xhdpi），竖屏 |
  | 摄像头 | 后摄 + 前摄，支持自动对焦、闪光灯，camera level FULL |
  | 网络 | WLAN（wlan0），当前 IP `192.168.50.70/24`，SSID HUAWEI-ECTRIP-5G |
  | MAC | `a4:e8:a3:8d:82:56`（`/sys/class/net/wlan0/address`，权限 `-r--r--r--`，**App 无需权限可直接读取真实 MAC**，已实测节点存在且全局可读） |
  | 百度设备指纹（实测） | **`153DA2A38757D7D7016E76F8EE0AACE367`**（35 位大写。用官方 demo APK 7.5 在本机激活页实测取得，授权绑的就是它，**不是 SN**；正式 App 用同一套 jar 预期取值一致，以 App 设置页实显为准） |
  
  ### 2.2 开发机（macOS）
  
  - Android Studio 已安装；Android SDK 平台 19~36 齐全，build-tools 含 34.0.0
  - JDK 8 / 11 / 17 / 19 均有（新工程用 **JDK 17**）
  - adb 路径 `/opt/homebrew/bin/adb`，设备连接正常
  
  ### 2.3 百度 SDK 物料
  
  路径：`/Volumes/USERDATA/anroidprj/Baidu_OCR_platenumber_OfflineSDK_Android_7.5-2/7.5车牌sdk/`
  
  | 文件 | 用途 |
  |---|---|
  | `sdk.zip` | 集成物料：3 个 jar + 两种 ABI 的 so + 模型资源 |
  | `ocr-sdk-offline-demo.zip` | 官方 demo 工程（Gradle，Java，已分析源码） |
  | `车牌识别安卓离线SDK_V7.5用户接入文档.pdf` | 官方接入文档（13 页，已逐页阅读） |
  | `车牌识别SDK_7.5.0.apk` | 官方演示 APK |
  | `readme.txt` | 模型与授权文件放 assets 的说明 |
  
  ---
  
  ## 3. 百度 SDK V7.5 技术分析（结论）
  
  ### 3.1 包内容（sdk.zip）
  
  **Java 依赖（3 个 jar）**
  
  - `libocrgveplate.jar` —— 车牌识别引擎（核心类 `com.baidu.vis.ocrgve.plate.OcrgveEnginePlate`）
  - `bd_unifylicense.jar` —— 统一授权组件（`AndroidLicenser` / `BDLicenseActivator`）
  - `liantian.jar` —— 安全模块
  
  **Native 库（两种 ABI 都提供，本设备用 arm64-v8a）**
  
  - `libocrgveplate.so`（arm64 约 6.9MB）、`libpaddle_light_api_shared_visocr.so`（PaddleLite 推理，约 4.4MB）、`libbd_unifylicense.so`、`libliantian.so`
  
  **模型资源（assets，约 30MB，整目录拷入工程 assets）**
  
  - 目录名固定：`assets/ocrgve_resource_plate/`
  - 含 5 个加密模型（`.dpmodel.encrypted`：车牌检测、主分类、单行识别 a/b、车牌颜色）、`configure.ini`、字典与分类配置等
  - `initFromAssets()` 内部按固定目录名加载，**目录名不可改**
  
  ### 3.2 支持范围
  
  - Android 6.0+（文档声明），提供 armeabi-v7a / arm64-v8a；本设备 arm64-v8a 完全匹配
  - 纯 Java 接口，离线推理（PaddleLite CPU），识别不依赖网络；**网络仅授权时需要**
  
  ### 3.3 核心 API（已通过 javap 反编译核对）
  
  ```java
  // 算法 ID（车牌识别固定值，demo 实测 = 7，以 getAlgorithmId() 返回为准）
  int algId = OcrgveEnginePlate.getAlgorithmId();
  
  // ① 授权（必须在子线程调用；成功后才能初始化模型）
  //    方式A：本地授权文件（从控制台下载，放 assets）
  AndroidLicenser.ErrorCode ret = AndroidLicenser.getInstance()
          .authFromFile(context, licenseKey, licenseFileName, true/*isRemote*/, algId);
  //    方式B：在线（单台/批量）序列号激活，返回 0 成功
  int ret = BDLicenseActivator.initLicenseOnLine(context, serialKey, "", algId);
  
  // 设备指纹（控制台绑定授权用）
  String deviceId = AndroidLicenser.getDeviceId(context);
  // 授权信息（有效期等）
  BDLicenseAuthInfo info = AndroidLicenser.getInstance().authGetAuthInfo(context, algId); // expireTime
  
  // ② 初始化模型（子线程；授权成功后调用；全局只初始化一次，重复初始化返回 MULTI_INIT=6）
  OcrgveEnginePlate engine = new OcrgveEnginePlate();
  OcrgveEnginePlate.setPreFiltering(false);      // 纯背景前置过滤，可选
  int code = engine.initFromAssets(context);    // 0=成功
  
  // ③ 识别（子线程）
  ArrayList<OcrgvesdkResponsePlate> results =
          engine.processOcrgvesdk(rgbaBytes, 10/*PIX_RGBA*/, width, height, 0/*orientation*/);
  
  // ④ 释放（App 退出时）
  engine.uninit();
  ```
  
  **识别结果 `OcrgvesdkResponsePlate` 字段**
  
  | 字段 | 含义 |
  |---|---|
  | `name` | 类型，取 `"plate_number"` 为车牌结果 |
  | `mystring` | **车牌号字符串**（支持新能源 8 位等） |
  | `color` | 颜色：`blue/yellow/green/white/black`（蓝/黄/绿/白/黑） |
  | `detScore` | 检测置信度 |
  | `recgProb[]` | 每个字符的识别置信度（可用最小值做整体过滤，demo 默认阈值 0.8） |
  | `coords[8]` | 车牌四角坐标 |
  
  **初始化错误码**：0 成功、1 未知、2 非法参数、3 内部错误、4 鉴权错误、5 未初始化、6 重复初始化、7 图片处理错误、9 模型文件未找到。
  
  **授权错误码（高频）**：7 设备 ID 校验错误、8 **包名（applicationId）校验错误**、9 过期时间不正确、11 授权已过期、12 本地文件读取失败、13 远程数据拉取失败。
  
  ### 3.4 授权机制（关键约束，影响工程决策）
  
  > **重要澄清：百度授权绑定的是「设备指纹 Device-id」，不是设备硬件 SN。**
  >
  > | 标识 | 是什么 | 怎么取 | 用途 |
  > |---|---|---|---|
  > | **百度设备指纹 Device-id** | 百度安全模块（liantian）综合多因子硬件信息生成的一串大写 ID（带 `fingerVersion` 指纹版本） | 代码 `AndroidLicenser.getDeviceId(context)`；或 demo logcat 搜 `BDLicenseLocalInfo`（文档 2.5 节原文：「设备指纹即 deviceid」） | **百度离线授权的唯一设备标识，控制台必须绑它** |
  > | 设备硬件 SN | 厂商出厂序列号 `ro.serialno`（本机 = `MT95LTFFD00631`，与 ADB 设备号一致） | `Build.SERIAL` / 属性读取 / 设置页可手填兜底 | 仅我方资产管理、核销上报告备用，**百度授权不用它** |
  >
  > 注：demo 激活页把 Device-id 标注为「序列号」是口语化叫法，二者不是一回事。
  >
  > **指纹构成（已反编译 liantian.jar 字节码核实）**：`com.baidu.liantian.ac.LH.getId()` 采集 `ANDROID_ID`、IMEI/IMSI/SIM 序列号、**直接读取 `/sys/class/net/wlan0/address` 与 `eth0/address` 的真实 MAC（键名 rpmacadd）**、WiFi BSSID、Build 硬件信息（MODEL/PRODUCT/BOARD/HARDWARE/MANUFACTURER/DEVICE/DISPLAY、CPU_ABI）等综合生成。
  >
  > **稳定性（文档 6.9）**：刷机、更换硬件会导致指纹变化；安卓系统升级、App 卸载重装、恢复出厂值不会。
  >
  > **本机实测（2026-09-25，官方 demo 7.5 激活页）**：设备指纹 = **`153DA2A38757D7D7016E76F8EE0AACE367`**，页面原文要求「点击复制下方本机硬件指纹 → 百度云控制台：离线 SDK 管理-单台设备授权-离线激活」。同时 logcat 显示 Android 11 已拒绝第三方读取 IMEI（`TelephonyPermissions ... getDeviceId:-1`），即本设备指纹实际由 ANDROID_ID + 真实 MAC + Build 硬件信息等因子生成，无电话权限也能稳定取到，**App 无需额外申请 READ_PHONE_STATE**。
  
  1. 官方支持 4 种授权（V7.5 接入文档 2.1 节原文核实，jar 签名 `javap` 复核一致），**SN 和设备指纹都涉及，区别在激活方式**：
  
     | 方式 | 控制台操作 | 设备端调用（algId = `OcrgveEnginePlate.getAlgorithmId()` = 7） | 要不要手工提指纹 |
     |---|---|---|---|
     | ① 控制台离线授权文件 | 申请序列号 → 单台设备授权选「车牌识别」→ 点「离线激活」**绑定设备指纹** → 下载 `.ini` 授权文件 | 文件放 assets，`AndroidLicenser.getInstance().authFromFile(ctx, licenseKey, licenseFile, true, 7)`，文档示例 key/file = `AISEE_OCRGVE_7_ANDROID` / `AISEE_OCRGVE_7_ANDROID.ini`（key/file 同名时可直接照搬 demo） | **要**，先取指纹再去控制台绑定 |
     | ② 按 App 授权文件 | 申请按 app 授权的文件（绑包名+签名 MD5），licenseKey 随文件提供 | 同上 `authFromFile`，licenseKey/licenseName 填授权方给的值 | 否（绑包名+签名） |
     | ③ 在线单台设备序列号 | 控制台申请**单台序列号（SN）** | 设备联网调 `BDLicenseActivator.initLicenseOnLine(ctx, 序列号, "", 7)`，返回 0 成功；**首次联网激活时 SDK 自动把本机指纹绑定到该 SN** | 否（自动绑定，最省事） |
     | ④ 在线批量序列号 | 控制台申请**批量序列号（SN）** | 同③，同一个 SN 可激活多台设备 | 否 |
  
     指纹获取 API（文档 2.5 节「获取本地鉴权设备指纹信息（离线激活需要）」，原文「设备指纹即 deviceid」）：
     - 直接取：`AndroidLicenser.getDeviceId(context)`（本 App 设置页采用，实测 `153DA2A3…`）
     - 完整本地信息：`AndroidLicenser.getInstance().authGetLocalInfo(ctx, 7)` 返回 `BDLicenseLocalInfo`，字段含 `deviceId / packageName / md5(签名MD5) / licenseKey / fingerVersion`；demo 也可在 logcat 搜 `BDLicenseLocalInfo` 拿 Device-id。
  2. **授权同时绑定「设备指纹 Device-id + 应用包名（applicationId）」**，一机一证；换设备、刷机、改包名均会失效；系统 OTA / 卸载重装不改变指纹。
  3. **当前拿到的 SDK 包内没有任何授权文件**（assets 只有模型；demo 工程也没有 license），官方 demo 必须输入有效序列号/授权文件才能识别。
  4. 因此：**应用包名必须先定下来再去申请授权，中途改包名授权作废**（包名已确认，见第 14 章；申请流程见第 11 章）。
  5. 第一期 App 的设置页会同时展示「设备 SN（备查）」与「百度设备指纹（点按复制，授权必用）」，未购授权也能先取指纹去控制台申请。
  6. **推荐落地路径**：手持机能联网时优先走方式③（设置页输入控制台申请的单台 SN，`initLicenseOnLine` 一键激活，无需手工收集指纹）；设备现场无网络时走方式①（设置页读指纹 → 控制台离线激活下载 `.ini` → 随 App 打包进 assets，`LICENSE_KEY/LICENSE_FILE` 见 [LicenseManager.java](app/src/main/java/com/ectrip/checkincar/license/LicenseManager.java) 常量）。
  7. 已实测坑：未授权状态下 `getAuthStatus(7)` 在该 SDK 内会抛 `ArrayIndexOutOfBoundsException: length=18; index=1000`（其内部用状态码索引 ErrorCode 枚举），必须 try/catch；`authGetAuthInfo()` 未授权时直接 native SIGSEGV 崩溃，**必须先确认 SUCCESS 再调**。
  
  ### 3.5 demo 流程分析（可直接借鉴）
  
  `StartActivity`（检查授权）→ `ActivitionActivity`（三种激活方式 + 展示设备指纹）→ `HomeActivity`（子线程 `initFromAssets`）→ `ScaleActivity`（Camera1 连续取流 640×480 NV21 → 旋转为正向 Bitmap → RGBA → 子线程识别 → 置信度过滤 → 出结果）。
  
  demo 相机部分较老旧（Camera1 + 离屏 SurfaceTexture + ImageView 显示画面），新工程不照搬，改用 CameraX；**授权、初始化、识别的调用时序与线程模型严格按 demo/文档实现**。
  
  ---
  
  ## 4. 总体设计
  
  ### 4.1 业务流程（详细设计见第 5 章）
  
  ```
  ┌─────────┐  车辆核销   ┌──────────────┐  对准/拍照   ┌──────────────┐
  │ 主界面  │ ─────────▶ │ 相机识别页    │ ──────────▶ │ 结果确认卡片  │
  │ Main    │  ①点击     │ VerifyActivity│  ②自动/拍照 │ (可人工改牌)  │
  └─────────┘            └──────────────┘            └──────┬───────┘
       │ 系统设置                      ▲  重拍/继续识别       │ ③确认核销
       ▼                               └─────────────────────┤
  ┌─────────┐                                                  ▼
  │ 设置页   │                                       ┌──────────────────┐
  │ Settings│                                       │ 调用后台核销接口  │
  └─────────┘                                       │ (本期 Mock)       │
                                                    └──────┬───────────┘
                                                           ▼
                                                    ┌──────────────────┐
                                                    │ ④核销结果(成功/失败)│
                                                    │ 成功→2s 自动回取景 │
                                                    │   （连刷下一辆）   │
                                                    └──────────────────┘
  ```
  
  **设计目标：每辆车常规操作只需 2 次点击** —— 主屏点「车辆核销」→ 对准车牌（自动识别）→ 点「确认核销」→ 成功后自动回到取景位继续下一辆，无需返回主屏。
  
  识别策略（已确认：**自动 + 拍照**）：连续自动识别为主（对准即出结果），手动拍照按钮为辅；取流帧节流约 400ms、单线程串行识别，命中且最小字符置信度 ≥ 阈值（默认 0.80，可设）后停止取流进入确认；支持「重拍」恢复。附闪光灯开关；预留音量下键/手持机实体扫描键作为拍照快捷键。
  
  ### 4.2 技术栈
  
  | 项 | 选型 | 理由 |
  |---|---|---|
  | 语言 | **Java 1.8** | 百度 SDK 与 demo 均为 Java，可最大量直接复用经过验证的调用代码 |
  | IDE/构建 | Android Studio + Gradle 8.x + AGP 8.x + **JDK 17** | 本机已具备；compileSdk/targetSdk 34 |
  | minSdk | **23（Android 6.0）** | 对齐百度声明的支持下限，兼容通用安卓手机 |
  | ABI | arm64-v8a + armeabi-v7a | 覆盖手持机与主流手机 |
  | 相机 | **CameraX 1.3.x**（camera-camera2 + lifecycle + view） | 生命周期安全、自动处理预览方向/分辨率；MT95L 为标准 Camera2 FULL 设备 |
  | UI | AndroidX AppCompat + Material + ViewBinding，传统 View/XML | 竖屏固定，720×1440 dp 适配（基准宽 360dp） |
  | 网络 | OkHttp 4 + org.json | 轻量；核销接口只有一个 |
  | 存储 | SharedPreferences（设置）+ 本地 JSON（核销记录，最近 100 条） | 不引入数据库，保持简单 |
  | 方向 | 全应用 `screenOrientation="portrait"` | 需求明确竖屏 |
  
  > 若 CameraX 在该工业设备上出现兼容性问题（概率低），回退方案：移植 demo 的 Camera1 取流代码（已验证可在百度引擎上跑通），识别/业务层不变。
  
  ### 4.3 工程结构（拟新建于当前目录）
  
  ```
  checkInCar/
  ├── 手持核销车辆系统.md            ← 本文档
  ├── settings.gradle / build.gradle / gradle.properties / gradlew
  └── app/
      ├── build.gradle
      └── src/main/
          ├── AndroidManifest.xml
          ├── assets/
          │   └── ocrgve_resource_plate/        ← 从 sdk.zip 整目录拷贝（约30MB）
          │       （百度授权 *.ini 待用户提供后放这里）
          ├── jniLibs/
          │   ├── arm64-v8a/  ← 4 个 so（手持机用）
          │   └── armeabi-v7a/ ← 4 个 so（通用手机兼容）
          ├── libs/  ← libocrgveplate.jar / bd_unifylicense.jar / liantian.jar
          ├── res/   ← layout/drawable/values/mipmap（竖屏 UI）
          └── java/com/ectrip/checkincar/
              ├── App.java                       ← Application，引擎单例初始化
              ├── MainActivity.java              ← 主界面（2 个按钮 + 今日核销数）
              ├── ui/settings/SettingsActivity.java
              ├── ui/verify/VerifyActivity.java  ← 相机 + 识别 + 结果确认 + 核销
              ├── core/prefs/AppPrefs.java       ← 全部设置项的读写
              ├── core/device/DeviceInfo.java    ← IP / MAC / SN 获取（多策略）
              ├── plate/
              │   ├── PlateInfo.java             ← 车牌号/颜色/置信度/位图
              │   ├── PlateRecognizer.java       ← 识别引擎接口（可切换）
              │   ├── MockPlateRecognizer.java   ← 模拟识别（本期默认）
              │   └── BaiduPlateRecognizer.java  ← 百度 SDK 封装（授权+init+识别）
              ├── license/LicenseManager.java    ← 百度授权状态/在线激活/设备指纹
              ├── net/
              │   ├── VerifyApi.java             ← 核销接口（真实 HTTP）
              │   └── MockVerifyApi.java         ← 模拟核销（本期默认）
              ├── model/VerifyRequest.java / VerifyResult.java
              └── history/VerifyHistory.java     ← 本地核销记录（JSON）
  ```
  
  > 包名 `com.ectrip.checkincar`（结合目录名 checkInCar 与现场 WiFi ECTRIP）**已评审确认采用**，App 显示名「车辆核销」；该包名将用于百度授权申请，之后不再变更。
  
  ---
  
  ## 5. 界面与交互详细设计（本章为本次重点细化内容）
  
  ### 5.0 设计原则
  
  1. **竖屏单手操作**：全部页面锁竖屏；核心按钮放在拇指热区（屏幕下半部），高度 ≥56dp。
  2. **名称四字对齐**：主按钮统一 4 个字 —— 「车辆核销」「系统设置」「确认核销」「重拍」。
  3. **步骤最少**：常规每车仅 2 次点击（进核销 → 确认核销），识别与连刷全部自动化。
  4. **紧凑两列**：设置页信息项采用「左标签 : 右值」左右两列、分组卡片排列，减少纵向行数，把屏幕空间留给状态/记录区域。
  5. **状态可见**：每个耗时动作都有明确提示（识别中、核销中），结果用大字 + 颜色 + 振动/音效三重反馈，户外嘈杂环境也能用。
  
  ### 5.1 页面清单与跳转关系
  
  | 页面 | Activity | 进入方式 | 返回行为 |
  |---|---|---|---|
  | 主界面 | MainActivity | 启动页 | — |
  | 系统设置 | SettingsActivity | 主界面「系统设置」 | 返回即回主界面，配置自动保存 |
  | 车辆核销 | VerifyActivity | 主界面「车辆核销」 | 返回主界面；核销成功不关闭本页，自动回取景态 |
  
  页面间不产生堆叠（核销页只有一个实例），应用内不做登录页（员工 ID 设置页手填）。
  
  ### 5.2 主界面 MainActivity（线框，基准 360×720dp）
  
  > **2026-09-25 更新：主界面按「鼎游 ECTRIP 科技风」改版（品牌 Logo + 模式状态 + 大按钮），最新设计以第 15.2 节为准，本节线框保留作历史对照。**
  
  ```
  ┌──────────────────────────────┐
  │ 车辆核销            v1.0.0     │ ← 标题栏 48dp，右侧版本号
  │                              │
  │                              │
  │      ┌────────────────┐      │
  │      │                │      │
  │      │   🚗 车辆核销    │      │ ← 主按钮：高 110dp，主色实心，
  │      │                │      │   28sp 粗体，点击进核销页
  │      └────────────────┘      │
  │                              │
  │      ┌────────────────┐      │
  │      │   ⚙  系统设置   │      │ ← 次按钮：高 96dp，浅色描边
  │      └────────────────┘      │
  │                              │
  │                              │
  │  引擎:模拟  网络:WLAN ✔       │ ← 状态行 14sp
  │  今日已核销 12 台             │
  └──────────────────────────────┘
  ```
  
  - 两按钮纵向居中、宽度占屏 80%；「车辆核销」视觉权重最高。
  - 底部状态行实时显示：识别引擎（模拟/百度）、网络是否在线、**今日成功核销数**（从本地记录统计，进页面 onResume 刷新）。
  - 连续点击「车辆核销」防抖；若选百度引擎但未授权/模型未就绪，按钮仍可点，进核销页时弹提示并引导去设置（不闪退）。
  
  ### 5.3 车辆核销页 VerifyActivity —— 单页 5 个状态（核心）
  
  该页只有一个 Activity，通过覆盖层切换 5 个状态，避免页面跳转打断节奏：
  
  ```
  S1 取景待识别 ──自动帧/拍照──▶ S2 识别中 ──命中且置信度达标──▶ S3 结果确认
       ▲                            │                            │
       │                         未命中/低分                     │ 确认核销
       │                            └──────────────▶ 回 S1      ▼
       │                                                     S4 核销提交中
       │◀──────────── 成功：2s 后自动返回（连刷）──────────────────┤
       │                                                          │
       └────────────────── 失败：停留，手动「重试/重拍」◀── S5 核销结果(成功/失败)
  ```
  
  #### S1 取景待识别
  
  ```
  ┌──────────────────────────────┐
  │ ✕        车辆核销      💡 开 │ ← 顶栏：左=返回主界面，右=闪光灯开关
  │                              │
  │        后摄全屏预览           │
  │    ┌────────────────────┐    │
  │    │ ╲                  ╱ │    │ ← 车牌对齐框（横向矩形，四角 L 形
  │    │                      │    │   高亮线 + 半透明遮罩）
  │    │                      │    │
  │    │ ╱                  ╲ │    │
  │    └────────────────────┘    │
  │                              │
  │   将车牌移入框内，自动识别     │ ← 提示文字随状态变化
  │                              │
  │              ⬤               │ ← 底部居中大快门（高 72dp），
  │          [拍照识别]           │   手动拍照；音量下键/扫描键等效
  └──────────────────────────────┘
  ```
  
  - CameraX 全屏预览，画面按竖屏自动旋转校正；对齐框宽占屏 86%、高约宽的 1/3。
  - 自动识别在后台持续进行（用户无感）；快门是主动兜底。
  - 连续 3 秒无任何检测时，提示文字轮播：「请靠近车牌 / 保持光线充足 / 点击下方按钮拍照」。
  
  #### S2 识别中
  
  - 命中帧后立即停止取流，画面定格；对齐框四角变为加载色，提示「识别中…」（正常 200~600ms，不做全屏遮罩，避免闪烁）。
  - 结果不达标（无车牌或最低字符置信度 < 阈值）：Toast 弱提示一次并自动回 S1 继续取流，不弹错误页。
  
  #### S3 结果确认（底部抽屉式卡片，不挡全图）
  
  ```
  ┌──────────────────────────────┐
  │              （定格的车牌画面） │
  │                              │
  ├──────────────────────────────┤
  │ 车牌号                   蓝牌 │ ← 颜色标签：蓝/黄/绿/白/黑
  │  ┌──────────────────────────┐│
  │  │ 京 A8D6F8              ✎ ││ ← 36sp 超大号；点 ✎ 弹键盘手改
  │  └──────────────────────────┘│
  │ 置信度 0.96   员工 10086       │ ← 次要信息 13sp 一行
  │                              │
  │  ┌──────────┐ ┌────────────┐ │
  │  │  重拍     │ │  确认核销   │ │ ← 左次右主，等高 56dp
  │  └──────────┘ └────────────┘ │
  └──────────────────────────────┘
  ```
  
  - **车牌可人工修正**：点击号码区域弹数字+省份简称键盘（系统键盘即可，输入自动去空格/转大写）；手改后置信度置灰显示「人工输入」。
  - 员工 ID 取自设置页；若为空，点「确认核销」时提示「请先在设置中填写核销员工 ID」并给「去设置」入口。
  - 后台地址为空或非法同理拦截，不发无效请求。
  
  #### S4 核销提交中
  
  - 卡片切换为 Loading：旋转指示 +「核销中，请勿移开…」；按钮全部禁用防重复提交；HTTP 超时 10s。
  
  #### S5 核销结果
  
  ```
  成功（绿底）                         失败（红底）
  ┌──────────────────────┐    ┌──────────────────────┐
  │         ✔            │    │         ✕            │
  │      核销成功         │    │      核销失败         │
  │   京A8D6F8           │    │   京A8D6F8           │
  │ ─────────────────── │    │ 原因：该车牌无预约记录 │ ← 后台 msg 原文
  │ 预约人：张三          │    │                      │
  │ 场  地：P1预约车位    │    │                      │
  │ 时  段：今日09-18点   │    │                      │
  │ 2 秒后自动继续…       │    │ [重拍]  [手改车牌重试] │
  │        [立即继续]     │    │        [返回]        │
  └──────────────────────┘    └──────────────────────┘
  ```
  
  - **成功：提示音 + 长振动 1 次**，展示后台返回的预约信息（无字段则只显车牌），2 秒倒计时后**自动回 S1 连刷**；点「立即继续」不等计时。
  - **失败：短促两声振动 + 低音**，原因直接显示后台 `msg`（如：无预约 / 已核销 / 不在有效期 / 网络异常），不自动跳转，由员工选择重拍、手改车牌重试或返回。
  - 无论成败都写本地记录（时间、车牌、颜色、员工、结果、原因），成功计入今日数。
  
  ### 5.4 系统设置 SettingsActivity（紧凑两列分组卡片）
  
  ```
  ┌──────────────────────────────┐
  │ ‹  系统设置                   │
  │ ── 设备信息（自动获取）─────────│
  │ 本机 IP    192.168.50.70   ⟳  │ ← 左标签120dp 右值，⟳=刷新
  │ MAC 地址  a4:e8:a3:8d:82:56   │   值可点复制；IP/MAC 整行左右排
  │ 设备 SN    MT95LTFFD00631  📋 │   硬件序列号，仅备查/上报
  │ 授权指纹   86F3A2…D9C1     📋 │ ← 百度Device-id，授权必绑(详见3.4)
  │ 指纹版本   v3 / 算法ID 7       │
  │ 授权状态   未授权              │
  │ ── 核销配置 ─────────────────│
  │ 员工 ID   [ 10086          ] │ ← 标签左、输入框右，同一行
  │ 核销地址  [ http://192.16…  ] │ ← 一行，保存时校验 URL
  │ ── 识别配置 ─────────────────│
  │ 识别引擎  (●模拟 ○百度离线)   │ ← 单选 segmented
  │ 置信阈值  [────●────] 0.80    │ ← 滑块 0.50~0.99
  │ ── 模拟配置（模拟引擎时显示）──│
  │ 模拟车牌  [ 留空=随机       ] │
  │ 识别耗时  [ 300 ] ms          │
  │ 核销结果  (●成功 ○失败 ○随机) │
  │ ── 授权（百度引擎时显示）──────│
  │ 序列号    [                ] │
  │           [      激活        ]│
  │                              │
  │ 版本 v1.0.0    今日核销 12 台 │
  └──────────────────────────────┘
  ```
  
  交互规则：
  
  - **所有配置改完即存**（失焦/切换即写 SharedPreferences），不做「保存」按钮，减少一次点击。
  - 「模拟配置」与「授权」分组按当前引擎**联动展开/收起**，不堆无关项。
  - IP、MAC、授权指纹、SN 点击整行复制到剪贴板并 Toast「已复制」（申请授权、报备设备时高频使用）；「授权指纹」行用浅色小字注明「百度授权绑定此 ID，非设备 SN」，防止混淆（见 3.4）。
  - 授权状态：未授权 / 已授权（至 yyyy-MM-dd）/ 授权过期（红色）。
  - 核销地址做格式校验（http(s):// 前缀 + host），不合法时行尾红字提示且不保存。
  - 整页可滚动，但上述内容在 720×1440 一屏内基本可见，不做冗余留白。
  
  ### 5.5 异常分支与处理方式一览
  
  | 场景 | 触发时机 | 界面处理 |
  |---|---|---|
  | 相机权限未授予 | 进核销页 | 内嵌说明卡片 +「去授权」按钮跳系统设置；返回后自动重试 |
  | 设备无后摄/打开失败 | 绑定相机 | 结果位显示「相机不可用」+ 返回按钮（模拟模式下可用纯手动输牌继续演示） |
  | 百度未授权/授权过期 | 引擎=百度且校验失败 | 弹窗显示设备指纹与错误码中文说明 →「去设置激活」；可切回模拟模式 |
  | 模型初始化失败 | 进核销页前 | 提示错误码（4 鉴权/9 模型缺失等），禁止进入 S1，回设置处理 |
  | 一直识别不到车牌 | S1/S2 | 不打断，文字引导；员工可手动拍照 |
  | 识别到但置信度低 | S2 | Toast「识别不确定，请靠近或手改」后回 S1；若手改则直接进 S3 |
  | 员工 ID/核销地址为空 | S3 点确认 | 输入框抖动提示 +「去设置」，不发请求 |
  | 网络不通/超时（10s） | S4 | S5 失败态：原因「网络异常，请检查 WiFi 与核销地址」，可原样重试不重拍 |
  | 后台返回 code≠0 | S4→S5 | 失败态显示 msg（无预约/已核销/不在有效期…），支持改牌重试 |
  | HTTP 非 200/返回非法 JSON | S4 | 失败态「服务异常(HTTP 500)」并记录日志 |
  | 连续重复提交 | S4 | 按钮禁用，二次点击忽略 |
  | 识别中按返回 | S1~S3 | 直接回主界面，释放相机与分析器，引擎不销毁 |
  | 来电话/切后台 | 生命周期 onPause | 停取流停对焦；回前台自动恢复 S1 |
  
  ### 5.6 硬件键与反馈
  
  - **物理键映射（手持机友好）**：音量下键 = 拍照（KeyEvent 监听）；如后续确认 MT95L 实体扫描键可用，将其键值映射为同一动作（设置里加开关，默认开）。
  - **音效**：成功/失败两种短音（assets 内置或系统提示音），跟随系统媒体音量；设置页暂不做静音开关（可后加）。
  - **振动**：成功长振 1 次、失败短振 2 次，使用 VibrationEffect（API 26+），低版本降级。
  - **闪光灯**：每次进页默认关闭，状态不记忆（避免白天误开）。
  
  ### 5.7 屏幕适配
  
  - 基准宽 360dp（720px@320dpi），用 ConstraintLayout + LinearLayout 组合；文字用 sp，触控目标 ≥48dp。
  - 长屏手机（≥800dp 高）拉伸按钮间距与预览区，设置页两列比例固定；小屏（320dp 宽老机）允许设置页滚动，核销页对齐框按比例缩放。
  - 颜色仅取功能语义（主色蓝、成功绿、失败红、标签灰），白天户外对比度优先；不使用横屏布局。
  
  ---
  
  ## 6. 关键模块设计
  
  ### 6.1 设备信息获取（IP / MAC / SN，已在设备上验证可行路径）
  
  - **IP**：`NetworkInterface.getNetworkInterfaces()` 枚举，取 `wlan0`（其次 eth0）上非 loopback、非 link-local 的 IPv4。实测当前 `192.168.50.70`。无需权限。
  - **MAC（Android 6+ 官方 API 被屏蔽，返回 02:00:00:00:00:00）**，按顺序兜底：
    1. 直接读 `/sys/class/net/wlan0/address` —— **本机实测权限 `-r--r--r--` 可读**，值 `a4:e8:a3:8d:82:56`，作为首选；
    2. 枚举 `/sys/class/net/*/address` 找首个非 00/02 开头地址；
    3. `NetworkInterface.getHardwareAddress()`；
    4. `WifiInfo.getMacAddress()`（基本是兜底假值，并明确标注「系统限制」）。
  - **SN**：`Build.getSerial()` 在 API 29+ 需要 READ_PRIVILEGED_PHONE_STATE（普通应用拿不到），改用 `Build.SERIAL`（28 以下）+ 读 `ro.serialno` 反射/备用；本设备 SN 与 ADB 一致（MT95LTFFD00631）。如系统接口受限，设置页允许**手工填写设备编号**并保存。
  - 进入设置页与点击刷新时重新获取。
  
  ### 6.2 相机与识别
  
  - CameraX：`Preview` + `ImageAnalysis(STRATEGY_KEEP_ONLY_LATEST)`，目标 640×480 / 接近 4:3；输出 YUV_420_888 → 转 Bitmap（按 targetRotation 旋转为正向）→ 必要时缩放到宽 ≤1280 → `copyPixelsToBuffer` 得到 RGBA byte[]。
  - 识别在单线程 Executor 串行执行（ReentrantLock 思路同 demo），帧间隔 ≥400ms；识别期间丢弃新帧。
  - 结果过滤：仅取 `name=plate_number`；`min(recgProb) ≥ 阈值`（可配）才接受；记录颜色。
  - 命中后 `analysis.clearAnalyzer()` 停止取流，显示结果卡片；重拍时重新绑定。
  - 手电筒：`CameraControl.enableTorch`；权限：CAMERA 运行时申请。
  - 引擎生命周期：`BaiduPlateRecognizer` 随 Application 持有单例，进入核销页前确保已授权 + `initFromAssets` 完成（只初始化一次）；切换引擎/页面不重复初始化。
  
  ### 6.3 模拟识别（MockPlateRecognizer，本期默认）
  
  - 实现同一个 `PlateRecognizer` 接口，延时 200~500ms 返回 `PlateInfo`：
    - 车牌 = 设置项固定值，或内置车牌库随机（如 京A·8D6F8 蓝牌、粤B·D12345 新能源绿牌、黄底牌等）；
    - 置信度 0.90~0.99；颜色随牌型。
  - 也支持在结果卡片直接手输车牌（真机演示时的保底手段）。
  - **目的：不依赖百度授权即可完整演示「拍（模拟）→ 识 → 改 → 核销 → 记录」闭环。**
  
  ### 6.4 后台核销接口
  
  - 统一封装 `VerifyApi` 接口，`MockVerifyApi` 与真实 `HttpVerifyApi` 可按设置切换，业务层无感。
  - 请求在子线程，OkHttp 超时连接 5s / 读取 10s；支持 http 明文（现场内网地址），通过 `network_security_config` 放行内网明文，不全局放开。
  - 接口契约为**草案（待与预约平台对齐）**，见第 7 章；Mock 按该契约返回。
  - 每次成功/失败均写本地记录（时间、车牌、员工、结果、原因），主界面显示「今日成功核销数」。
  
  ### 6.5 设置存储 AppPrefs
  
  - 单个 SharedPreferences（`car_verify_prefs`）封装全部键：staffId、baseUrl、engineType、scoreThreshold、mockPlate、mockResult、设备编号手填值等；改动即时生效。
  
  ### 6.6 授权管理 LicenseManager
  
  - 封装：查询设备指纹、查询授权状态与到期时间、在线序列号激活、离线文件 authFromFile。
  - 严格遵守官方时序：**授权（子线程）成功 → 再 initFromAssets（子线程）**，二者不并发、不重复初始化；所有错误码映射为中文提示（第 3.3 节）。
  - App 启动时若引擎为「百度」：后台静默校验授权与模型状态，主界面/设置页展示；未授权则点击「车辆核销」时引导去授权页，不会闪退。
  
  ---
  
  ## 7. 后台核销接口契约（草案，待平台方确认）
  
  **请求**
  
  ```
  POST {后台核销地址}/api/checkin/carVerify
  Content-Type: application/json
  ```
  
  ```json
  {
    "plateNo": "京A8D6F8",        // 车牌号（必填）
    "plateColor": "blue",         // blue/yellow/green/white/black
    "staffId": "10086",           // 核销员工ID
    "deviceSn": "MT95LTFFD00631", // 设备SN
    "mac": "a4:e8:a3:8d:82:56",
    "ip": "192.168.50.70",
    "timestamp": 1727230000000    // 毫秒
  }
  ```
  
  **响应**
  
  ```json
  {
    "code": 0,                    // 0=核销成功，其他=失败
    "msg": "核销成功",
    "data": {
      "reservationId": "YY20260925001",
      "visitorName": "张三",
      "lotName": "P1 预约车位",
      "visitTime": "2026-09-25 09:00-18:00",
      "plateNo": "京A8D6F8"
    }
  }
  ```
  
  - 常见失败：无预约、已核销、不在有效期、车牌不匹配等，以 `code/msg` 展示。
  - 真实路径、字段名、鉴权方式（是否加 token/签名/租户号）**拿到平台文档后只改 `HttpVerifyApi` 与 model**，界面不动。
  
  ---
  
  ## 8. 第一期（今天，模拟版）交付内容与验收
  
  **交付**：可在 MT95L 上安装运行的 debug APK + 完整 Android Studio 工程。
  
  1. 新建工程、拷贝百度 jar/so/模型进工程（不启用不调用，仅保证能打包通过）。
  2. 主界面两个按钮 + 今日核销数；全屏竖屏。
  3. 设置页：IP/MAC/SN 自动显示并可刷新；员工 ID、核销地址可保存；引擎/阈值/模拟参数可配；显示百度设备指纹（即使未授权也能取到，供申请授权用）。
  4. 核销页：CameraX 后摄预览、对焦、闪光灯、对齐框、手动拍照；**模拟识别**出车牌；结果卡片可改车牌；**模拟核销**返回成功/失败（可配）；成功/失败结果页 + 振动；本地记录与今日计数。
  5. 相机、网络等运行时权限处理。
  6. `adb install -r` 安装到 MT95LTFFD00631 真机走查全部流程（竖屏、720×1440 适配）。
  
  **验收标准**
  
  - 手持机上能连续演示：进入核销 → 对准/拍照 →（模拟）出号 → 改号 → 确认核销 → 成功/失败 → 继续下一辆。
  - 设置页显示的 IP=`192.168.50.x`、MAC=`a4:e8:a3:8d:82:56`（以实际为准），员工 ID 与地址重启后保留。
  - 切换「模拟核销结果=失败/随机」时错误流程与提示正确。
  
  ## 9. 第二期（授权与真实接口到位后）
  
  1. 你方在百度控制台完成授权（流程见第 11 章），或提供在线序列号。
  2. 引擎切「百度离线识别」：真机初始化模型 → 真实车牌识别调试（光照、距离、新能源/黄牌、置信度阈值、识别耗时实测）。
  3. 按预约平台真实文档实现 `HttpVerifyApi`、联调核销（含无预约/重复核销等异常分支），必要时加 token/签名。
  4. release 签名、混淆（追加百度 keep 规则：`-keep class com.baidu.vis.**{*;}`、`-keep class com.baidu.liantian.**{*;}`、keep native 方法）、出正式包。
  5. 如多台手持机推广：采用**在线批量序列号**，在设置页逐台激活，避免每台单独打包 license 文件。
  
  ---
  
  ## 10. 构建、安装与验证命令
  
  ```bash
  # 工程就绪后（本机 JDK17 + Android SDK 34）
  ./gradlew assembleDebug
  adb -s MT95LTFFD00631 install -r app/build/outputs/apk/debug/app-debug.apk
  adb logcat | grep -iE "Ocrgve|BDLicense|carverify"   # 看授权/初始化/识别日志
  ```
  
  - 真机信息复核：`adb shell wm size` → 720x1440；`getprop ro.product.cpu.abi` → arm64-v8a。
  - 授权排障时以设备指纹 + 授权错误码（第 3.3）为准，不凭猜测下结论。
  
  ---
  
  ## 11. 百度授权办理流程（需要你方操作，开发侧配合）
  
  1. **applicationId 已确认为 `com.ectrip.checkincar`，授权申请即按此包名，之后不再更改**。
  2. 安装第一期 APK 后，在「系统设置」页复制**百度设备指纹（Device-id，授权必绑，注意不是硬件 SN）**——每台手持机不同；第一期 App 无需授权即可显示该值。当前这台 MT95L 用同版本 SDK 实测指纹为 `153DA2A38757D7D7016E76F8EE0AACE367`（可直接拿它去控制台申请，正式 App 装好后再复核一次）。
  3. 登录百度智能云控制台 → 车牌识别离线 SDK 授权管理：
     - **单台离线授权**：新建单台授权，选择模型「车牌识别」、填设备指纹、绑定包名 → 离线激活 → 下载授权文件（`*.ini` + 对应 licenseKey）→ 发给开发放入 `assets/` 重新出包（一台一证，适合设备少）。
     - **在线序列号（推荐多机）**：申请单台/批量序列号 → 在 App 设置页输入激活（需联网一次），激活信息本地持久化，之后离线可用。
  4. 开发侧用 `authFromFile(key, 文件名, true, algId)` 或 `initLicenseOnLine(序列号)` 完成鉴权，成功后初始化模型。
  5. 注意：App 签名、包名需与申请时一致；正式发布前用 release 签名重新核对授权策略。
  
  ---
  
  ## 12. 风险与对策
  
  | 风险 | 影响 | 对策 |
  |---|---|---|
  | 暂无百度授权文件/序列号 | 真机无法真实识别 | 第一期用模拟引擎跑通全部业务；SDK 物料与封装先行；设置页先取设备指纹便于立即申请授权 |
  | 授权绑定包名+设备指纹 | 包名定死、换机失效 | 包名先评审确认；多设备用在线批量序列号；换机要重新授权（官方规则） |
  | Android 11+ MAC 被系统屏蔽 | 设置页显示假 MAC | 首选读 sysfs（本机实测可读真实 MAC），多级兜底并标注来源 |
  | 工业设备 CameraX 兼容性 | 取流异常 | CameraX 先行；异常回退 demo 的 Camera1 方案，识别层不变 |
  | 现场内网 HTTP 明文 | 9.0+ 默认禁止明文 | networkSecurityConfig 仅放行配置的内网地址/端口 |
  | 模型/so 体积大（约 50MB） | APK 偏大 | arm64+v7a 都保留（通用手机兼容）；后续可按渠道拆 ABI 包 |
  | 重复初始化/线程错误 | 模型初始化失败 | 严格单例、子线程、授权后初始化；错误码中文映射 |
  | 后台接口未确定 | 无法真实核销 | 接口层抽象 + Mock；契约草案先行，平台文档到位后仅替换实现 |
  
  ---
  
  ## 13. 配置/权限清单（开发时照此实施）
  
  - `AndroidManifest.xml`：`CAMERA`、`INTERNET`、`ACCESS_NETWORK_STATE`、`READ_EXTERNAL_STORAGE`（仅相册调试，API≤28）；`largeHeap=true`；全部 Activity 竖屏；FileProvider（相册选图）。
  - `build.gradle(app)`：minSdk 23 / target+compile 34；`ndk { abiFilters 'arm64-v8a','armeabi-v7a' }`；`jniLibs.srcDirs=['libs']` 或使用标准 jniLibs 目录；`implementation files('libs/*.jar')`；CameraX / OkHttp 依赖；`compileOptions 1.8`。
  - 资源：`assets/ocrgve_resource_plate/` 整目录；so 与 jar 不重打包损坏（从 zip 解压后二进制原样拷贝）。
  
  ---
  
  ## 14. 评审结论与遗留事项
  
  ### 已确认（2026-09-25 评审）
  
  1. ✅ 包名 applicationId：**com.ectrip.checkincar**，显示名「车辆核销」。
  2. ✅ 第一期**默认模拟识别 + 模拟核销**，百度 SDK 同步完成集成与封装、暂不启用真实识别（当前无授权文件，这是今天跑通真机全流程的方式）。
  3. ✅ 识别交互：**对准自动识别 + 手动拍照兜底 + 结果可人工修正**（详见 5.3 五状态设计）。
  4. ✅ 核销员工 ID：**系统设置页手工填写并本地保存**。
  5. ✅ 本次重点细化方向：**界面与流程**（第 5 章已补充设计原则、页面跳转、三屏线框图、核销页状态机、异常分支、硬件键与反馈、适配规则）。
  
  ### 仍遗留（不阻塞第一期开发，可后续提供）
  
  1. 预约平台核销接口是否已有正式文档？没有则先按第 7 章契约模拟，拿到后仅替换 `HttpVerifyApi` 与 model。
  2. 百度授权由谁在控制台申请、预计何时提供序列号或授权文件（流程见第 11 章）。**本机指纹 `153DA2A38757D7D7016E76F8EE0AACE367` 已实测取得，现在就可以去控制台申请离线授权**；官方 demo APK（车牌识别7.5）已临时安装在手持机上用于取指纹，可保留用于授权后自测，也可卸载。
  3. 是否需要核销记录的**查询/导出页面**？（第一期仅本地落盘 + 主界面今日计数；如需要可补一个记录列表页，支持按日期查看。）
  4. MT95L 实体扫描键是否需要映射为拍照快捷键（第一期先适配音量下键，扫描键拿到真机键值后即可加开关）。
  
  ---
  
  > **方案已按评审意见完成界面与流程细化。如无其他修改意见，请确认，我将新增 com.ectrip.checkincar 工程并在 MT95L 真机上开发、安装、验证第一期（模拟版）。**
  
  ---
  
  ## 15. 第二轮变更（2026-09-25）：品牌图标、科技风主界面、在线/离线识别三路由
  
  > 第一期模拟版真机走查通过后追加。**本章与前述章节冲突处，以本章为准。**
  
  ### 15.1 应用图标更换为 ECTRIP 鼎标（本轮已实施 ✅）
  
  - 源文件：工程根目录 [ectrip.ico](file:///Volumes/USERDATA/anroidprj/checkInCar/ectrip.ico)（Windows ICO，含 16/32/48/256 四档，256 主档透明底红色「鼎形 ECTRIP」标，与现场手持机上「智能移动验证系统」图标同源）。
  - 已用 PIL 从 256px 主档生成全套 Android 启动图标（桌面图标 = 安装后显示图标，Android 不区分二者）：
    - `mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher.png`（48/72/96/144/192px 方形，白底红鼎）
    - 同目录 `ic_launcher_round.png`（圆形裁剪版，供部分启动器）
    - 同目录 `ic_launcher_foreground.png`（108/162/216/324/432px，自适应图标前景，鼎标占画布 60%，保证落在 66dp 安全圈内）
    - [mipmap-anydpi-v26/ic_launcher.xml](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml) / `ic_launcher_round.xml`：白底 + 鼎标前景（API26+ 自动裁剪成圆形/圆角方形）；旧蓝底车牌矢量前景已删除
  - 背景取**白色**（红鼎在深蓝底上偏闷；参考 App 的品牌呈现也是红鼎 + 浅蓝徽标轮廓 + 白底）。
  - 已 `assembleDebug` + 装机（2026-09-25），桌面/任务管理/安装确认界面均显示新图标。
  - 主界面顶部要展示的**竖版品牌区**另用 256px 透明底 PNG（`drawable-nodpi/ic_logo_ectrip.png`），实施 15.2 时拷入，不做进 mipmap（mipmap 仅用于启动图标）。
  
  ### 15.2 主界面科技风改版（参考现场鼎游「智能移动验证系统」界面）（本轮已实施 ✅）
  
  > 实施落地（2026-09-25 真机截图确认）：品牌区 200dp 深蓝渐变 + 八边形描边徽标（`drawable/bg_octagon.xml`，内嵌 `drawable-nodpi/ic_logo_ectrip.png` 38dp 红鼎）+「鼎 游 信 息 / ECTRIP · SMART VERIFY」+ 25sp 宽字距标题 + 模式胶囊；底 2dp `#35C2FF` 高光线；内容区四角 L 形青色角标（`drawable/decor_corners.xml`）；主按钮 96dp 蓝渐变 `bg_btn_tech_primary.xml`、车形图标在左；次按钮 88dp 白底蓝描边齿轮图标；状态行改为三张白底小卡片（引擎/网络/今日核销）；左下角版本号 + 设备编号。核销页顶栏用半透明深蓝渐变（`bg_brand_header_overlay.xml`，压住相机预览），设置页顶栏用实色渐变。
  
  参考照片（Newland MT95 上现有 App）关键元素：顶部红色 ECTRIP 鼎标 +「鼎游信息」、深色大标题、**绿色「当前：在线检票」模式状态**、整宽蓝色大按钮（字距拉开，硬朗、高对比）、底部「版本号 / 设备编号」。在此基础上融入科技感。
  
  **竖屏线框（360×720dp，从上到下）**
  
  ```
  ┌────────────────────────────────────┐
  │  ▓▓▓▓▓ 深蓝→藏青渐变标题区 ▓▓▓▓▓▓▓  │ 高 200dp
  │      ╭──────────────╮              │
  │      │  ◇ 红鼎ECTRIP ◇ │            │ ← 浅蓝八边形徽标(矢量描边)
  │      ╰──────────────╯              │   内嵌鼎标 64dp
  │          鼎 游 信 息                │ ← 12sp 浅蓝白，字距加宽
  │                                    │
  │        车 辆 核 销 系 统            │ ← 24sp 白色粗体，字距 6sp
  │      ┌────────────────────┐        │
  │      │ ● 当前：在线识别    │        │ ← 模式胶囊，在线=荧光绿 #39FF88
  │      └────────────────────┘        │   离线=亮蓝 #4FC3F7 / 模拟=暖橙 #FFB74D
  ├────────────────────────────────────┤
  │  (浅灰底 #F4F6FA，微弱科技网格/角标) │
  │   ┌──────────────────────────────┐ │
  │   │  ▰▰  车 辆 核 销             │ │ ← 主按钮 高 96dp，蓝色渐变
  │   └──────────────────────────────┘ │   #1565C0→#0D47A1，白色车形图标
  │   ┌──────────────────────────────┐ │   圆角 12dp，按压 0.97 缩放
  │   │  ⚙   系 统 设 置             │ │ ← 次按钮 高 88dp，白底蓝描边
  │   └──────────────────────────────┘ │
  │                                    │
  │  引擎:在线   网络:在线  今日核销:1  │ ← 13sp 深灰状态行
  ├────────────────────────────────────┤
  │  版本号 v1.0.0                     │
  │  设备编号 MT95LTFFD00631           │ ← 12sp 浅灰，左对齐（同参考App）
  └────────────────────────────────────┘
  ```
  
  设计要点：
  
  1. **品牌区**：深蓝渐变（`#1565C0→#0D2B5C`）标题区，内含浅蓝八边形（双切角矩形）描边徽标 + 红鼎 +「鼎 游 信 息」；标题文字白色、宽字距，复刻现场 App 的硬朗工业感。
  2. **科技感装饰**（克制、不影响信息）：标题区底部一道 2dp 荧光青 `#35C2FF` 高光线；内容区四角放 L 形青色角标线；背景 `#F4F6FA` 叠极淡网格（可选，避免视觉噪点）。
  3. **模式胶囊**随设置引擎实时变色（onResume 刷新），文字「当前：在线识别 / 离线识别 / 模拟识别」——直接对应现场 App「当前：在线检票」。
  4. 按钮**整宽 88%**、大字距（4 字之间留空，与参考一致）、主按钮带车形图标；保持本期已验证的点击区域（底部手掌握持区）。
  5. 底部双行信息保留参考 App 习惯：版本号 + 设备编号（SN）；其上保留我们自有的「引擎/网络/今日核销」状态行。
  6. 核销页不推翻：顶栏改为同样的深蓝渐变 + 青色高光，车牌框四角 L 线沿用（本来就是科技风），其余 5 状态机不动。
  7. 设置页顶栏同步深蓝渐变；卡片式分组不变。
  
  ### 15.3 识别引擎改三路由：模拟 / 在线 / 离线
  
  设置页「识别引擎」由 2 段改 **3 段**：`模拟识别 | 在线识别 | 离线识别`。业务层（VerifyActivity 状态机、结果卡片、核销接口）**零改动**，只在识别实现层增加一个云端实现：
  
  | 引擎 | 实现类 | 依赖 | 要授权/密钥吗 | 识别位置 |
  |---|---|---|---|---|
  | 模拟识别 | `MockPlateRecognizer`（已有，默认） | 无 | 否 | 本地假数据 |
  | **在线识别（新增）** | `OnlinePlateRecognizer`（新增） | 外网 + 百度 AI 开放平台 | **AK/SK（已提供，预置默认值）** | 百度云 REST |
  | 离线识别 | `BaiduPlateRecognizer`（已有） | 离线 SDK 授权 | 设备指纹授权/序列号（第 11 章） | 端侧 so |
  
  工厂 [PlateRecognizerFactory.java](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/java/com/ectrip/checkincar/plate/PlateRecognizerFactory.java) `create(Context)` 按 AppPrefs 当前引擎返回实例；主界面状态卡片/胶囊文案同步改为三态。旧引擎值迁移：AppPrefs 初始化时把旧 `engine=1`（百度离线）一次性迁到 `2`，标记位 `engineV2Migrated`。
  
  #### 15.3.1 在线识别接口（依据示例 [rest2.0ocrv1license_plate.java](file:///Volumes/USERDATA/anroidprj/checkInCar/rest2.0ocrv1license_plate.java) 与百度 AI 开放平台文档）
  
  1. **获取 access_token**（AK/SK 换 token，有效期 30 天，需缓存）：
  
  ```
  POST https://aip.baidubce.com/oauth/2.0/token
  Content-Type: application/x-www-form-urlencoded
  body: grant_type=client_credentials&client_id={APIKey}&client_secret={SecretKey}
  → JSON 取 access_token、expires_in(秒，通常 2592000)
  ```
  
  2. **车牌识别**：
  
  ```
  POST https://aip.baidubce.com/rest/2.0/ocr/v1/license_plate?access_token=...
  Content-Type: application/x-www-form-urlencoded
  body: image={JPEG 的 Base64，URLEncode}&multi_detect=false&multi_scale=false
  成功：{"words_result":{"color":"blue","number":"粤BD12345","probability":[...]},
         "words_result_num":1,"log_id":...}
  失败：{"error_code":110,"error_msg":"Access token invalid"}
  ```
  
  3. 已提供的凭证（控制台应用「闸机检票系统」，ak_sk 鉴权）：
  
  | 项 | 值 | App 内存储 |
  |---|---|---|
  | client_id（API Key / AK） | `iKKGwJRwHxIe9CAAXgafSpyt` | AppPrefs，作默认值预填，可在设置改 |
  | client_secret（Secret Key / SK） | `FS0byCisfASTaqoaEcRDoye4wiPFuosq` | 同上，输入框默认密文显示（小眼睛切换） |
  
  #### 15.3.2 客户端实现要点（新增 `OnlinePlateRecognizer`）
  
  - **token 管理**（新增 `BaiduCloudToken` 小类）：成功获取后把 token 与到期时间戳存 AppPrefs；剩余有效期 >24h 直接复用，否则重新获取；识别返回 `error_code=110/111`（token 失效）时**自动重取一次并重试一次**，仍失败才报错。
  - **图像**：沿用现有 JPEG 通路（YUV→NV21→JPEG / 拍照 JPEG），宽压到 ≤1280、质量 80，Base64 后通常 100~300KB；OkHttp `FormBody` 自动 URLEncode；连接 5s / **读取 10s**（云端比本地慢）。
  - **节流**：在线请求有 QPS 与计费，自动分析帧间隔由 400ms 放宽到 **≥1000ms**，识别中丢帧；命中即停（同离线）。S2 文案显示「云端识别中…」。
  - **自动帧本地预筛（省次数）**：自动分析帧在上传前先缩到 160 宽灰度，统计平均亮度与梯度能量（`OnlinePlateRecognizer.frameWorthSending`）：亮度 <25 或 >245、边缘能量 <5.5 直接丢弃不上传。真机标定（MT95L）：暗噪空景边缘 4.3~4.6（跳过），合成车牌入框 0.75 倍引导框 6.6、满框 7.9（上传）。**手动拍照是有意触发，不做预筛**（再暗也只产生一次调用，避免"按了没反应"）。
  - **空结果静默**：`error_code=282102/282103`（未检测到车牌/目标识别错误，对空画面百度每次都回这个）与无 `words_result` 一样按"本帧无车牌"静默处理，不弹 Toast；其余错误（17/18/19 额度·QPS·并发、110/111 鉴权、网络）才经 `getLastError()` 在界面节流提示（3s 一次）。
  - **结果映射**：`words_result.number`→车牌；`color`（blue/yellow/green/white/black/yellowgreen）→现有颜色标签（yellowgreen→green 按新能源处理）；取 `probability` 数组最小值为置信度；云返回不带 probability 时 PlateInfo.confidence=-1，结果卡片显示「云识别」。在线引擎不过本地置信阈值。
  - **错误中文映射**：网络不可达 →「无法连接百度云，请检查外网/WiFi」；token 获取失败 →「鉴权失败：…」；`error_code 17/18/19` →「云端识别今日次数已超限 / QPS 超限 / 并发超限」；216200/216201/216202 图片类错误；其余显示 `error_msg（code）`。失败后**不静默降级**，由员工决定切引擎。
  - 在线引擎**不校验百度离线授权、不加载 so 模型**；LicenseManager 与百度 jar 不参与该路径。
  - **核销接口不变**：`VerifyApiFactory` 仍按「仅模拟引擎 → MockVerifyApi，其余 → HttpVerifyApi」工作；在线识别 + 真实后台即生产组合，无后台时确认核销走失败页（「网络异常: …」，不闪退）。
  
  #### 15.3.3 设置页联动（在现有「识别配置」分组上改）
  
  ```
  ── 识别配置 ──────────────────────
  识别引擎   [模拟识别|在线识别|离线识别]   ← 3 段
  置信阈值   [────●────] 0.80              ← 仅「离线识别」显示
  ── 在线配置（引擎=在线时展开）────────
  API Key    [iKKGwJ****afSpyt        👁]  ← 预填默认 AK，可改
  Secret Key [********************    👁]  ← 预填默认 SK，密文
  鉴权状态   未获取 Token / 有效（至 MM-dd HH:mm）  ← 绿色，实测 30 天
             [　测试鉴权并获取 Token　]      ← 立即调 oauth 验证 AK/SK
  ── 模拟配置（引擎=模拟时展开，已有）──
  ── 离线授权（引擎=离线时展开，已有）──
  ```
  
  - AppPrefs 新增键：`engine`(0模拟/1在线/2离线，复用原键改值域并迁移)、`cloudAk`、`cloudSk`、`cloudToken`、`cloudTokenExpireAt`、`engineV2Migrated`；旧两段选择迁移（旧值 1 → 2）。AK/SK 输入框 TextWatcher 即时保存，**改动即 clearCloudToken()** 强制重鉴。
  - 在线引擎立即可用的前提：手持机能访问**外网**（`aip.baidubce.com`）；现场若只有内网，切离线或模拟。
  - 主界面「网络:在线」检测需能区分**内网通但外网不通**：在线模式启动时可选做一次轻量探测（HEAD baidu.com / DNS），不通时胶囊仍可点但进核销页提示。
  
  #### 15.3.4 安全与计费说明（须知）
  
  1. AK/SK 内置在 APK 中可被逆向提取，仅适用于**专用手持机、受控分发**场景；控制台请勿开启无关付费接口，必要时在百度云设置用量告警。更稳妥的后续方案：我方业务后台代发 OCR 请求（App 调自己的核销地址，由后台持密钥），列为二期可选优化。
  2. 在线识别**按次计费**（车牌识别有每日免费额度，超出按次计费，以百度价目表为准），故自动帧 1s 节流 + 暗/糊帧本地预筛（15.3.2），仅在 S1 自动识别；手动拍照为操作员有意触发，不节流、不预筛，每次只产生一次调用。
  3. 在线引擎不需要第 11 章的设备指纹授权，**包名变更不影响在线识别**；离线引擎仍受包名+指纹绑定约束。
  
  ### 15.4 实施任务与验收（2026-09-25 实施）
  
  | # | 任务 | 状态 |
  |---|---|---|
  | A | ECTRIP 图标全套 | ✅ 已装机（15.1） |
  | B | 主界面/顶栏科技风改版：品牌区、渐变、胶囊、角标高光、版本/SN | ✅ 真机截图与参考照一致 |
  | C | `OnlinePlateRecognizer` + token 缓存/重试 + 颜色/错误映射 + 1s 节流 + 帧预筛 | ✅ 新增 [OnlinePlateRecognizer.java](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/java/com/ectrip/checkincar/plate/OnlinePlateRecognizer.java)、[BaiduCloudToken.java](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/java/com/ectrip/checkincar/plate/BaiduCloudToken.java)、PlateRecognizerFactory |
  | D | 设置页 3 段引擎、在线配置分组（AK/SK 密文预填、测试鉴权）、联动、prefs 迁移 | ✅ |
  | E | MT95L 真机走查 | ✅ ②③④ 已验（详见下）；①待对准真实车牌实测 |
  
  已验记录（2026-09-25，设备 MT95LTFFD00631，WiFi HUAWEI-ECTRIP-5G 可出外网）：
  
  1. **鉴权**：设置页「测试鉴权并获取 Token」成功，状态「有效（至10-25 12:57）」；AK/SK 与 oauth/REST 通路在设备上打通。
  2. **OCR 接口与凭证**：用合成蓝牌「京A12345」调 license_plate 成功返回 number=京A12345、color=blue、probability 数组（各字符 0.9998+），解析契约与 App 实现一致。
  3. **在线取景**：核销页提示「请将车牌放入框内（在线识别）」、S2「云端识别中…」；无牌暗画面经帧预筛**零云端调用**（实测 10s 0 次请求）；282103 空识别静默不弹窗。
  4. **三切换联动**：模拟→模拟配置组；在线→在线配置组（AK 预填/SK 密文+小眼睛/鉴权状态/测试按钮）；离线→阈值滑块+授权激活组；主界面胶囊橙/荧光绿/亮蓝三态与引擎卡片同步。
  5. **不回归**：模拟引擎自动识别（粤JS77X4 蓝牌 94%）、结果卡片/重拍/确认流程正常；在线引擎下核销无后台时落失败页，不闪退。
  
  待办（现场补测）：引擎切「在线识别」对准**真实车牌**（蓝/黄/新能源绿牌）验证 1~2 秒回号并走通核销；改错误 SK 后中文失败提示；断网进入不闪退。
  
  验收标准：引擎切「在线识别」、设备连外网时，对准真实车牌 1~2 秒内回号并走通核销（核销仍走 Mock/后台）；AK/SK 错误时有明确中文提示；断网时不闪退；模拟与离线现有功能不回归。
  
  ## 16. 第三轮变更（2026-09-27）：现场演示打磨（已装机 ✅）
  
  > 目标：客户现场真机演示前的界面与流程微调。全部改动已构建装机（MT95LTFFD00631）并走查，当前引擎停留在「在线识别」（prefs engine=1）。
  
  ### 16.1 变更清单
  
  | # | 需求 | 实施 |
  |---|---|---|
  | 1 | 核销失败弹窗也显示车牌 | [VerifyActivity.java](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/java/com/ectrip/checkincar/ui/verify/VerifyActivity.java) 失败分支 `addInfoRow("车牌", currentPlate.number)`，位于失败原因下方 |
  | 2 | 识别结果卡增加「返回」按钮 | 底部由「重拍 / 确认核销」改为「重拍 / 确认核销 / 返回」三按钮；返回 = `finish()` 回主页（[activity_verify.xml](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/res/layout/activity_verify.xml) `btnBackHome`） |
  | 3 | 车牌取景框加大 | 引导框 300×96dp → 340×116dp → **356×120dp**（屏宽 360dp，横向近满屏，竖向按车牌 440:140 比例）。纯视觉，识别仍送整帧 |
  | 4 | 首页引擎状态醒目 | 引擎卡片值 15sp → **17sp 加粗**并按引擎着色：在线=#00A854 绿、离线=#0288D1 蓝、模拟=#EF6C00 橙（与顶部胶囊同色）；onResume 刷新 |
  | 5 | 核销后台固定走模拟、固定成功 | [VerifyApiFactory.java](file:///Volumes/USERDATA/anroidprj/checkInCar/app/src/main/java/com/ectrip/checkincar/net/VerifyApiFactory.java) 不再按识别引擎分流，恒返回 `MockVerifyApi`；Mock 去掉随机失败/失败原因分支，固定 600ms 返回成功。留 TODO：正式后台就绪后恢复 HttpVerifyApi 分流 |
  | 6 | 成功页预约信息补全 | 展示行：预约号 / **预约时间** / **预约人** / **证件号（脱敏 3502**********1234）** / **预约类型（老人/正常）** / **进入日期** / **核销流水（HX+时间戳）**；模型新增 `visitorIdCard / visitorType / verifySerialNo`，`fromJson` 同步解析同名字段 |
  | 7 | 「车位」改为「进入日期」 | 字段契约全局收口：`lotName` → **`enterDate`**（VerifyResult、VerifyRecord 本地历史键、MockVerifyApi、VerifyActivity）。取值规则：`data.enterDate` 优先，空则取 `data.enterTime` 兼容；Mock 演示值=当天 `yyyy-MM-dd`（实测显示 2026-09-27） |
  
  ### 16.2 真机走查记录（2026-09-27）
  
  - 模拟引擎全流程：自动识别 → 三按钮结果卡 → 确认 → 绿色成功页，7 行信息完整（含进入日期当日），2 秒自动连刷正常。
  - 失败弹窗车牌行：Mock 失败路径造数验证过（本轮后失败路径在现场不再触发，因核销恒成功）。
  - 在线引擎取景页文案、引导框尺寸、引擎卡片绿色加粗，截图确认。
  - 百度云 access_token 性质澄清（已向客户说明）：**应用级凭证，不绑设备**，同一 AK/SK 可多台 MT95L 共用，额度/QPS 按 AK 累计；与离线 License 的「指纹+包名一机一授权」不同。Token 约 30 天有效（2026-10-25 前后到期，App 自动刷新）。
  
  ### 16.3 明天（及后续）待办
  
  1. **现场真实车牌实测**：在线识别对准蓝/黄/新能源绿牌，确认 1~2s 回号（合成牌通路已验，真牌尚未现场拍）。
  2. **正式核销接口对接**：后台 JSON 就绪后，① `VerifyApiFactory` 恢复/新增 HttpVerifyApi 分流；② 确认 `data.enterDate` 真实字段名（不一致则在 VerifyResult.fromJson 的兼容处加映射，**只改数据入口，不动界面**）；③ 预约时间/预约人/证件号/预约类型/核销流水字段名一并对齐。
  3. 非阻塞遗留：离线 License 激活（控制台 SN 流程见第 11 章）、MT95L 扫描键映射、核销记录查询页、断网/错误 SK 的现场演示话术。
  
  ### 16.4 现场操作备忘
  
  - 设备当前：引擎=在线识别，核销=模拟恒成功（任何引擎下点确认核销都成功），今日核销计数每天 0 点重置。
  - 常用命令：构建 `./gradlew assembleDebug --no-daemon`；装机 `adb -s MT95LTFFD00631 install -r app/build/outputs/apk/debug/app-debug.apk`；启动 `adb shell am start -n com.ectrip.checkincar/.ui.main.MainActivity`（VerifyActivity/SettingsActivity 未导出，不能直接 am start，需从主页点入）。
  - 坐标（720×1440）：主页「车辆核销」约 (360,705)、「系统设置」约 (360,976)；设置页引擎三段 y≈1237：模拟 x≈157 / 在线 x≈360 / 离线 x≈563。
  
  ## 17. 第四轮：对接真实核销后台 mqttScan（2026-09-28）
  
  > 依据：`车牌订单核销模拟接口说明.md` + 后端源码（只读参考，**严禁修改**）：`/Volumes/USERDATA/ideaProjects/wts_vehicle_reservation`（分支 tdos-dev）。
  
  ### 17.1 后台事实（源码核实）
  
  - 入口 `ParkingController.mockMqttScan`（open-api/.../parking/controller/ParkingController.java）→ `CallbackService.processRecognizedPlate` → `ParkingService.queryVehicleInfo`；通道业务模式=3 时调 `ParkingOrderHandler.parkingVerify` 执行真实订单消费（消费畅游通订单 + 写 OrderCheckRecord 核销流水 + MQTT 开闸）。
  - 请求：`GET {baseUrl}/parking/mock/mqttScan?deviceCode=&licensePlate=&colorValue=`；colorValue 0蓝/1绿/2黄（`LicensePlateColorEnum`）；车牌明文需 URL 编码。
  - 响应外壳 `AjaxData{success:boolean, info:string, data:VehicleInfoVO}`（**不是** code/msg）。
  - VehicleInfoVO：orderId、orderCode、licencePlate（**Base64 明文车牌**）、createTime（首次入场时间）、seq、vehicleType（1本地/2工作/3预约/4非预约/5非本地/10免票）、licenseColor（蓝/绿/黄）、carType、pass（isPass→JSON 键 pass）、secondEntry、entryTimes。
  - 判定规则（ParkingService 427-462 行）：模式 1 只查询；模式 2 查询并放行；**模式 3 + vehicleType=3 + pass=true 才真实核销**。
  - 已核销预约车再扫：status=1 → pass=false、secondEntry=true、entryTimes=N；免票车 vehicleType=10 且 pass=false；非预约 4/5 直接 return（pass=false，不开闸不核销，但仍写一条 VehicleChannelRecord 通道流水）。
  - 3 秒同设备同车牌 Redis 去重：`success=false, info="3秒内重复车牌识别消息已忽略"`。
  - 坑：`parkingVerify` 抛异常被 processBusinessMode catch 仅打印日志，HTTP 仍 success=true —— App 必须按 data 的 pass/vehicleType/secondEntry 组合判定，不能只看 success。
  - 副作用警告：接口名为 mock 实为正式链路，**真实预约车牌测一次即消费一单**。
  
  ### 17.2 实施方案（用户已确认三项决策）
  
  1. **核销方式开关**：设置页「核销配置」组新增分段「模拟核销｜后台核销」（AppPrefs `verifyMode` 0/1，默认 0）；`VerifyApiFactory.create()` 按此分流，默认模拟防误核销。识别引擎三路由不受影响。
  2. **设备编号**：AppPrefs 新增 `deviceCode`，默认 **DEVICE001**，设置页可改（即时保存）；与手持机 SN 无关，须为后台已配置（device.status=1）且绑定模式 3 通道的编号。
  3. **HttpVerifyApi 重写**：
     - GET，query 参数 deviceCode / licensePlate(URLEncoder UTF-8) / colorValue（blue→0、green→1、yellow→2，未知→0）；连 5s 读 8s。
     - 解析 AjaxData：success=false → `VerifyResult.fail(info)`（原样展示后台中文原因）。
     - 解析 data：orderCode→预约号、orderId、Base64 解码 licencePlate、vehicleType→中文类型、licenseColor、createTime（兼容字符串/毫秒）、seq、pass、secondEntry、entryTimes。
     - 成功/失败判定**只看 AjaxData.success**：false → 红色失败页，原样显示 info（设备未配置/已禁用/3秒重复等）；true → 成功页，data 九项字段**全部显示**（null 显示“-”）：订单号 orderCode、车牌号（licencePlate Base64 解码）、首次入场时间 createTime、入场序号 seq、车辆类型（编码+中文）、车牌颜色、是否允许通行 pass（是/否）、是否重复入场 secondEntry（是/否）、当前入场次数 entryTimes。标题：预约车(type=3)=核销成功，其余=处理成功，副标题显示 info 原文。
  4. **成功页分行展示**：真实模式固定九行（见上，全部显示）；模拟模式保持现有 7 行演示信息（Mock 继续填模拟值）。
  5. 红色失败页保留后台 info 原文 + 车牌行。
  
  ### 17.3 联调与测试
  
  - 安全通路测试（不消费订单）：用无预约的假车牌调后台 → 应得 success=true、vehicleType=4、pass=false，验证网络/解析/判定（副作用仅一条通道流水日志）。
  - 真实核销测试前提：后台提供绑定模式 3 通道的有效 deviceCode + 当天未核销预约车牌（一次性）；核销后第二次扫同牌应拦截为重复入场。
  - 回归：核销方式切回模拟时，全流程与第 16 章一致。
  
  **2026-09-28 现场网络勘察结果**：192.168.50.1:8080 当前返回 `404 / Server: Embedded Server/1.0.0`（网关或道闸设备自带服务，非本系统 Spring 后台）；192.168.50.1-254 全段 8080 扫描无其他服务在线，手持机（.70）正常。**结论：后台服务今日未部署/未启动在本网段，真实链路待后台上线后联调**；App 侧代码已就绪，后台不通时红色失败页显示「后台返回 HTTP 404 / 网络异常」，不闪退。另注：open-api 模块 resources 无 application.yml（配置走外部配置中心），端口与 context-path 以部署环境为准，当前按文档直连 8080 根路径。
  
  ### 17.4 待后台确认/遗留
  
  - DEVICE001 是否真实存在且绑定模式 3 通道；不行则由后台管理员提供 deviceCode（设置页可直接改，无需发版）。
  - 后台不返回预约人/证件/预约类型/核销流水，成功页暂不展示；后续后台加字段后仅在数据入口加映射。
  - parkingVerify 失败对调用方不可见（HTTP 仍成功）——如需精确核销结果，需后台后续在 VehicleInfoVO 增加核销结果字段或提供核销流水查询接口。
  
  ## 18. 第六轮：核销确认机制 + 预约查询接口（2026-10-27）
  
  > 背景：前几轮识别车牌后直接提交核销，无信息确认环节。用户要求增加确认弹窗，显示车牌号、驾驶员、预约日期、订单号等信息，确认后才执行核销。
  > 核心问题：原核销接口 `/tdos/consumeOrder_/appedit.do` 只返回 `{success, info}` 两字段，不含任何预约详情，**无法在核销前展示**。
  > 解决方案：后台新增免登录预约查询接口，App 侧改为两步流程（先查后核销）。
  
  ### 18.1 后台新增查询接口（已上线）
  
  **请求地址**：
  ```
  GET /tdos/consumeOrder_/appquery.do
  POST /tdos/consumeOrder_/appquery.do
  ```
  
  **请求参数**：
  
  | 参数 | 必填 | 类型 | 说明 |
  |------|------|------|------|
  | licensePlate | 是 | String | Base64 编码后的车牌号（UTF-8），GET 时需再 URL 编码 |
  | callback | 否 | String | JSONP 回调函数名 |
  
  **Base64 编码规则**：与核销接口 `appedit.do` 完全一致——`Base64.encodeToString(plate.getBytes("UTF-8"), Base64.NO_WRAP)`，再用 `URLEncoder.encode(encoded, "UTF-8")` 处理 `+` `/` `=` 特殊字符。
  
  **成功响应（查到有效预约）**：
  ```json
  {
    "success": true,
    "info": "查询成功",
    "data": {
      "licensePlate": "粤A12345",
      "orderId": 10001,
      "orderCode": "202610270001",
      "driverName": "张三",
      "driverPhone": "13800138000",
      "useStartDate": "2026-10-27",
      "parkingAddress": "停车场A区",
      "status": 0,
      "enterTime": null
    }
  }
  ```
  
  **成功响应（无有效预约）**：
  ```json
  {
    "success": false,
    "info": "未查询到当天有效车牌预约信息",
    "data": {
      "licensePlate": "粤A12345"
    }
  }
  ```
  
  **错误响应**：
  ```json
  {"success": false, "info": "车牌号Base64编码格式错误"}
  ```
  
  **返回字段说明**：
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | licensePlate | String | 解码后的车牌号 |
  | orderId | Integer | 订单 ID |
  | orderCode | String | 订单编号 |
  | driverName | String | 驾驶员姓名 |
  | driverPhone | String | 驾驶员手机号 |
  | useStartDate | String | 预约使用日期 |
  | parkingAddress | String | 停车地点 |
  | status | Integer | 0=待入场，1=已入场核销 |
  | enterTime | String/null | 入场核销时间，未核销时为 null |
  
  **接口特点**：
  - 免登录（与 `appedit.do` 同属 `/consumeOrder_/` 路径，Shiro 白名单已配置）
  - 只查不消费订单，不会核销
  - Spring MVC `.do` 后缀拦截规则生效（路径必须带 `.do`）
  - 生产地址前缀：`https://wtspw.wtsykfwzx.com:8145/tdos`
  - 开发测试地址前缀：`https://wtstest.jingqu.cn:9143/tdos`
  
  ### 18.2 App 侧新增文件
  
  | 文件 | 说明 |
  |------|------|
  | `model/QueryResult.java` | 查询结果模型：`ok`(网络层) + `success`(业务层) + `info` + `data` 各字段 |
  | `net/QueryApi.java` | 查询接口定义：`query(String plateNo)` 返回 `QueryResult` |
  | `net/HttpQueryApi.java` | 真实后台实现：GET `{baseUrl}/tdos/consumeOrder_/appquery.do`，5s 超时 |
  | `net/MockQueryApi.java` | 模拟实现：固定 300ms 耗时，80% 概率返回模拟预约详情 |
  | `res/layout/dialog_verify_confirm.xml` | 确认弹窗自定义布局（车牌号/状态/驾驶员/手机号/订单号/预约日期/停车地点 + 取消/确认核销按钮） |
  | `res/drawable/bg_btn_outline.xml` | 取消按钮背景（描边样式） |
  
  ### 18.3 已有文件改动
  
  | 文件 | 改动 |
  |------|------|
  | `net/VerifyApiFactory.java` | 新增 `createQuery()` 方法，按 verifyMode 分流真实/模拟查询 |
  | `ui/verify/VerifyActivity.java` | ① `onRecognized()` 改为先调 `queryAndShowConfirm()` 再弹确认窗；② 取消自动核销（AUTO_VERIFY_ON 选项保留但不再自动提交）；③ 新增 `showConfirmDialog()`（有预约）和 `showNoReservationDialog()`（无预约降级）；④ 新增 `confirmDialog` 和 `queryPending` 状态变量；⑤ `backToScanning()` 和 `onDestroy()` 中清理弹窗状态 |
  | `core/prefs/AppPrefs.java` | ① 核销方式缺省值 `VERIFY_MOCK` → `VERIFY_SERVER`（新安装默认后台核销）；② 识别引擎缺省值 `ENGINE_MOCK` → `ENGINE_ONLINE`（新安装默认在线识别）；③ `migrateEngineV2()` 中旧默认值同步更新 |
  
  ### 18.4 核销流程（改造后）
  
  ```
  拍照/识别车牌
      │
      ▼
  onRecognized(PlateInfo)
      │
      ├─ 取消原 AUTO_VERIFY_ON 自动提交逻辑
      │
      ▼
  workExecutor.execute: QueryApi.query(车牌)
      │
      ┌──────────────────────────────────┐
      │                                  │
   查询成功 + success=true           查询失败 或 success=false
   (有有效预约)                    (无预约 / 网络异常)
      │                                  │
      ▼                                  ▼
   弹确认弹窗                      Toast + 双按钮对话框
   ┌─────────────────────┐         ┌─────────────────┐
   │ 🚗 粤A12345        │         │ 未查到预约信息   │
   │ 📌 待入场/已入场    │         │ 是否继续核销？   │
   │ 👤 张三            │         │ [继续核销][取消] │
   │ 📱 138****8000     │         └─────────────────┘
   │ 📋 202610270001    │                  │
   │ 📅 2026-10-27      │           ┌──────┴──────┐
   │ 🅿️ A区停车场       │           │             │
   ├─────────────────────┤     submitVerify   backToScanning
   │ [取消]  [确认核销]  │
   └─────────────────────┘
         │              │
     backToScanning  submitVerify(currentPlate)
                            │
                            ▼
                      调 HttpVerifyApi.submit()
                      POST /tdos/consumeOrder_/appedit.do
                            │
                            ▼
                      展示核销结果页
  ```
  
  ### 18.5 边界处理
  
  | 场景 | 处理 |
  |------|------|
  | 查询成功 + status=0（待入场） | 正常弹窗，确认核销走原流程 |
  | 查询成功 + status=1（已入场） | 弹窗状态标签红色「已入场」，点「确认核销」后二次确认 |
  | 查询成功 + 无预约（success=false） | 提示"未查到预约信息"，双按钮：继续核销 / 取消 |
  | 查询超时 / 网络异常 | 降级为"未查到预约信息"处理，不阻塞核销 |
  | 模拟核销模式 | MockQueryApi 返回模拟预约详情，流程与真实模式完全相同 |
  | 手动输入车牌 | 同样走查询+确认弹窗流程，与识别的车牌无区别 |
  | 查询中返回扫描态 | `queryPending` 标志位防止重复提交，用户返回后忽略查询结果 |
  | 确认弹窗中按返回键 | `setCancelable(true)`，取消弹窗回到扫描态 |
  
  ### 18.6 接口路径汇总
  
  | 功能 | 方法 | 路径 | 说明 |
  |------|------|------|------|
  | 预约查询 | GET/POST | `/tdos/consumeOrder_/appquery.do` | 免登录，只查不核销，Base64+URL 编码车牌 |
  | 核销提交 | POST | `/tdos/consumeOrder_/appedit.do` | 免登录，真实消费订单，Base64 编码车牌 |
  | 生产地址前缀 | — | `https://wtspw.wtsykfwzx.com:8145/tdos` | .do 后缀由路径自行拼接 |
  | 开发测试地址前缀 | — | `https://wtstest.jingqu.cn:9143/tdos` | 同上 |
  
  ### 18.7 关键代码参考
  
  ```java
  // HttpQueryApi.java — 查询接口实现
  private static final String PATH = "/tdos/consumeOrder_/appquery.do";
  
  public QueryResult query(String plateNo) throws Exception {
      String base = AppPrefs.getBaseUrl();  // 自动去除末尾 /
      String encodedPlate = Base64.encodeToString(
              plateNo.getBytes("UTF-8"), Base64.NO_WRAP);
      String url = base + PATH + "?licensePlate="
              + URLEncoder.encode(encodedPlate, "UTF-8");
      // GET 请求，5s 超时
      // 解析 JSON → QueryResult.fromServerJson(body)
  }
  ```
  
  ```java
  // VerifyActivity.java — 识别成功后先查询再弹窗
  private void onRecognized(PlateInfo info) {
      currentPlate = info;
      queryAndShowConfirm(info);  // 替代原 autoVerify 逻辑
  }
  
  private void queryAndShowConfirm(PlateInfo plate) {
      workExecutor.execute(() -> {
          QueryResult result = VerifyApiFactory.createQuery().query(plate.number);
          runOnUiThread(() -> {
              if (result.ok && result.success) {
                  showConfirmDialog(result);       // 有预约 → 弹确认窗
              } else {
                  showNoReservationDialog(result.info);  // 无预约 → 降级提示
              }
          });
      });
  }
  ```
  
  ### 18.8 2026-10-27 现场测试结果
  
  - 缺省值调整：新安装 App 默认为「在线识别 + 后台核销 + 生产正式地址」
  - 查询接口 `.do` 后缀修正（初版漏写导致 404）
  - Base64 编码 `NO_WRAP` + URL 编码处理 `+` `/` `=` 特殊字符
  - 完整流程：拍照识别 → 查询 → 弹确认窗 → 确认核销 → 展示结果，测试通过