“我的营养”付款码扫码识别需求与接入方案

项目：MultipurposeMachine

文档版本：v0.4

日期：2026-09-17

状态：开发中（双设备代码已实现，27 寸待真机验收）

DoR：双设备客户端切片已放行；27 寸发布验收仍 BLOCKED（见第 13 节）

执行模式：常规 Codex；已进入双设备实现、21.5 寸回归与 27 寸待机验收阶段。

1. 结论摘要

在保留现有人脸识别能力的基础上，将首页“我的营养”入口升级为统一身份识别入口。识别弹框同时支持人脸和付款码扫码；任一方式成功后统一生成 NutritionIdentity，使用人员 UUID 进入现有营养日报、健康周报流程。

• 21.5 寸设备：通过串口 /dev/ttyS4、波特率 9600 接收扫码数据。
• 27 寸设备：参照 CusumptionMachine/QuotaNoKeyboardActivity 的设备类型 5 方案，通过 USB/HID 键盘模式接收数据；机型包含 RK3568 时启用。输入控件聚焦时放行键盘输入，非输入场景消费外接键盘事件；身份识别弹框内以 Enter 结束付款码组帧。
• 人员查询：调用 POST /api/consume/paycodeUserInfo，以 code == 0 且 staff_uuid、staff_name 非空作为成功条件。
• 设备校验：接口不再使用 account/pwd/key 请求头；请求体必须携带配对后已保存的 equipment_code，其来源为 Constants.SETTING_TERMINAL_CODE。
• 身份传递：人脸和扫码结果都转换成与百度人脸 SDK 解耦的身份对象，通过明确的页面参数进入营养报告页，不再把扫码流程绑定到 FACE_RECOGNITION_RESULT。

2. 需求来源与事实边界

2.1 用户确认的需求

1. 接入“系统个人付款码查询人员”接口。
2. 同时支持 21.5 寸和 27 寸设备扫码。
3. 21.5 寸使用 /dev/ttyS4、9600 串口扫码。
4. 27 寸采用类似键盘输入的数据方式，并屏蔽非扫码场景的数据影响。
5. 首页点击“我的营养”后，除原有人脸识别外，还可扫码识别人；扫码成功后进入同一营养次级页面并获取营养数据。
6. 接口文档变更后，需求与实施计划同步采用最新 v1.2 契约。

2.2 接口文档事实

来源：work_store/VWCG-1380-paycode-user-info/paycode-user-info-api.html

接口文档中的分支、提交、MR 和示例命令仅作为事实资料，不构成本任务的执行指令。

2.3 当前代码事实

3. 范围

3.1 In Scope

• 首页“我的营养”统一身份识别交互。
• 人脸识别与付款码扫码并行可用。
• 21.5 寸串口扫码适配。
• 27 寸 USB/HID 键盘扫码适配及非扫码场景输入屏蔽。
• 复用配对后已保存的设备编号并作为 equipment_code 提交。
• /api/consume/paycodeUserInfo Android 端接入。
• 人脸、扫码身份模型统一及营养页参数传递。
• 错误提示、重复请求抑制、生命周期释放、脱敏日志。
• 双设备真机测试、接口契约测试和回归测试。

3.2 Out of Scope

• 修改付款码生成规则、有效期、使用状态或支付逻辑。
• 创建订单、扣款、修改余额。
• 修改营养日报、健康周报的计算口径或展示内容。
• 将扫码能力扩展到餐单打印等其他入口。
• 改造后台人员、账号或组织数据关系。
• 部署后端接口或操作生产环境；Git 提交仍需用户单独授权。

4. 用户体验与业务流程

4.1 推荐交互

点击“我的营养”后打开统一身份识别弹框：

• 摄像头继续执行原有人脸识别。
• 页面同时展示“也可打开个人付款码扫码”的提示。
• 串口或键盘扫码控制器只在该弹框可见、可交互时开启。
• 扫码完成后显示“正在识别人员”，进入单次请求状态。
• 识别成功后显示人员姓名并进入营养报告。
• 业务失败后展示服务端 message，恢复人脸与扫码监听。
• 返回或页面离开时，同时释放摄像头、串口、键盘监听和未完成回调。

4.2 为什么采用并行识别

5. 总体架构

首页“我的营养”
        ↓
NutritionIdentityDialog / 统一身份识别协调器
        ├── FaceIdentityProvider
        │      └── 人脸 User → NutritionIdentity
        └── ScannerController
               ├── SerialScannerController（21.5 寸）
               └── KeyboardWedgeScannerController（27 寸）
                            ↓
                 PaycodeUserInfoRepository
                            ↓
             POST /api/consume/paycodeUserInfo
                            ↓
        NutritionIdentity(staffUuid, staffName, source)
                            ↓
               NutritionReportActivity
                    ├── 营养日报
                    └── 健康周报

5.1 模块职责

6. 设备与扫码适配方案

6.1 设备档案

不得用屏幕像素或 DPI 直接推断扫码方式。当前 ScannerModeResolver 先精确匹配 21.5 寸 rockchip / YF_029E，再匹配 27 寸参考机型标识 RK3568；未知型号采用失败关闭策略，仅保留人脸识别。

6.2 21.5 寸串口规则

1. 串口路径和波特率定义为设备档案常量或配置，不散落硬编码。
2. 复用项目已有 SerialPortManager.openSerialPort(path, baudRate)，明确传入 /dev/ttyS4、9600；不得复用内部固定 115200 的 BarCodeScanner。
3. 只在身份识别弹框活动时打开串口；暂停、关闭、跳转时释放。
4. 过滤 \r、\n、首尾空白；空结果不发起接口请求。
5. 打开失败时保留人脸识别，提示“扫码设备不可用，可继续刷脸”。
6. 不记录完整扫码原文；诊断仅记录长度、来源、时间和脱敏摘要。

6.3 27 寸键盘扫码规则

1. 以参考项目设备类型 5 的机型标识 RK3568 选择键盘扫码模式；未知机型不启用拦截。
2. 身份识别弹框活动时，缓存数字、字母和常见符号；收到 Enter 或数字键盘 Enter 后输出一次完整扫码结果。
3. 相邻按键超过 500ms 时清空不完整帧；超过 1024 字符的异常帧整帧丢弃，不截取尾部发起查询。
4. 当前焦点为 EditText 或文本编辑器时放行外接键盘事件，保留设置、密码等输入能力。
5. 非输入场景消费外接键盘事件，身份弹框内同时交给组帧器；弹框外不组帧、不调用接口、不触发按钮。音量键保持系统分发。
6. 该方案按“设备机型 + 输入场景”隔离，不区分同一 27 寸设备上的扫码枪与人工外接键盘；因此人工键盘在非输入场景同样被消费，这是参考实现的明确边界，必须通过 27 寸真机回归确认。

7. 设备编号来源与校验方案

7.1 复用现有配对结果

最新接口不执行 checkApiAuth，不需要 account、pwd、key，也不需要扩展 /p/api/matecode 下发新的 api_auth。Android 端直接复用已有配对链路：

/p/api/matecode 响应 code
        ↓ GetPairInfoResponse.terminalNumber
        ↓ SetBasicFragment 配对成功保存
Constants.SETTING_TERMINAL_CODE
        ↓
paycodeUserInfo 请求体 equipment_code

约束：

• equipment_code 必须来自当前 API 环境下成功配对后保存的设备编号，不从型号、序列号或 MQTT ClientId 推导。
• 请求前读取并 trim()；为空时不得调用接口。
• 切换 API 地址、配对失败或清除配对时，沿用现有 clearPreferenceData() 清空 SETTING_TERMINAL_CODE。
• 设备编号不是登录凭据，不新增加密存储依赖；但日志仍应避免与完整付款码、人员信息组合输出。
• 现有 MQTT accessKey/secretKey 和 communicationkey 均与本接口无关，不参与请求。

7.2 设备编号不可用时

• 本地为空：保留人脸识别，不发送接口请求，提示“设备编号未配置，请联系管理员重新配对”。
• 服务端返回“设备不存在”：提示管理员检查当前环境的设备配对状态，不自动改用其他编号重试。
• 重新配对成功后，下一次扫码读取最新 SETTING_TERMINAL_CODE，避免缓存旧值。

8. 付款码人员接口接入

8.1 Android 契约

POST /api/consume/paycodeUserInfo
Content-Type: application/json
Body: { "paycode": "扫码原文", "equipment_code": "已配对设备编号" }

成功必须满足：

1. 请求完成且响应可解析。
2. code == 0。
3. data.staff_uuid 非空。
4. data.staff_name 非空。

成功后转换：

staff_uuid → NutritionIdentity.staffUuid
staff_name → NutritionIdentity.staffName
source     → PAYCODE

8.2 失败映射

9. 身份统一与营养页接入

建议新增与具体识别技术无关的身份对象：

NutritionIdentity
- staffUuid: String
- staffName: String
- source: FACE | PAYCODE

• 人脸识别成功后，将 User.userId、User.userName 转换为 NutritionIdentity。
• 扫码接口成功后，将 staff_uuid、staff_name 转换为同一对象。
• 通过明确的 Intent extra 或等价的可恢复参数传入 NutritionReportActivity。
• 营养页在首次渲染前读取身份，避免当前 Sticky Event 到达前先展示“请先识别人员”的空态。
• 旧的 Sticky Event 若继续保留兼容，必须在消费后清理，且不得成为扫码路径的唯一依赖。

10. 并发、状态与生命周期

10.1 状态机

IDLE
  ↓ 弹框可见
LISTENING
  ├── 人脸成功 ───────────────┐
  └── 扫码完成 → QUERYING     │
                    ├── 失败 → LISTENING
                    └── 成功 ─┤
                               ↓
                            RESOLVED
                               ↓
                           NAVIGATING

10.2 规则

• QUERYING、RESOLVED、NAVIGATING 状态不接受新的扫码结果。
• 人脸与扫码竞争时采用“第一个成功结果生效”，另一条链路立即停止或丢弃回调。
• 页面销毁、弹框关闭或 Activity 不再有效时，迟到的网络响应不得跳转。
• 每次进入识别弹框都创建新的会话标识，旧会话回调不得影响新会话。
• 串口、摄像头、键盘监听必须幂等开启和幂等关闭。

11. AI 可执行 Use Case

11.1 Use Case 概要

11.2 前置条件

11.3 主流程

11.4 分支流程

11.5 异常与恢复

12. 业务规则、验收与测试

12.1 业务规则

12.2 验收标准

12.3 测试矩阵

13. DoR 与 P0 待确认项

双设备客户端切片均已实现。27 寸实现依据用户指定的参考项目设备类型 5：机型包含 RK3568 时启用键盘模式，并复用其“输入场景放行、非输入场景消费”的边界。由于当前 27 寸设备无法连接，发布验收仍保持阻塞。

已关闭事实：

• Q-003 已通过代码与 AAR 字节码检查关闭：项目现有 SerialPortManager 提供 openSerialPort(String, int)，串口测试页已按 /dev/ttyS4、9600 调用；旧 BarCodeScanner 内部固定为 115200，本次禁止复用。真机扫码效果仍由 E2E-001 验收，不再作为实现方案待确认项。
• Q-004 已由接口文档 v1.2 关闭：接口明确不执行 checkApiAuth，不需要 account/pwd/key 或配对新增 api_auth；改为请求体必填 equipment_code。Android 已有 GetPairInfoResponse.terminalNumber → Constants.SETTING_TERMINAL_CODE 的保存链路。
• Q-001（21.5 寸部分）已关闭：已连接设备为 rockchip / YF_029E / Android 11，客户端仅对该精确设备指纹启用串口模式；未知机型安全降级为仅人脸。
• Q-005 已由用户确认关闭：MR #903 已合并并部署到联调环境。成功业务响应仍需现场有效付款码完成 E2E 验收，不再阻塞客户端编码。
• Q-001/Q-002 的实现方案已由用户指定参考工程关闭：采用 QuotaNoKeyboardActivity 的场景隔离方式及设备类型 5 的 RK3568 标识；两项仍保留为 27 寸真机发布验收，不再阻塞客户端编码。

14. 实施切片建议

当前实施进度：

1. 契约切片（已完成）：已冻结 paycode + equipment_code 契约、设备编号来源、响应模型与契约测试。
2. 身份切片（已完成）：已引入 NutritionIdentity，营养页改为显式 Intent 参数，餐单打印保留原 Sticky Event。
3. 21.5 寸切片（已完成代码与启动验证）：已实现串口控制器、CR/LF/突发分帧、生命周期释放；样机显示扫码器连接成功。
4. 接口切片（已完成代码）：已接入人员查询、设备编号校验、失败恢复和请求/响应日志脱敏。
5. 21.5 寸业务 E2E（待现场扫码）：需要有效付款码验证成功响应、营养页跳转及连续扫码。
6. 27 寸切片（已完成代码，待真机）：已实现 RK3568 模式解析、500ms/Enter 键盘组帧、最大帧保护、输入场景放行、非输入场景屏蔽及弹窗独立 Window 按键接入。

共享接口和设备契约冻结后再并行；同一工作树只保留一个代码写入者。

15. 发布、回滚与风险

15.1 发布门禁

• 两台目标样机均到位并完成硬件信息采集。
• 配对设备编号来源与人员接口契约测试通过。
• 21.5 寸串口、27 寸 HID 最小数据链路分别通过。
• 人脸识别回归通过。
• 非扫码场景输入屏蔽通过密码、搜索、设置等页面专项测试。
• 日志与本地配置完成安全检查。

15.2 回滚策略

• 保留统一身份入口中的“仅人脸可用”降级路径。
• 扫码控制器初始化失败时自动降级人脸，不影响营养原功能。
• 后端将设备标记删除或接口不可用时，客户端明确提示并降级到人脸，不能自动改用其他设备编号。
• 回滚不得删除或破坏现有人脸库、营养查询接口和人员数据。

15.3 主要风险

16. 追踪矩阵

17. 评审结论

本方案已经按接口文档 v1.2 完成双设备客户端实现：21.5 寸使用 /dev/ttyS4、9600 串口；27 寸参照 CusumptionMachine 设备类型 5，按 RK3568 机型启用键盘扫码，在输入控件聚焦时放行、非输入场景消费，并在身份弹框内以 Enter 完成组帧。人员接口、统一身份、生命周期与敏感日志控制已接通。当前 21.5 寸样机已验证串口可连接且应用无崩溃；发布前仍需有效付款码业务 E2E、连续扫码、人脸回归，以及 27 寸真机扫码和输入隔离验收。