# 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

## 构建与运行

### 构建项目
```bash
./gradlew assembleDebug
```

### 安装到设备
```bash
./gradlew installDebug
```

### 清理构建
```bash
./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 调用示例

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

## 串口开柜示例

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

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