# 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`。