VWCG-1327 菜单消费分类模式上线通知

一 通知正文

CusumptionMachine 消费机客户端本次计划上线“菜单消费分类模式”功能。基础设置新增“菜单消费模式”，管理员可选择“固定分类”或“自定义分类”，未配置、升级后缺少配置或配置值异常时均默认使用固定分类，不改变现有设备的默认菜单行为。

自定义分类模式继续复用现有 POST /p/api/getMeal 接口，通过 group_mode=custom_category_v1 获取服务端配置的分类及菜品。分类按接口返回顺序动态展示，支持横向滚动；分类名称超过 6 个 Unicode 字符时显示前 6 个字符并追加 ...，完整分类名称和分类 ID 仍用于数据匹配，不影响菜品筛选。

本次同时补齐菜单分类与“营养展示”配置的兼容：两项设置独立生效，从基础设置返回菜单页后立即应用；关闭营养展示时会清除已选但不可见的营养筛选，并恢复当前分类的完整菜品列表。基础设置中的“人脸识别阈值”改为只显示数字，不再附加“分”单位。

当前代码、73 项单元测试和 Debug APK 构建已完成，最终 Debug APK 已安装到 rk3568_r 设备并完成启动冒烟。固定分类、自定义分类与营养开关的四种组合已验证。上线时间、正式包版本、签名及发布渠道仍待发布负责人确认，因此本通知状态为“待上线”，不代表生产环境已经发布。

二 上线信息

三 本次改动

3.1 菜单消费模式

• 基础设置新增“菜单消费模式”，支持“固定分类”和“自定义分类”。
• 设置选择后立即保存，重新进入页面时恢复最后一次有效选择。
• 新安装、旧版本升级后缺少配置及非法配置均使用 fixed_category。
• 从基础设置返回菜单页时，如果分类模式发生变化，只按新模式重新请求一次菜单。

3.2 固定分类

• 保持原有“全部、主食、素菜、荤菜、蛋奶坚果、水果、汤饮”七个分类。
• 请求继续使用原有接口和响应结构，不提交 group_mode。
• 原有菜品展示、购物车、排序和支付流程保持不变。

3.3 自定义分类

• 复用 POST /p/api/getMeal，增加请求字段 group_mode=custom_category_v1。
• 固定分类和自定义分类使用独立 Retrofit 方法、独立响应 DTO，再分别映射为统一 MenuCatalog 页面模型。
• 只展示接口中 status=1 且名称有效的分类，并保持服务端返回顺序。
• code=all 展示本次响应中的全部菜品；普通分类和 code=other 按 custom_category_id 匹配。
• 分类数量较多时支持横向滚动。
• 分类名称最多显示 6 个 Unicode 字符，超过时显示前 6 个字符并追加 ...。
• 名称省略只影响标签显示，不改写接口数据、统一模型、分类匹配或日志中的完整名称。

3.4 营养展示兼容

• 菜单分类模式与营养展示开关独立组合生效。
• 从设置页返回菜单页时重新读取营养配置，无需退出页面或重启应用。
• 关闭营养展示时隐藏营养筛选、排序和总热量区域，并清除原有隐藏筛选。
• 只修改营养开关时不重新请求菜单；分类模式与营养开关同时修改时只请求一次新模式菜单。
• 自定义分类继续复用菜品的热量、碳水、蛋白质、脂肪和膳食纤维字段。
• 设置变化、分类切换、刷新失败和协议降级均不清空购物车。

3.5 人脸识别阈值显示

• 基础设置中的人脸识别阈值由“80分”调整为“80”，只显示数值。
• 本次仅修改展示格式，不改变阈值保存值、默认值、50～100 范围、输入校验或 SDK 阈值换算。

四 接口与兼容说明

自定义分类响应必须返回 schema_version=custom_category_v1。当协议版本缺失或不匹配时，客户端仅对本次页面请求临时降级为固定分类，不修改管理员已经保存的自定义分类设置。

分类为空但菜品非空时，客户端临时生成“全部”分类；菜品无法匹配普通分类时仍保留在“全部”中并记录日志。网络失败、业务异常和临时降级不会主动清空已有购物车。

五 验证结果

5.1 自动化验证

执行：

JAVA_HOME=/Users/liang/Library/Java/JavaVirtualMachines/corretto-1.8.0_482/Contents/Home bash ./gradlew :app:testDebugUnitTest :app:assembleDebug --rerun-tasks

• Debug 单元测试共 73 项，失败 0、错误 0、跳过 0。
• 分类名称格式化新增 5 项测试，覆盖少于 6 个字符、刚好 6 个字符、超过 6 个字符、UTF-16 代理对和空名称。
• Debug APK 构建成功。
• git diff --check 通过。
• 新增和修改文本为 UTF-8 无 BOM，中文使用简体中文。

5.2 当前设备验证

验证设备：rk3568_r。

六 上线前检查

• 确认正式上线版本号和 versionCode，避免沿用已发布版本号导致覆盖安装或版本识别异常。
• 使用正式签名构建 Release APK，并核对应用 ID com.cpt.cusumption。
• 确认目标环境的 /p/api/getMeal 已支持 group_mode=custom_category_v1。
• 确认自定义响应中的 schema_version、categories、dishes 和菜品营养字段符合约定。
• 按早餐、午餐、晚餐等目标餐段核对菜谱范围及自定义分类关联。
• 准备至少一个超过 6 个字符的自定义分类，补充真机省略显示截图。
• 使用真实支付回归普通支付成功弹窗和营养支付成功弹窗。
• 回归语音播报和客屏流程。
• 确认上线时间、设备范围、发布渠道和回滚包。

七 已知限制与待补验项

• 当前设备接口没有超过 6 个字符的自定义分类测试数据，因此名称省略规则已完成单元测试，但真机长名称截图仍待补充。
• 已完成分类与营养开关四种组合、设置返回即时生效、隐藏筛选清理和购物车保持验证；真实支付、语音和客屏仍待上线前专项回归。
• 不同餐段可能返回不同菜谱和自定义分类集合，多餐段配置需要分别核对。
• 项目全量 lintDebug 仍受 18 个存量错误影响，首批错误位于本次未修改的 OrderDao.java；已有报告中本次修改文件未发现新增 Error。

八 上线观察与问题排查

上线后重点观察菜单请求成功率、协议版本异常、分类数量、菜品数量、无法匹配分类的菜品日志以及购物车和支付流程。

如果自定义分类只显示“全部”和“其他”，或普通分类突然减少，按以下顺序排查：

1. 先确认问题发生时对应的餐段，以及前后是否发生餐段切换。
2. 使用同一设备编号核对请求是否携带 group_mode=custom_category_v1。
3. 查看原始响应中的 categories、dishes 和 custom_category_id。
4. 如果原始响应本身只有“全部/其他”，优先检查该餐段的菜谱范围和后台分类关联。
5. 只有接口已返回普通分类但页面没有展示时，才继续排查客户端 DTO、Mapper 和动态分类渲染。

“营养展示”不负责生成、删除或重排自定义分类，不应把餐段数据变化直接判断为营养兼容或客户端渲染回归。

九 回滚方案

1. 如果仅自定义分类协议或后台配置异常，管理员可在基础设置中切换回“固定分类”，无需清理本地数据或修改数据库。
2. 如果客户端出现影响消费的异常，停止扩大发布范围，并通过既有发布渠道覆盖安装上一稳定版本 APK。
3. 回滚后复核固定分类菜单、购物车、刷卡、扫码、人脸支付及离线记账。
4. 本次无数据库迁移、无新权限，客户端回滚不需要执行数据结构回退。

十 发布群通知简版

【CusumptionMachine 菜单消费分类模式上线通知】

上线时间：待确认
正式版本：待确认（当前代码版本 2.11.1，versionCode 36）
任务编号：VWCG-1327

本次主要更新：
1. 基础设置新增“固定分类/自定义分类”，默认固定分类。
2. 自定义分类复用 /p/api/getMeal，并提交 group_mode=custom_category_v1。
3. 自定义分类按服务端顺序展示，超 6 个字符显示前 6 个字符加 ...。
4. 分类模式兼容原营养展示开关，设置返回立即生效，关闭营养时清除隐藏筛选。
5. 人脸识别阈值只显示数字，不再显示“分”。

验证情况：73 项单元测试全部通过；Debug APK 构建成功；当前设备已完成分类与营养四种组合、设置即时生效、购物车保持、人脸阈值显示和启动冒烟验证。

注意事项：上线前仍需确认正式版本号、签名、上线范围和回滚包，并补充多餐段、超长分类、真实支付、语音及客屏回归。若自定义分类只剩“全部/其他”，请优先核对当前餐段菜谱和接口原始响应。

十一 交付边界

• 本通知依据当前源码工作区、VWCG-1327 需求文档及实施记录整理。
• 未执行云效任务关联、Git 暂存、提交、推送、分支切换、合并或生产发布。
• 通知状态为“待上线”，由发布负责人补齐时间、正式版本、签名、设备范围和发布渠道后发送。