菜单消费分类模式需求文档

1. 文档信息

2. 背景与目标

当前菜单消费页面使用客户端固定分类展示菜品，分类固定为“全部、主食、素菜、荤菜、蛋奶坚果、水果、汤饮”。服务端现已在原有 POST /p/api/getMeal 接口上增加 custom_category_v1 响应模式，可以返回餐厅配置的自定义分类和菜品所属分类。

本需求目标是在基础设置中增加“菜单消费模式”，让管理员可以在固定分类和自定义分类之间切换。菜单消费页面根据设置选择对应的请求和响应契约，同时保持现有购物车、营养筛选、排序和支付流程不变。

3. 范围

3.1 In Scope

• 基础设置新增“菜单消费模式”。
• 菜单消费模式包含“固定分类”和“自定义分类”。
• 新安装、老版本升级和非法配置均默认使用固定分类。
• 固定分类继续使用当前分类和当前响应结构。
• 自定义分类调用原有 POST /p/api/getMeal，增加 group_mode=custom_category_v1。
• Android 客户端为固定分类和自定义分类分别声明 Retrofit 调用方法和响应 DTO。
• 两种响应通过各自 Mapper 转换为统一页面菜单模型。
• 自定义分类按照接口返回顺序动态显示，分类过多时支持横向滚动。
• 自定义分类标签名称最多显示前 6 个字符，超过 6 个字符时追加 ...。
• 保留现有营养筛选、营养排序、购物车、支付、语音和客屏逻辑。
• 增加新旧协议兼容、空数据、异常分类和网络失败处理。

3.2 Out of Scope

• 不新增后端接口路径。
• 不修改服务端分类配置功能。
• 不在 Android 端创建、编辑或删除自定义分类。
• 不修改现有菜品价格、库存、限购、营养标签和支付协议。
• 不修改客屏分类展示。
• 不修改订单数据结构和离线订单上传协议。
• 不在本需求中实现 custom_category_v2。
• 不在未取得明确授权时提交、推送、合并或发布代码。

4. 参与者与系统边界

5. 触发、前置条件与后置条件

5.1 触发事件

• 管理员进入基础设置并修改“菜单消费模式”。
• 用户进入菜单消费页面。
• 用户在菜单消费页面执行下拉刷新或空页面重试。

5.2 前置条件

5.3 成功后置条件

• 本地保存管理员选择的菜单消费模式。
• 菜单消费页面按照当前模式请求并展示对应分类。
• 分类切换后只更新菜品列表，不清空购物车。
• 现有营养筛选、排序和支付链路继续可用。

5.4 失败后置条件

• 网络或协议异常不得修改管理员已保存的模式。
• 已存在的购物车内容不得因菜单刷新失败被清空。
• 已有菜品列表在刷新失败时应继续保留。
• 首次加载失败且没有可用数据时显示错误或空状态，并允许重试。

6. 页面与交互要求

6.1 基础设置页面

新增设置项：

菜单消费模式    [固定分类] [自定义分类]

交互要求：

• 默认选中“固定分类”。
• 管理员点击选项后立即保存到本地。
• 重新进入设置页面时恢复已保存的选项。
• 显示文本使用简体中文资源，不在 Java 代码中重复硬编码。
• 设置值使用字符串枚举，为后续协议版本扩展保留空间。

建议持久化值：

6.2 菜单消费页面

固定分类模式：

• 保持当前固定分类栏和现有视觉样式。
• 分类为“全部、主食、素菜、荤菜、蛋奶坚果、水果、汤饮”。
• 默认选中“全部”。

自定义分类模式：

• 隐藏固定分类栏，显示动态自定义分类栏。
• 分类名称、顺序和启用状态来自接口 categories。
• 分类区域使用横向滚动容器，支持任意数量的分类。
• 分类标签名称不超过 6 个字符时原样显示；超过 6 个字符时显示前 6 个字符并追加 ...。
• 长度按 Unicode 字符计算，不能截断表情等需要 UTF-16 代理对表示的字符。
• 截断只作用于页面标签，接口响应、统一页面模型、分类匹配和日志继续保留完整名称。
• 默认优先选中 code=all 的分类。
• 如果没有 code=all，选中第一个启用分类。
• 点击分类后根据分类 ID 更新菜品列表。
• 切换分类不清空购物车，不改变当前支付方式设置。

7. API 契约

7.1 后端接口

固定分类和自定义分类复用同一个后端接口：

POST /p/api/getMeal

本需求不新增后端 URL。

7.2 固定分类请求

category=false
keyword=
code=<当前设备编号>

固定分类请求不提交 group_mode。

7.3 自定义分类请求

category=false
keyword=
code=<当前设备编号>
group_mode=custom_category_v1

7.4 Android 客户端接口声明

尽管后端路径相同，固定分类和自定义分类属于两套不同的数据契约。Android 客户端应声明两个 Retrofit 方法：

两个方法是同一后端接口的两种客户端映射，不代表新增服务端接口。

7.5 固定分类响应

固定分类继续使用现有 GetDishMenuResponse，只承载旧结构：

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "1": [],
    "2": [],
    "3": [],
    "4": [],
    "5": [],
    "6": []
  }
}

7.6 自定义分类响应

新增 GetCustomDishMenuResponse，只承载 custom_category_v1 结构：

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "schema_version": "custom_category_v1",
    "categories": [
      {
        "id": 0,
        "code": "all",
        "name": "全部",
        "status": 1,
        "is_system": 1
      },
      {
        "id": 12,
        "code": null,
        "name": "高蛋白套餐",
        "status": 1,
        "is_system": 0
      },
      {
        "id": 1,
        "code": "other",
        "name": "其他",
        "status": 1,
        "is_system": 1
      }
    ],
    "dishes": [
      {
        "uuid": "DISH-UUID-001",
        "name": "宫保鸡丁",
        "custom_category_id": 12,
        "custom_category_name": "高蛋白套餐",
        "custom_category_status": 1,
        "price": 18,
        "unit": "份",
        "energy_100g": 121
      }
    ]
  }
}

7.7 响应 DTO 分离原则

• GetDishMenuResponse 只描述固定分类旧协议。
• GetCustomDishMenuResponse 只描述自定义分类新协议。
• 不允许在一个响应类中同时堆叠旧协议的 1 至 6 字段和新协议的 schema_version/categories/dishes 字段。
• DishBean 由两种响应共用，并增加自定义分类字段。
• 项目自定义 DishBeanJsonDeserializer 必须显式解析 custom_category_id、custom_category_name 和 custom_category_status。

7.8 统一页面模型

两个网络响应分别转换为统一的页面菜单模型 MenuCatalog：

GetDishMenuResponse
→ FixedMenuCatalogMapper
→ MenuCatalog

GetCustomDishMenuResponse
→ CustomMenuCatalogMapper
→ MenuCatalog

MainActivity 只消费 MenuCatalog，不直接依赖两套网络字段结构。MenuCatalog 至少包含：

• 页面分类列表。
• 全部菜品列表。
• 分类 ID 到菜品列表的映射。

8. 数据规则

9. 主流程

10. 分支流程

11. 异常与恢复流程

临时降级只影响本次页面数据，不允许把用户保存的“自定义分类”自动改回“固定分类”。

12. 兼容性与不应影响逻辑

• 老版本升级后没有新增设置 Key 时继续使用固定分类。
• 固定分类的接口参数、响应 DTO、分类名称和分类过滤行为保持不变。
• 自定义分类成功路径只请求一次 getMeal。
• 协议异常降级时才允许重新发起一次固定分类请求。
• 菜品图片、价格、单位、重量、限购、销量、预订数和营养字段继续使用现有 DishBean。
• 购物车中已经选择的菜品不因分类切换消失。
• 菜名播报、总金额、总热量和支付结果不受影响。
• 刷卡、扫码、人脸支付、HTTP/MQTT 分流和离线记账不受影响。
• 客屏现有购物车与支付结果展示不受影响。

13. 日志与可观测性

客户端应记录以下信息，不记录支付凭证或人员敏感数据：

• 当前菜单分类模式。
• 实际调用的客户端方法。
• 响应 schema_version。
• 分类数量和菜品数量。
• 协议不匹配原因。
• 无法匹配分类的菜品 UUID 和分类 ID。
• 临时降级发生时间和结果。
• 网络失败或业务错误码。

13.1 分类异常的优先排查顺序

当自定义分类标签减少、只剩“全部/其他”或菜品数量发生明显变化时，必须先排查餐段和接口数据，再排查客户端代码：

1. 确认问题发生前后是否切换了早餐、午餐、晚餐等餐段，并记录问题时刻对应的当前餐段。
2. 使用问题设备的同一设备编号，核对该时刻 POST /p/api/getMeal 请求是否携带 group_mode=custom_category_v1。
3. 优先检查原始响应中的 categories、dishes、custom_category_id 和 custom_category_name，并与另一个餐段的响应进行对比。
4. 如果响应本身只包含 all 和 other，且菜品均归入 other，应先检查当前餐段的菜谱范围及自定义分类关联配置，不应直接判定为营养展示适配或客户端分类渲染回归。
5. 只有当接口已经返回普通自定义分类、但页面没有对应标签时，才继续排查响应 DTO、CustomMenuCatalogMapper、动态分类栏渲染和页面刷新逻辑。

“营养展示”只控制营养筛选、排序和热量区域，不负责生成、删除或重排接口返回的自定义分类。排查分类缺失时，应先固定餐段和接口响应，避免把餐段数据变化误判为营养功能回归。

14. 非功能要求

14.1 性能

• 固定分类成功路径不得增加额外网络请求。
• 自定义分类成功路径只调用一次 POST /p/api/getMeal。
• 分类切换必须使用本次响应的本地数据过滤，不得每次点击分类都重新请求接口。
• 接口响应时间继续沿用现有菜单接口服务指标；当前未提供量化 SLA，不作为本轮完成声明依据。

14.2 安全

• 不新增 Android 权限。
• 不新增用户身份、支付凭证或人员敏感字段。
• 设备编号继续使用现有本地配置和传输方式。
• 日志禁止记录卡号、付款码、人脸特征和鉴权密钥。

14.3 编码和资源

• 所有新增或修改文本必须为 UTF-8 无 BOM。
• 所有中文必须使用简体中文。
• 可见文本必须优先使用 Android 字符串资源。
• 协议值、设置 Key 和系统分类 Code 必须使用具名常量，禁止散落硬编码。

15. 验收标准

16. 测试矩阵

17. 实际接口验证记录

2026-09-07 已使用当前连接设备的实际接口配置验证自定义分类请求。验证时对设备编号进行脱敏记录。排查过程中确认，同一设备在不同餐段会返回不同菜谱和自定义分类集合。

该现象的根因是餐段切换后服务端返回的菜谱范围和分类关联发生变化，不是营养展示适配删除了自定义分类。客户端两次均按响应中的 categories 原顺序展示。后续验收和问题复现必须记录餐段，并分别验证目标餐段的后台分类配置。

18. 追踪矩阵

19. 依赖、风险与待确认项

20. 营养展示兼容补充方案

20.1 为什么需要补充

“固定分类/自定义分类”解决的是菜品如何分组展示；“营养展示”解决的是菜单页面是否提供营养筛选、排序、总热量以及支付后的营养反馈。两者属于相互独立的功能维度，不能因为分类来源发生变化而改变原有营养能力。

本次补充主要解决以下问题：

• 防止新增自定义分类后，原有营养筛选、营养排序和支付营养反馈发生功能回退。
• 修复菜单页面只在初始化时读取“营养展示”设置，导致从设置页直接返回后不能立即生效的问题。
• 防止关闭营养展示后，页面虽然隐藏了营养控件，但之前选中的营养条件仍在后台过滤菜品。
• 明确自定义分类响应需要继续提供现有营养字段，避免除热量外的其他营养筛选无数据可用。

20.2 需求性质

20.3 功能规则

菜单分类模式和营养展示配置必须独立组合生效：

营养开关继续复用 Constants.SETTING_NUTRITION_SHOW_SWITCHER，默认值保持为关闭，不增加第二个营养设置项。

开启营养展示时：

• 显示营养升序/降序区域、营养类型区域和已选菜品总热量区域。
• 默认不自动选中具体营养类型。
• 支付成功继续使用营养反馈弹窗。

关闭营养展示时：

• 隐藏上述菜单页面营养区域。
• 清除 mCurrentNutritionTabId 和营养选项选中状态。
• 重新显示当前分类下未经过营养条件过滤的菜品。
• 不清空购物车，不改变当前分类，不重新请求菜单接口。
• 支付成功使用普通成功弹窗。

无论采用哪种分类模式，页面统一执行以下数据处理顺序：

接口菜品
  → 按当前分类过滤
  → 按当前营养类型过滤
  → 按营养值升序或降序
  → 更新菜品列表

20.4 设置返回即时生效

管理员从菜单消费页面进入基础设置，修改配置后直接返回时：

• 分类模式发生变化：按照新模式重新请求菜单。
• 只有营养展示发生变化：只更新本地页面状态，不重新请求菜单。
• 营养展示由开变关：在隐藏控件的同时清除已有营养筛选并刷新当前分类列表。
• 分类模式和营养展示同时变化：使用最新配置，只执行一次菜单请求，避免重复刷新。
• 不要求退出菜单页面或重启应用。

20.5 自定义分类接口营养字段

自定义分类响应中的 dishes 应继续提供现有五类营养字段：

{
  "energy_100g": 121,
  "carbohydrate_100g": 12.5,
  "protein_100g": 18,
  "fat_100g": 6.2,
  "dietary_fiber_100g": 2.1
}

字段规则：

• 字段允许为数字、数字字符串或 null。
• 字段缺失、为空或无法解析时按“无该项营养数据”处理，页面不得崩溃。
• 选择某项营养条件后，缺少对应有效数值的菜品不参与该项筛选和排序。
• 如果服务端只返回 energy_100g，客户端只能保证热量功能可用，其他四项营养筛选可能得到空列表。
• 要达到与固定分类完全一致的能力，固定和自定义响应中的五个营养字段必须保持相同语义。

20.6 技术落地

MainActivity 增加统一的营养状态刷新方法，例如 refreshNutritionDisplaySetting()，负责：

1. 读取最新的营养展示配置。
2. 统一更新三个营养相关区域的可见性。
3. 关闭营养展示时清除营养选中状态。
4. 返回是否需要重新刷新本地菜品列表。

调用位置：

• initViews()：处理首次进入菜单页面的初始状态。
• onResume()：处理从基础设置返回后的即时状态变化。

推荐的 onResume() 处理顺序：

读取最新分类模式和营养设置
  → 营养关闭时清除隐藏筛选
  → 分类模式是否变化？
      是：按新模式请求一次菜单
      否：营养筛选是否被清除？
          是：刷新本地菜品列表
          否：不处理

现有 DishBean 和 DishBeanJsonDeserializer 已承载五种营养字段，自定义分类 Mapper 应继续传递同一个 DishBean，禁止复制菜品时丢失营养字段。固定和自定义响应继续通过各自 Mapper 转换为统一 MenuCatalog，页面不得增加两套营养处理分支。

20.7 验收标准

21. 下一步实施计划

当前下一步是完成剩余真机验收：固定并记录目标餐段，逐餐段验证普通业务自定义分类、多分类和长名称；随后使用真实支付回归普通/营养支付成功弹窗、语音和客屏。本计划不包含云效关联任务、Git 提交、推送、合并或发布操作。

22. Definition of Ready 审计

当前结论：DoR: READY，Android 客户端开发和核心组合验证已完成。Q-002 不阻塞当前实现，但必须在完整真机验收前关闭。

23. 变更记录