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 文档，补充项目架构、模块划分与开发流程说明
55 lines
3.5 KiB
Markdown
55 lines
3.5 KiB
Markdown
# Repository Guidelines
|
||
|
||
本项目 **SmartPlateCabinet / SmartTakePlate（发盘机）** 是基于 Android 的智能餐盘柜控制系统，集成人脸识别（ArcFace SDK）与 PLC 硬件控制。本文档为贡献者提供统一规范。
|
||
|
||
## 项目结构与模块组织
|
||
|
||
多模块 Gradle 工程，模块定义于 `settings.gradle.kts`：
|
||
|
||
- `app/` — 主应用模块，命名空间 `com.sw.platecabinet`（applicationId `com.sw.take.plate`）。源码位于 `app/src/main/java/com/sw/platecabinet/`，按职责分包：`activity`、`fragment`、`viewmodel`、`repository`、`network`（`api`/`interceptor`/`task`）、`model`（`request`/`response`）、`socket`、`utils`（PLC 实现在 `utils/mego`）、`adapter`、`dialog`、`view`、`receiver`、`ext`。
|
||
- `lib_face/` — 人脸识别库模块（`com.sw.plate.utils.arcface`），封装 ArcFace SDK，含 `camera`、`face`、`facedb`（Room 持久化）、`faceserver`、`viewmodel` 等。
|
||
- 依赖版本统一管理于 `gradle/libs.versions.toml`；本地 AAR 依赖置于 `app/libs/`（如 PLC SDK `plc_aar_104.aar`）。
|
||
- 测试目录：`app/src/test`（单元测试）、`app/src/androidTest`（仪器测试）。
|
||
|
||
## 构建、测试与开发命令
|
||
|
||
```bash
|
||
./gradlew assembleDebug # 编译 Debug APK
|
||
./gradlew installDebug # 安装到已连接设备
|
||
./gradlew clean # 清理构建产物
|
||
./gradlew :app:test # 运行单元测试
|
||
./gradlew :app:connectedAndroidTest # 运行仪器测试（需连接设备）
|
||
```
|
||
|
||
修改 Kotlin/Java 或资源后，须运行 `./gradlew assembleDebug` 验证编译通过。
|
||
|
||
## 编码规范与命名约定
|
||
|
||
- 语言：Kotlin 优先，Java 仅限历史代码维护；JVM target 11。
|
||
- 架构：MVVM。Activity 继承 `BaseActivity<VB>`，Fragment 继承 `BaseFragment<VB>`，ViewModel 继承 `BaseViewModel`，Repository 继承 `BaseRepository`。
|
||
- 命名：`XxxActivity` / `XxxFragment` / `XxxViewModel` / `XxxRepository`；工具类 `XxxUtil` 或 `XxxHelper`。
|
||
- 异步：协程（`viewModelScope.launch`）；PLC 操作走回调 `PlcCallback<T>`；网络请求在 ViewModel 内用 `launchRequest { }`。
|
||
- 资源：布局 `activity_*` / `fragment_*`，字符串禁止硬编码到布局；依赖版本禁止硬编码于 `build.gradle.kts`，统一使用版本目录。
|
||
- 注释统一使用简体中文；标识符保持英文。
|
||
|
||
## 测试指南
|
||
|
||
框架：JUnit 4 + AndroidX Test（Espresso）。业务逻辑优先在 `src/test` 编写单元测试；涉及 UI 或硬件交互的改动，须说明是否需仪器测试。测试类置于对应包路径下。
|
||
|
||
## 提交与分支约定
|
||
|
||
提交信息采用 **Conventional Commits（中文描述）**：`<type>(<scope>): <中文描述>`。常见 type：`feat`、`fix`、`refactor`；scope 如 `login`、`plc`、`face`、`ui`、`build`、`api`、`base`。示例：
|
||
|
||
```
|
||
feat(plc): 添加餐盘平台复位功能和无餐盘提示界面
|
||
fix(login): 修复人脸识别登录界面返回时串口连接超时问题
|
||
```
|
||
|
||
分支：`main` 为基础分支；功能分支命名形如 `main_<功能>_<YYMMDD>`（如 `main_吐盘机_260701_5.0`）。合并请求需描述变更内容、关联问题；改动 UI 或硬件交互时附截图或验证说明。
|
||
|
||
## 配置与安全提示
|
||
|
||
- 签名：Debug 使用 `app/swkey.jks`（见 `app/build.gradle.kts`）。
|
||
- 明文 HTTP 流量已通过 `network_security_config.xml` 放行，请勿在受控环境外泄露配置。
|
||
- `app` 依赖 `lib_face` 时已排除其中的 `android-serialport`，由 app 自行引入，避免重复依赖。
|
||
- ABI 过滤：`armeabi-v7a`、`arm64-v8a`。 |