VWCG-1327 菜单消费分类模式实施记录

1. 实施结论

已完成菜单消费“固定分类/自定义分类”客户端功能实现。基础设置默认使用固定分类；自定义分类模式复用 POST /p/api/getMeal，提交 group_mode=custom_category_v1。固定和自定义模式分别使用独立 Retrofit 方法及响应 DTO，并转换为统一 MenuCatalog 供菜单页面展示。

当前状态：代码、资源、单元测试和 Debug APK 构建均已完成；Debug APK 已安装到当前连接设备，并完成固定/自定义分类与营养开/关四种组合、设置返回即时生效及隐藏筛选清理验证。已在一个餐段观察到普通业务自定义分类；多餐段完整覆盖、真实支付和客屏仍待专项验收。

2. 核心设计

3. 代码改动

4. 行为说明

• 设置页首次进入默认显示“固定分类”，切换后立即保存。
• 从设置页返回菜单页时，如果模式发生变化，自动重新请求菜单。
• 从设置页返回菜单页时重新读取营养开关，显示状态立即生效。
• 关闭营养展示时清除已选营养条件，并恢复当前分类的完整菜品列表。
• 仅修改营养开关时不请求菜单；分类模式和营养开关同时修改时只按新模式请求一次。
• 固定模式请求不携带 group_mode，保持旧协议和七个固定分类。
• 自定义模式请求携带 group_mode=custom_category_v1。
• 自定义分类只显示 status=1 且名称有效的分类，并过滤重复 ID。
• 自定义分类标签名称不超过 6 个字符时原样显示，超过时显示前 6 个字符并追加 ...。
• 标签截断按 Unicode 字符计数，只影响显示；分类 ID、完整名称、菜品过滤和日志保持不变。
• 分类为空但菜品非空时，临时生成“全部”分类。
• 菜品分类无法匹配时仍保留在“全部”中，并输出可定位日志。
• 分类切换、刷新失败和协议降级均不清空购物车。

5. 自动化验证

5.1 单元测试与 APK 构建

执行命令：

JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew --no-daemon :app:testDebugUnitTest :app:assembleDebug

结果：BUILD SUCCESSFUL。

• 共执行 73 项单元测试，失败 0，错误 0。
• 新增覆盖模式默认值、固定分类聚合、自定义分类过滤、空分类恢复、协议版本及完整 JSON 解析。
• 新增覆盖营养区域关闭时清除隐藏筛选、自定义分类营养字段解析和 Mapper 营养字段保留。
• 新增 5 项分类名称格式化测试，覆盖少于 6 个字符、刚好 6 个字符、超过 6 个字符、Unicode 代理对和空名称。
• Debug APK：app/build/outputs/apk/debug/app-debug.apk。

5.2 资源与格式

• 修改的 XML 已通过 xmllint --noout。
• git diff --check 通过。
• 新增和修改文本均为 UTF-8 无 BOM、简体中文。

5.3 Lint

lintDebug 已执行，项目因 18 个存量错误返回失败，首批错误位于未修改的 OrderDao.java。报告中本次修改文件没有 Error；相关文件仍存在项目原有的布局、硬编码和可访问性 Warning。

Lint 报告：app/build/reports/lint-results-debug.html。

5.4 当前设备验证

验证设备：rk3568_r；应用版本：2.11.1、versionCode=36。

上述组合验证结束时，设备曾恢复为“自定义分类 + 营养关闭”，并清理了验证加入的临时购物车菜品。

真机组合验证完成后，代码继续进行了“营养展示默认值提取为具名常量”和“自定义分类标签超长省略”调整。最新代码已通过 73 项单元测试和 Debug 构建，最终 APK 已覆盖安装到当前设备并完成菜单页面启动冒烟验证，未出现崩溃。当前设备保存的是固定分类模式，接口也没有可用于截图的超长自定义分类测试数据，因此 6 字省略的真机视觉证据仍需在准备长名称分类数据后补充；边界规则已由 5 项单元测试覆盖。

5.5 自定义分类标签缺失问题排查

现象：自定义分类模式下曾只显示“全部”和“其他”，此前可见的普通自定义分类标签消失。

排查证据：

两次请求使用同一设备编号和同一客户端协议参数，客户端映射数量均与原始响应一致。最终确认根因是餐段切换导致服务端返回的菜谱范围和分类关联发生变化，不是营养展示适配或客户端渲染逻辑删除了分类。本次排查未修改业务代码。

后续同类问题按以下顺序优先排查：

1. 先确认问题时刻对应的餐段及是否刚发生餐段切换。
2. 再核对同一设备编号、同一 group_mode 请求的原始 categories 和 dishes。
3. 如果原始响应只有“全部/其他”，优先检查该餐段的菜谱与自定义分类关联配置。
4. 只有原始响应已包含普通自定义分类但页面未展示时，才进入客户端 DTO、Mapper、动态分类 UI 和刷新逻辑排查。

6. 待验收项

• 覆盖安装最终 Debug APK，补做一次启动和菜单页面冒烟验证。
• 抓取固定模式请求，确认不提交 group_mode。
• 抓取自定义模式请求，确认提交 group_mode=custom_category_v1。
• 固定并记录目标餐段，逐餐段完成普通自定义分类、多分类与长名称横向滚动验收。
• 使用真实支付完成普通/营养支付成功弹窗回归。
• 回归语音和客屏流程。

7. Git 边界

按用户要求，本次未执行任务关联、git add、提交、推送、分支切换或合并。

8. 变更记录