ManageDishTeminal 开发前的规划动作

1. 项目启动定位

本项目是安卓 Pad 横屏客户端，核心用于称重台排菜和设置菜谱。当前阶段先进入本地开发和框架搭建，接口文档后续提供，先用空布局和预留封装跑通页面骨架与主流程。

• 目标设备竖屏物理分辨率为 2136 x 3200，应用按横屏 3200 x 2136 适配。
• 只适配这一类 Pad。
• 强制横屏，不支持竖屏。
• 全屏运行，隐藏系统状态栏和导航栏。
• 允许按 Android 原生控件适配，不要求逐像素还原 HTML 原型，但整体布局和主流程尽量贴近原型。
• 菜品默认图、空状态、加载状态、失败状态首期均可用文字提示。

2. 技术框架约定

3. 首期页面范围

需要实现

• 登录页。
• 功能首页。
• 排菜页。
• 设置菜谱页。
• 系统设置弹窗。
• 排菜选择菜品弹窗或抽屉。
• 替换菜品确认弹框。
• 复制菜谱弹窗或抽屉。

首期暂不做

• 新增菜品。
• 编辑菜品。
• 图片上传。
• 取消排菜。
• 离线队列。
• 实时推送。
• 全拼和首字母搜索。

4. 业务展示规则

• 首页不需要天气，先写死基础信息。
• 排菜页进入后先拉取档口列表，默认选中第一个档口。
• 排菜页再获取餐段时间，根据当前时间显示当前餐段。
• 档口列表从接口来。
• 菜品分类从接口来。
• 菜品搜索首期只做名称模糊搜索。
• 已排菜、未排菜、在线、离线筛选首期都要做。
• 单称/双称字段结构由接口支持，客户端 UI 预留 main、left、right。
• 历史日期禁止编辑。
• 设置菜谱默认显示日期为当天。

5. 交互规则

• 未排菜称位：点菜后立即保存。
• 已排菜称位：点新菜时弹替换确认框，确认后覆盖。
• 取消排菜：首期不支持。
• 设置菜谱添加菜品：抽屉内点击菜品只是选中，点击底部“加入已选菜品”后才保存到菜谱。
• 菜谱移除菜品：不二次确认，直接移除并 toast。
• 复制菜谱：目标已有菜品时跳过。
• 复制菜谱保存后建议提示复制数量和跳过数量，例如“已复制 8 道菜，跳过 3 道重复菜品”。
• 设备离线问题由服务端按现有逻辑处理，设备端首期忽略。
• 离线期间同一称位多次修改按覆盖处理。
• 菜品价格修改按菜品信息变更处理。
• 图片上传失败是否允许先保存菜品：设备端首期不做新增菜品，可忽略。

6. 接口待提供清单

接口材料稍后提供。框架阶段先留统一网络层、Repository、DTO、空布局和错误状态，不要把接口调用散落在页面中。

• 获取档口列表。
• 获取餐段时间。
• 获取称重台列表，包含单称/双称、在线/离线、已排菜/未排菜状态。
• 获取菜品分类。
• 获取菜品列表，首期支持名称模糊搜索。
• 排菜保存。
• 替换排菜保存。
• 获取指定日期、餐次、档口的菜谱。
• 添加菜品到菜谱。
• 移除菜谱菜品。
• 复制菜谱，返回复制数量和跳过数量。
• 系统设置相关接口如后续需要再补。

7. 网络请求框架规划

• 使用 Retrofit + OkHttp。
• 封装统一 ApiClient，页面不得直接创建 Retrofit。
• baseUrl 可配置，后续可从系统设置或构建配置读取。
• 统一设置连接超时、读超时、写超时，均为 5 秒。
• 统一请求头预留 token、设备编号、项目 ID、app version。
• Debug 环境开启网络日志，Release 环境关闭或脱敏。
• 统一处理网络异常、超时、服务端错误码、数据为空。
• 建议接口响应统一为 code、message、data、success。
• Repository 层负责把接口结果转成页面状态，Activity/Fragment 不直接解析复杂错误。

页面状态

• loading：加载中...
• empty：按业务显示空布局文字。
• success：正常渲染。
• error：数据加载失败，请稍后重试。
• no network：网络异常，请检查连接。

8. 架构层规划

建议分包

• ui：Activity、Fragment、Adapter、Dialog、Drawer。
• data：Repository、接口数据源、本地数据源。
• network：Retrofit、OkHttp、Interceptor、ApiService。
• model：接口 DTO、页面 Bean。
• storage：SharedPreferences、SQLite helper。
• common：工具类、常量、基类、统一 toast、loading、弹窗。
• crash：异常捕获、日志落盘。
• log：行为日志和运行日志。

基类和通用能力

• BaseActivity：横屏/全屏处理、统一标题栏、loading、toast、错误展示、防重复点击辅助。
• BaseFragment：初始化 view、通用 loading/error/empty。
• BaseRepository：统一请求包装和错误转换。
• LogUtil：统一日志输出，支持 debug 开关。
• 统一防重复点击，避免连续排菜重复提交。
• 接口请求中的页面销毁要取消回调或判断页面状态。
• 统一处理空数组和空字段，避免页面空指针。

本地存储

• SharedPreferences：登录状态、本地密码、baseUrl/配置链接、字号、主题。
• SQLite：预留菜谱缓存、称重台缓存、操作记录；行为日志首期先参考现有项目写本地文件，后续需要查询/上传状态时再补 SQLite 表。

8.1 统一标题栏规划

标题栏需要封装成公共组件，避免多 Activity 分散实现。可参考现有安卓项目里 BaseActivity 统一管理标题栏的方式，但本项目按 ManageDishTeminal 的视觉和交互重新收口。

• 组件名称建议：CommonTitleBar 或 BaseTitleBar。
• 接入方式：由 BaseActivity 统一初始化，业务 Activity 只调用方法设置标题、返回按钮、右侧操作。
• 左侧区域：默认显示页面标题栏 Logo，即 icon_logo.png；子页面可显示返回按钮 + Logo。
• 中间区域：显示当前页面标题，例如“功能首页”“排菜”“设置菜谱”。
• 右侧区域：可显示系统设置、当前用户、时间/日期等扩展入口；按页面需要显示或隐藏。
• 标题栏高度、Logo 尺寸、左右间距、背景色、文字大小统一定义在公共布局/样式中。
• 换肤时标题栏背景、标题颜色、按钮选中态跟随主题色刷新；Logo 图片本身不随主题切换。
• 全屏模式下标题栏负责避开系统栏影响，页面内容从标题栏下方开始布局。
• 标题栏点击事件统一走接口回调，页面不要直接查找标题栏内部子 View。

BaseActivity 建议暴露的方法

• setTitleText(String title)
• setTitleLogoVisible(boolean visible)
• setBackVisible(boolean visible)
• setRightActionText(String text)
• setRightActionVisible(boolean visible)
• setOnRightActionClickListener(...)
• applyThemeToTitleBar()

8.2 系统设置换肤规划

系统设置页的换肤功能纳入首期规划，但首期只做本地 UI 主题切换，不依赖接口。

• 入口位置：系统设置弹窗。
• 保存位置：SharedPreferences。
• 主题范围：标题栏、主按钮、选中态、重点状态色、部分分割线/浅色背景。
• 首期建议内置主题：默认橙色、蓝色、绿色。
• 换肤后立即刷新当前页面可见 UI，并保存为下次启动默认主题。
• 页面标题栏 Logo 固定使用 icon_logo.png，不随主题切换。
• App 启动图标固定使用 launcher.png，不随主题切换。
• 字号设置与换肤同属系统设置，独立保存，避免主题切换影响字号。

首期换肤不要求动态替换所有 drawable，可先通过统一颜色资源、BaseActivity 和公共控件方法收口，避免颜色散落在页面 XML 中。

9. Crash 拦截与日志

• 增加全局 UncaughtExceptionHandler。
• Crash 信息本地落盘。
• Crash 文件建议记录崩溃时间、Android 版本、app version、设备型号、堆栈信息、当前页面/模块。
• 本地最多保留最近 10 条 Crash 文件。
• Debug 环境打印完整堆栈；Release 环境记录文件并给出异常提示。
• 后续如有日志上传接口，再补自动上传。

10. 行为日志本地记录

行为日志纳入框架层。首期参考现有安卓项目的日志记录方式：调试日志走 LogUtils，业务行为日志封装成事件 JSON，异步写入本地文件；后续如有日志上传接口，再扩展上传。首期不强制把行为日志存 SQLite。

参考项目实现

• CusumptionMachine/utils/LogUtils.java：Debug 环境输出日志，自动带方法名、文件名、行号。
• CusumptionMachine/utils/LocalFileRecorder.java：异步写入 externalFilesDir/Log/ 下的按日期分文件日志。
• ZhctWeightingTableYoukate/utils/UploadLogUtils.java：按事件类型、事件码、事件消息组装 JSON。
• ZhctWeightingTableYoukate/utils/SlsLogUploader.java：上传失败时回落到 LocalFileRecorder.writeLog(...)。

首期落地方式

• 新增 LogUtils：保持参考项目风格，Debug 环境输出方法名、文件名、行号。
• 新增 LocalFileRecorder：异步写本地文件，目录建议 externalFilesDir/Log/。
• 新增 BehaviorLogUtils：封装业务行为日志，不让页面直接拼日志字符串。
• 行为日志按日期分文件，例如 behavior_2026-06-22.txt。
• Crash 日志仍写入 externalFilesDir/crash/；Crash 时追加最近行为日志可作为后续增强。
• 系统设置里预留“导出日志”入口，首期可隐藏或开发模式可见。
• SQLite 行为日志表不作为首期必做；如果后续需要查询、筛选、上传状态，再补数据库表。

记录范围

• 登录成功/失败、退出登录。
• 进入功能首页、排菜页、设置菜谱页。
• 打开系统设置、保存系统设置。
• 拉取档口列表、餐段时间、称重台列表、菜品列表、分类列表。
• 切换档口、切换筛选。
• 打开排菜抽屉、选择菜品排菜、替换确认/取消。
• 排菜接口成功/失败。
• 设置菜谱日期/餐次/档口切换。
• 添加菜品到菜谱、移除菜谱菜品、复制菜谱。
• 接口请求失败。
• Crash 前最后操作。

日志内容格式

参考 UploadLogUtils 的事件 JSON 方式，首期每条行为日志写一行 JSON 字符串，便于后续上传或排查。

首批事件码

• LOGIN_SUCCESS、LOGIN_FAIL、LOGOUT
• HOME_ENTER、ARRANGE_ENTER、RECIPE_ENTER
• SETTINGS_OPEN、SETTINGS_SAVE
• STALL_LIST_LOAD、MEAL_TIME_LOAD、SCALE_LIST_LOAD
• DISH_LIST_LOAD、CATEGORY_LIST_LOAD
• ARRANGE_DRAWER_OPEN、ARRANGE_DISH_SELECT
• ARRANGE_REPLACE_CONFIRM、ARRANGE_REPLACE_CANCEL
• ARRANGE_SAVE_SUCCESS、ARRANGE_SAVE_FAIL
• RECIPE_DATE_CHANGE、RECIPE_MEAL_CHANGE、RECIPE_STALL_CHANGE
• RECIPE_DISH_SELECT、RECIPE_SAVE_SUCCESS、RECIPE_SAVE_FAIL
• RECIPE_DISH_REMOVE
• RECIPE_COPY_OPEN、RECIPE_COPY_CONFIRM
• RECIPE_COPY_SUCCESS、RECIPE_COPY_FAIL
• API_REQUEST_FAIL、CRASH_CAPTURED

11. 空布局文案

• 称重台列表为空：暂无称重台数据。
• 档口列表为空：暂无档口数据。
• 菜品列表为空：暂无菜品数据。
• 菜谱为空：当前日期暂无菜谱。
• 加载失败：数据加载失败，请稍后重试。
• 加载中：加载中...

12. 仍需确认或提供

• 完整接口文档。
• 实际目标设备 Android 系统版本。
• 餐段时间接口和字段。
• 档口接口和字段。
• 菜品分类接口和字段。
• 单称/双称称位字段结构。
• 复制菜谱接口是否返回复制数量、跳过数量。
• 系统设置里哪些配置需要真实保存，哪些只是展示。
• 服务端排菜下发链路确认。
• 设备状态后续是否需要定时刷新、WebSocket 或 MQTT。