mazengfei
d53ea8f798
- 新增 ApiServiceV2 接口，支持人脸缓存、增量数据、设备配置等接口 - ApiClient 中新增 apiServiceV2 对象，复用 Retrofit 实例，调整超时时间至60秒 - DeviceInitActivity 改用 netViewModelV2 进行人脸缓存全量拉取及设备配置读取 - BaseActivity 新增对人脸增量同步接口调用，调用成功后刷新本地识别缓存 - BaseActivity 新增清空本地人脸库功能，异步清理数据库并刷新识别缓存 - FaceApi 增加清空本地人脸库接口，重写数据库操作逻辑 - 升级 lib_face 模块 Room 数据库版本，新增字段以支持多标识人脸实体扩展 - FaceEntity 实体扩展会员编号、用户ID、人脸ID、会员标识、更新时间等字段 - FaceDao 新增按人脸ID查询和删除接口，支持多重人脸数据操作 - 优化网络层 OkHttpClient 配置，简化拦截器写法及日志级别判断 - 升级 lib_face 模块支持 arm64-v8a 架构，增强兼容性 - 规范模块间依赖关系，统一版本管理及包路径声明 - 完善 CLAUDE.md 文档，补充项目架构、模块划分与开发流程说明
199 lines
5.7 KiB
Markdown
199 lines
5.7 KiB
Markdown
# 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) {
|
||
// 开柜失败
|
||
}
|
||
});
|
||
```
|