SmartPlateCabinet/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

SmartTakePlate（发盘机）是一个基于 Android 的智能餐盘柜控制系统，集成了人脸识别和 PLC 硬件控制功能。

应用ID: com.sw.platecabinet.member（会员版；命名空间 com.sw.platecabinet） 最低SDK: 24 (Android 7.0) 目标SDK: 35

构建与运行

构建项目

./gradlew assembleDebug

安装到设备

./gradlew installDebug

清理构建

./gradlew clean

注意: 构建需要 Java 17 环境（compileOptions 为 Java 11，但 Gradle 需 JDK 17）。直接使用系统默认 JDK 11 会报错，需使用 Android Studio 自带的 JBR 设置 JAVA_HOME 后再执行 gradlew。

项目架构

模块结构

• app/ - 主应用模块（PLC控制、业务逻辑）
• lib_face/ - 人脸识别库模块（ArcFace SDK封装）

架构模式

采用 MVVM 架构：

• View: Activity/Fragment（使用 ViewBinding）
• ViewModel: 继承自 BaseViewModel，处理业务逻辑和状态管理
• Repository: BaseRepository 和 RemoteRepository 处理数据层

关键技术栈

• Kotlin 2.0.21 + Coroutines
• Retrofit 3.0.0 + OkHttp 4.12.0（网络请求）
• Room 2.2.5（人脸数据本地存储）
• CameraX 1.3.0（摄像头）
• EventBus 3.3.1（事件总线）
• PLC SDK (plc_aar_104.aar)（硬件控制）
• ArcSoft 人脸识别 SDK

核心功能模块

1. 串口硬件控制（柜锁）

核心包: lib_face/com.sw.plate.utils.comn/

关键类：

• SerialApi - 对外 API 门面（静态方法），串口路径 /dev/ttyS2、波特率 19200
  • init() - 打开串口连接
  • openPlate(boxNumber, callback) - 开柜（命令由 CabinetLockCommand.generateOpenCommand 生成）
  • close() - 关闭串口
• SerialPortManager - 串口管理（发送命令、接收线程 SerialReadThread）
• CabinetLockCommand - 柜锁命令生成

调用方: BaseActivity、BindPlateFragment、SettingListFragment 直接调用 SerialApi。

注意: 所有串口操作都是异步的，通过 SerialPortManager.SendCallback 回调返回结果。

2. 人脸识别

核心包: lib_face/com.sw.plate.utils.arcface/

关键类：

• FaceApi - 人脸操作 API
• RecognizeViewModel - 人脸识别 ViewModel
• FaceDatabase - Room 数据库（存储人脸特征）
• CameraHelper / DualCameraHelper - 摄像头管理

人脸数据流程：

1. 从服务器获取用户人脸数据（UserViewModel.getUserFaceList()）
2. 存储到本地 Room 数据库
3. 实时识别时与本地数据库对比

3. 网络层

API 配置: GlobalData.appBaseUrl（当前指向 https://dev.yixiong-tech.com:8081，切换环境直接修改该字段）

API 响应格式: ApiResponse<T>

• 成功: code == "00000"
• 失败: 检查 msg 字段

网络客户端: ApiClient（Retrofit 单例） API 接口: ApiService

4. 全局配置

GlobalData 包含关键配置：

• arrayCross = 2（横排数量）
• arrayVertical = 11（竖排数量）
• arrayMode = 0（0=竖直排列, 1=水平排列）
• ArcSoft SDK 配置：appId, sdkKey, activeKey

SharedPreferences 键: 见 GlobalKey

应用启动流程

1. MyApp.onCreate() - 初始化日志、崩溃处理、全局数据
2. DeviceInitActivity - 加载人脸缓存、获取设备配置
3. LoginByFaceActivity - 人脸识别登录
4. MainActivity - 主界面（Fragment 容器）

代码规范

命名约定

• Activity: XxxActivity
• Fragment: XxxFragment
• ViewModel: XxxViewModel
• Repository: XxxRepository
• 工具类: XxxUtil 或 XxxHelper

基类使用

• Activity 继承 BaseActivity<VB>（VB 为 ViewBinding 类型）
• Fragment 继承 BaseFragment<VB>
• ViewModel 继承 BaseViewModel
• Repository 继承 BaseRepository

异步操作

• 使用 Kotlin Coroutines（viewModelScope.launch）
• PLC 操作使用回调（PlcCallback<T>）
• 网络请求在 ViewModel 中调用 launchRequest { }

重要注意事项

NDK 架构

项目仅支持 armeabi-v7a（32位 ARM），不支持 arm64-v8a。这是因为 PLC SDK 和 ArcSoft SDK 的限制。

硬件依赖

• 需要串口通信支持（android-serialport）
• 需要摄像头权限（人脸识别）
• 需要网络权限（API 调用）

调试配置

• 签名密钥: swkey.jks（密码: 123456）
• 允许明文 HTTP 流量（network_security_config.xml）
• ProGuard 混淆已禁用

lib_face 依赖

app 模块依赖 lib_face 时，排除了 android-serialport 依赖，因为 app 模块自己引入了该库。

常用工具类

• SpTool - SharedPreferences 操作
• Debouncer - 防抖
• QRCodeUtil - 二维码生成
• PermissionHelper - 权限管理
• FragmentHelper - Fragment 管理

Git 分支策略

• 主分支: main
• 功能分支命名形如 main_<功能>_<YYMMDD>（如 main_吐盘机_260327）

最近开发重点

根据最近的提交记录，项目正在进行以下工作：

1. 会员版（已修改包名）
2. 绑定/解绑餐盘功能
3. 人脸识别登录（含手机号密码登录）

API 调用示例

// 在 ViewModel 中
launchRequest(
    request = { repository.someApiCall(params) },
    onSuccess = { data ->
        // 处理成功响应
    },
    onError = { code, msg ->
        // 处理错误
    }
)

串口开柜示例

// 串口操作为异步回调（SerialPortManager.SendCallback）
SerialApi.openPlate(boxNumber, new SerialPortManager.SendCallback() {
    @Override
    public void onSuccess() {
        // 开柜命令发送成功
    }

    @Override
    public void onFail(Exception e) {
        // 开柜失败
    }
});