Technical Development Design
菜品自定义分类管理、导入与双屏消费机分类展示
当前分工已冻结：本线程只开发 store 的数据库、PC、普通导入和设备接口；Android 消费机由另一位同学负责，双方以 custom_category_v1 接口合同联调。
结论
本线程只交付 store；Android APK、动态 Tab 和真机验收已明确交给消费机同学。
2目标代码仓库：store、CusumptionMachine
1 + 1全局分类表 + 菜品关联字段
5进入开发前必须确认的门禁
- 分类表不带
store_id，原营养分类字段保持不变。 - “其他”是带稳定编码的真实系统记录，不用 0 或名称判断。
- 普通导入先全量校验，有任一错误就整批零写入并返回全部行级错误。
/p/api/getMeal增加版本化动态响应，旧固定1…6响应保留。- Android 固定 Tab 改为动态横向列表；营养、购物车、支付和副屏不改业务合同。
证据与差距
| 证据 | 等级 | 结论 |
|---|---|---|
| 云效正文与 3 个附件 | A | 明确全局共享、系统其他、导入和双屏验收 |
| store 当前源码 | A | 当前分支没有自定义分类；普通导入固定列且存在先删后验风险 |
CusumptionMachine master@54623f4f | A | 真实菜单调用 /p/api/getMeal，6 类、7 Tab、响应键均写死 |
| 历史国信提交 | B | 可复用 CRUD/PC 结构，但旧合同按商户隔离且不接导入/双屏 |
| 权限与统计建议 | D | 需要产品和研发评审后冻结 |
分类管理：系统“其他”锁定，普通分类支持 CRUD 和启停。
双屏：只替换顶部分类来源，营养、购物车与支付结构保持。
目标架构
全局分类CRUD / 权限
菜品关联新增 / 编辑 / 查看
普通导入整批预校验
MySQL分类表 + 外键值
getMeal新旧双合同
Android动态分类 Tab
非回归营养 / 支付 / 副屏
旧 APK 不传 group_mode，继续获得旧结构；新 APK 请求 custom_category_v1。这允许后端先发、APK 后发。
数据与迁移
全局分类表
- 无
store_id code=other标识系统分类active_name保证有效名称全局唯一- 普通分类按创建顺序，“其他”最后
菜品关联
ydy_dishes.custom_category_id- 0 只作为迁移/回滚过渡值
- 所有新增路径缺省解析为“其他”
- 删除按全部商户占用判断
历史表门禁：若目标库已部署过国信版带 store_id 的分类表，必须先做名称合并和菜品重映射，不能直接删除租户字段。
迁移顺序
创建/确认全局分类表
→ 插入或回读系统“其他”
→ 新增菜品关联字段
→ 发布所有写路径默认“其他”的后端
→ 幂等回填 0 / NULL / 悬空关联
→ 验证 invalid_count = 0
→ 发布 PC 和 Android
PC 与普通导入
| 模块 | 关键规则 | 优先级 |
|---|---|---|
| 分类管理 | 名称 20 字、全局唯一、系统其他保护、启停二次确认、全局占用删除 | P0 |
| 菜品表单 | 非必填；只选启用分类；空值归其他；当前停用值可保留 | P0 |
| 列表/查看 | 单分类筛选；停用分类可筛选；回显名称和状态；当前商户菜品隔离 | P0 |
| 普通导入 | 第 8 列；旧模板兼容；精确匹配；整批预校验；全部行级错误 | P0 |
| AI 导入 | 本期不增加列，所有新菜品默认归其他 | P1 |
现有普通导入会在遍历中先删除同名菜品，再继续校验后续行。改造必须先完成整份文件校验，之后才允许任何删除或写入。
双屏消费机
服务端
- 入口：
POST /p/api/getMeal - 新增
group_mode=custom_category_v1 - 返回
schema_version/categories/dishes - 停用分类不出 Tab，菜品仍进全部
- 0/悬空数据过渡期回落到其他并告警
Android
- 保留旧
1…6字段作为回退 - 固定 TextView 改为动态横向列表
Map<Long,List<DishBean>>- 刷新后选中分类消失则回到全部
- 副屏只做购物车/支付非回归
必须真机验证
- 分类超过一屏、20 字长名称和横向滚动
- 分类筛选与五类营养维度叠加
- 主屏购物车与副屏金额/数量一致
- 刷卡、扫码、人脸支付成功/失败/取消
- 重启、断网、刷新失败和恢复网络
发布与回滚
| 阶段 | 发布门禁 | 回滚入口 |
|---|---|---|
| 数据库 | 版本确认、备份、旧表预检、低峰 DDL | 已使用后保留表/字段，不物理删除 |
| store 后端 | 新旧 getMeal 合同、所有写路径默认其他 | 旧响应始终保留；恢复后重跑回填 |
| PC | 分类/菜品/导入实页和权限 | 隐藏入口，保留数据 |
| Android | 单测、构建、目标样机和支付全链路 | 安装上一版 APK |
进入开发前的 5 个门禁
- 全局写权限：仅超管/平台管理员，还是任一商户有权限的人都能修改？推荐仅全局管理员。
- 菜品数量：列表显示全局数量还是当前商户数量？删除必须使用全局占用。
- 历史表：目标数据库是否执行过国信版分类 SQL？
- 发布基线：目标分支、产品版本和正式 SQL 文件名是什么？
- 硬件样机：目标型号、Android 版本、主/副屏分辨率和验收负责人是谁？
当前可以进入技术评审和任务拆分；上述门禁未确认前，不建议直接编码。