ZhctWeightingTableYoukate 410 型称重台协作指南

本指南沉淀 ZhctWeightingTableYoukate Android 项目的代码拉取、构建、硬件、接口、测试和维护协作方式，面向后续开发、问题排查、新人交接和 AI 协作。项目技术说明请先阅读 README.md。

型号事实：项目负责人于 2026-09-09 确认，Codeup 仓库 ZhctWeightingTableYoukate 对应 410 型优卡特称重台。源码中仍保留“称重台450型”和 ZhctWeightingTable 等历史标识；协作者不得据此把本仓库重新归类为 450，也不得在没有接口与真机回归的情况下直接改动这些兼容字段。

项目位置

协作工作区根目录：zhct/
业务代码：zhct/zhctproject/android/ZhctWeightingTableYoukate
协作文档：zhct/zhctprompt/work_android/ZhctWeightingTableYoukate/
Codeup 项目页：https://codeup.aliyun.com/60069db88deaa14d9e02b875/zhct/device/restaurant/billedBygram/ZhctWeightingTableYoukate
SSH 仓库：git@codeup.aliyun.com:60069db88deaa14d9e02b875/zhct/device/restaurant/billedBygram/ZhctWeightingTableYoukate.git
HTTPS 仓库：https://codeup.aliyun.com/60069db88deaa14d9e02b875/zhct/device/restaurant/billedBygram/ZhctWeightingTableYoukate.git
远端默认分支：master

项目	已核验值
远端默认分支 HEAD	`master@2f759f9415b4`
默认分支版本	`versionName 2.6.0`、`versionCode 21`
梁工本机任务分支	`zymy_ongoing@21a5d3d956f0`，工作树干净
梁工本机任务分支版本	`versionName 2.6.2`、`versionCode 23`

新协作者的完成目标

新协作者读取本页后，应能完成以下闭环：

从 Codeup 拉取 410 项目代码到统一 Android 目录。
确认远端、分支、HEAD 和工作树状态，避免在错误副本或错误客户分支上开发。
使用 JDK 8 完成 Gradle Sync、单元测试和 Debug APK 构建。
连接指定 410 真机，完成安装、启动及称重、扫码、取餐上传主流程验证。
将方案、排查、测试和变更记录归档到本协作目录，不向业务仓库复制叙述型过程文档。

快速开始

方式一：使用 Android Studio 拉取

打开 Android Studio，选择 Get from VCS。
填写 SSH 或 HTTPS 仓库地址。
本地目录选择 zhct/zhctproject/android/ZhctWeightingTableYoukate。
拉取完成后打开项目根目录，等待 Gradle Sync。
将 Gradle JDK 切换为 JDK 8。
按 Android Studio 提示补齐 Android SDK Platform 30 和对应 Build Tools。
先完成 Debug 构建，再连接项目负责人指定的 410 真机运行。

方式二：命令行拉取

在个人 zhct 工作区根目录执行：

mkdir -p zhctproject/android
git clone \
  git@codeup.aliyun.com:60069db88deaa14d9e02b875/zhct/device/restaurant/billedBygram/ZhctWeightingTableYoukate.git \
  zhctproject/android/ZhctWeightingTableYoukate

如果 SSH 权限不可用，在已获得 Codeup HTTPS 权限的前提下使用：

git clone \
  https://codeup.aliyun.com/60069db88deaa14d9e02b875/zhct/device/restaurant/billedBygram/ZhctWeightingTableYoukate.git \
  zhctproject/android/ZhctWeightingTableYoukate

拉取后的固定核验

repo_dir="zhctproject/android/ZhctWeightingTableYoukate"
git -C "$repo_dir" remote -v
git -C "$repo_dir" branch --show-current
git -C "$repo_dir" rev-parse HEAD
git -C "$repo_dir" status --short --branch

核验要求：

origin 必须指向本页登记的 Codeup 仓库。
新拉取仓库默认应进入 master；任务指定客户线或功能分支时，以任务契约为准。
工作树存在他人未提交修改时，停止覆盖、清理、切分支或批量同步，先确认变更归属。
不以本机外层旧目录或历史备份作为新的协作入口。

项目概述

ZhctWeightingTableYoukate 是运行在 410 型优卡特称重台上的 Android 应用，负责餐盘识别、实时称重、菜品与营养展示、取餐量计算、取餐记录上传、离线补传、云端排菜、设备心跳和异常告警。

典型取餐流程：

设备启动并检查 API 地址、设备编号和配对码。
应用通过启动接口获取 MQTT、首页展示模式和取餐限制。
应用同步当前排菜；无排菜时进入未排菜页。
410 称体读取餐盘码、重量和稳定状态。
应用查询餐盘绑定人员、营养信息和推荐结果。
餐盘离开后计算本次取餐重量。
取餐记录先写入本地数据库，再由后台任务串行上传。
网络或服务异常时保留本地记录，满足条件后继续补传。

核心能力

设备初始化：申请必要权限，检查本地配置，初始化网络、数据库、日志和称体 SDK。
410 硬件适配：通过 DeviceSDK-80.1.10.12.20260129.aar 对接 PC681 称体扫码能力，由 YoukateHardwareManager 统一管理。
云端排菜：同步设备当前菜品，支持未排菜分流、手动排菜和 MQTT 菜品变更。
取餐识别：识别餐盘码、人员绑定、推荐信息和取餐前后稳定重量。
取餐上传：本地先落库，后台串行补传；服务端明确成功后才删除本地记录。
异常与防逃餐：覆盖未绑定餐盘、无盘取餐、余额不足、餐盘状态和解除告警等策略。
设备维护：提供称体初始化、连接、置零、标定、鉴别率和采样间隔等调试入口。
运行监控：设备心跳、本地日志、业务日志、企业告警、阿里云 SLS 和 RUM。
界面模式：支持深色主题和多种余额、营养展示模式。

启动与运行主链路

`StartActivity`

申请存储、网络、相机等运行权限。
校验 API_ADDRESS、TERMINAL_NUMBER 和 PAIR_CODE。
配置缺失时进入 SetActivity。
调用 /p/api/equipmentStart 获取设备运行配置。
启动 CustomMqttService。
调用 /api/weigh/dishes 获取当前设备排菜。
有排菜进入 HomeActivity，无排菜进入 UnSetDishActivity。

`HomeActivity`

通过 YoukateHardwareManager 初始化并监听称体。
展示打餐前页面和当前菜品。
接收称重状态、净重和餐盘码。
识别有效餐盘后查询人员、营养和推荐数据。
进入打餐中状态并记录开始重量。
餐盘离开且满足稳定条件后计算取餐重量。
保存并上传取餐记录；失败时保留本地数据等待补传。
处理 MQTT 排菜变更、心跳、提示、灯光和告警状态。

关键代码入口

代码位置	职责
`app/src/main/java/com/cpt/zhct/weighting/StartActivity.java`	启动、权限、配置检查、设备初始化和页面分流
`app/src/main/java/com/cpt/zhct/weighting/activity/HomeActivity.java`	称重取餐主流程、状态切换、重量和扫码回调
`app/src/main/java/com/cpt/zhct/weighting/activity/SetActivity.java`	API、设备、提示、硬件调试和版本配置
`app/src/main/java/com/cpt/zhct/weighting/hardware/YoukateHardwareManager.java`	PC681 SDK、称重状态、扫码数据和串口生命周期统一入口
`app/src/main/java/com/cpt/zhct/weighting/network/CPTNetworkRequest.java`	Retrofit 接口定义
`app/src/main/java/com/cpt/zhct/weighting/network/CPTService.java`	网络请求封装
`app/src/main/java/com/cpt/zhct/weighting/database/`	本地取餐记录与补传数据
`app/src/main/java/com/cpt/zhct/weighting/workmanager/`	心跳和离线取餐记录后台任务
`app/src/main/java/com/cpt/zhct/weighting/service/CustomMqttService.java`	MQTT 连接、订阅和消息处理
`app/src/main/java/com/cpt/zhct/weighting/antiescape/`	A01/A02/A03 等防逃餐检测与告警策略

主要接口

功能	接口
启动初始化	`POST /p/api/equipmentStart`
当前设备排菜	`POST /api/weigh/dishes`
推送设备排菜	`POST /api/weigh/pushDishes`
餐盘人员与推荐查询	`POST /p/api/selectPlate`
取餐记录上传	`POST /p/api/zhctPushMeal`
当前餐次营养	`POST /p/api/currentMealNutrition`
配对码校验	`POST /p/api/matecode`
设备心跳	`POST /p/api/heartbeat`
菜品库与菜品详情	`POST /p/api/CaterList`、`POST /p/api/find`
餐段信息	`POST /p/api/getRestaurantsInfo`
MQTT 处理反馈	`POST /p/api/feedback`
当前菜品重量	`POST /api/weigh/pushWeight`
版本检查	`POST /p/api/getNewVersion`

接口字段、错误码和兼容行为必须以目标分支源码及对应服务端契约为准。本页只用于快速定位，不替代接口评审。

配置与本地数据

本地配置主要通过 MMKV 管理，关键键集中在 Constants.java：

配置	作用
`API_ADDRESS`	服务端地址；部署时必须使用任务指定环境
`TERMINAL_NUMBER`	设备编号
`PAIR_CODE`	配对码
`CURRENT_DISH_ID`、`CURRENT_DISH_NAME`	当前排菜信息
`SPOON_WEIGHT`、`SKIP_WEIGHT`	勺重和起跳阈值
`SINGLE_PICK_WEIGHT_MAX`	单次最大取餐重量，支持服务端下发
`WEIGHER_INTERVAL_MS`	称体采样间隔
`STYLE_HOME_DISPLAY`	首页余额与营养展示模式
报警、灯光、语音相关开关	控制提示和防逃餐策略

注意：源码保留历史默认接口地址，仅用于旧环境兼容。协作者不得把默认值当作生产环境，也不得把客户地址、配对码、账号或密钥写入 Git 和协作文档。

构建基线

远端 master@2f759f9415b4 于 2026-09-09 核验的基线：

项目	值
工程结构	单模块 `:app`
Android Gradle Plugin	`3.4.1`
Gradle Wrapper	`5.1.1`
Java	Java 8
compileSdkVersion	`30`
minSdkVersion	`26`
targetSdkVersion	`30`
ABI	`arm64-v8a`、`armeabi-v7a`
applicationId	`com.cpt.zhct.weighting`
入口 Activity	`com.cpt.zhct.weighting.StartActivity`
核心硬件依赖	`app/libs/DeviceSDK-80.1.10.12.20260129.aar`

命令行验证

Jack于2026-09-09要求使用Docker内不同JDK，不在Mac安装或调用任务JDK。JDK8容器构建Android，JDK17容器做SDK审计；Linux Android工具由容器准备。

请先review 整体方案，再按双JDK执行说明运行；本任务当前PENDING_REVIEW。

Debug APK 默认位于：

app/build/outputs/apk/debug/app-debug.apk

真机运行与验收

410 的称重、扫码、灯光、告警和串口能力不能用普通手机或模拟器代替。设备地址由现场或项目负责人提供，不在文档中固定某个客户设备 IP。

adb devices
adb connect <410-device-ip>:5555
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.cpt.zhct.weighting/.StartActivity

最低真机验收：

应用安装并进入启动页，无持续崩溃或权限死循环。
设置页能保存指定环境、设备编号和配对码。
设备初始化成功，能读取稳定状态、重量和餐盘码。
有排菜进入取餐首页，无排菜进入明确提示页。
放盘、取餐、移盘后重量计算符合任务验收阈值。
正常网络下上传成功；断网时本地记录保留，恢复后补传且不重复。
MQTT 排菜、心跳、灯光、声音和告警按目标分支规则工作。
日志中不出现账号、密钥、完整个人敏感信息或不可控高频刷屏。

协作文档目录

路径	用途
`README.md` / `README.html`	项目概述、技术说明和协作入口
`COLLABORATION_GUIDE.md` / `COLLABORATION_GUIDE.html`	代码拉取、构建、真机验收和协作交付说明
`docs/`	设计、现状、业务流程和故障说明
`implementation_plans/`	开发实施计划与验证步骤
`change_records/`	每次独立代码或协作文档变更的记录

推荐先阅读：

README.md：了解项目能力、代码结构、配置、接口和硬件边界。
COLLABORATION_GUIDE.md：确认 410 项目边界并完成代码拉取。
docs/2026-08-05-alarm-and-prompt-current-state.md：了解报警和提示现状。
docs/2026-08-11-anti-escape-alarm-comprehensive-plan.md：了解防逃餐总体方案。
implementation_plans/2026-07-14-reliable-pick-meal-upload-phase1.md：了解本地落库和补传机制。
docs/2026-07-31-pc681-receive-cache-race-fix.md：了解 PC681 接收缓存和监听生命周期风险。
change_records/ 中与当前任务最接近的最新记录。

已知风险与停止规则

410 型号与历史代码标识不一致

已确认业务事实：本仓库对应 410 型优卡特称重台。
当前历史代码：Constants.DEVICE_TYPE 仍为“称重台450型”，应用名仍为 ZhctWeightingTable。
处理原则：文档按 410 归类；如果要修改代码标识、服务端设备类型或版本分发参数，必须先确认后端匹配规则、历史设备兼容和真机升级范围。

老构建链路

Gradle 5.1.1 / AGP 3.4.1 优先使用 JDK 8。
新 JDK 下出现 Groovy、Gradle 初始化或插件错误时，先校验 JDK，不要直接升级构建链。

PC681 SDK 生命周期

业务代码必须通过 YoukateHardwareManager 使用称体 SDK。
已知第三方 SDK release() 存在 native 字段契约风险；不得绕过封装直接调用或重复创建串口所有者。

现场硬件门禁

未连接指定 410 真机时，只能证明静态检查、单元测试或 APK 构建结果。
未验证称重、扫码、移盘、告警、离线补传和恢复，不得声称硬件发布就绪。

Git 与资料边界

不执行未经任务授权的提交、推送、合并、部署或设备升级。
不覆盖未知本地修改，不使用 reset --hard、clean、强推或整份覆盖式冲突处理。
业务源码、运行配置和测试代码留在 ZhctWeightingTableYoukate 仓库。
方案、排查、验收、截图和变更说明放在本协作目录；正式文档保持同名 Markdown 与 HTML。

协作者交付清单

已核对仓库绝对路径、origin、目标分支和 HEAD。
已阅读本页及与任务相关的最新设计/变更记录。
已明确本次目标设备是 410，且识别到历史 450 代码标识风险。
已完成 JDK、SDK、Gradle Sync 和 Debug 构建检查。
已运行受影响单元测试并记录结果。
涉及硬件时已在指定 410 真机完成主流程、异常和恢复验证。
已更新对应 change_records/ Markdown/HTML 记录。
未把凭据、客户敏感数据、APK 或大体积调试文件提交到 Git。
已记录验证结果、遗留风险和下一位协作者的恢复入口。

事实来源与边界

410 型号映射：项目负责人 2026-09-09 明确确认。
仓库、分支和 HEAD：Codeup Git 远端只读核验。
技术栈、版本、入口、接口和历史标识：master@2f759f9415b4 与梁工本机只读源码核验。
业务能力和历史风险：本目录已有设计、实施和变更记录。
未执行生产部署、设备升级或客户现场写操作；真机发布状态必须由对应项目验收证据单独证明。