feat: 初始化星元智灵人脸识别回收箱项目

README.md

@@ -0,0 +1,113 @@
+# 星元智灵
+
+星元智灵是基于智投终端流程改造的竖屏 Android 投放终端应用。项目保留串口投口控制、称重回包、本地备份和服务器上报框架，并集成本地 SeetaFace6 人脸识别与人员录入流程。
+本项目为沃尔核材专用 APP，定位为安卓上位机应用。
+
+## 主要功能
+
+- 首页显示摄像头实时画面并默认进行本地人脸识别，也可通过刷卡或工号进入投放流程。
+- 设置页新增“人脸”Tab，可新增人员、录入或更新人脸、查看人员列表并删除人员。
+- 第二页填写本次投放信息：机台号、人员、生产批次。
+- 机台号支持手动输入，也支持小窗口表格选择；选择后自动联动人员和生产批次。
+- 第三页支持 1/2/3/4 投口模式，可选择单个投口或打开全部投口，页面展示本次机台号、人员、生产批次。
+- 投递页支持关门倒计时、手动关门、一次性延时关门。
+- 结果页仅显示本次投放垃圾类型和重量，不显示奖励。
+- 投口垃圾类型支持镀锡铜、铝合金、废铜、废电线、废铝、废锡和自定义。
+- 投放结果通过预留接口上报服务器，接口未定时使用本地队列和备份兜底。
+- 保留下位机原始称重小数；串口或下位机不可用时不会生成虚假称重结果。
+
+## 工程结构
+
+```text
+app/src/main/
+  AndroidManifest.xml          Android 应用配置
+  assets/www/                  WebView 前端界面
+  assets/face_models/          SeetaFace6 人脸模型
+  assets/brand/                App 图标源图
+  java/                        原生桥、串口、TCP 上报逻辑
+  jniLibs/armeabi-v7a/         串口 native 库
+  res/mipmap-*/                Android launcher 图标
+build.sh                       无 Gradle 手动构建脚本
+```
+
+## 构建要求
+
+- macOS
+- Android SDK，包含：
+  - `platforms/android-28/android.jar`
+  - `build-tools/34.0.0`
+- JDK 8 或兼容 `javac --release 8` 的 JDK
+- Android SDK platform-tools，用于 `adb install`
+
+仓库服务限制单文件最大 50MB，因此约 98MB 的
+`face_recognizer.csta` 被保存为 `model-parts/` 下的四个分片。
+`build.sh` 会在编译前自动校验 SHA-256 并恢复完整模型，无需手动合并。
+
+## 构建 APK
+
+```bash
+bash build.sh
+```
+
+如果只需要恢复或校验人脸模型，可单独执行：
+
+```bash
+bash scripts/restore-face-models.sh
+```
+
+构建产物：
+
+```text
+build/out/xingyuan-zhiling-signed.apk
+```
+
+首次构建时，如果本地没有 debug keystore，脚本会自动生成：
+
+```text
+keystore/zhitou-debug.keystore
+```
+
+该 keystore 不提交到 Git。
+
+## 安装到终端
+
+```bash
+$HOME/Library/Android/sdk/platform-tools/adb install -r build/out/xingyuan-zhiling-signed.apk
+$HOME/Library/Android/sdk/platform-tools/adb shell monkey -p com.xingyuan.zhiling -c android.intent.category.LAUNCHER 1
+```
+
+## 串口说明
+
+默认串口配置：
+
+```text
+path: /dev/ttyS4
+baudRate: 9600
+```
+
+如果首页提示串口故障，请检查串口占用情况以及下位机连接。旧智投 APP 与星元智灵同时运行时，可能会竞争 `/dev/ttyS4`。
+
+## 接口说明
+
+当前机台号、人员、生产批次接口仍为测试数据实现，内置 `WAL-A01`、`WAL-A02`、`WAL-B01`、`WAL-B02` 四台机台供流程测试。后续接入正式接口时，需要替换：
+
+- `app/src/main/java/com/zhitou/terminal/ZhitouBridge.java` 中的 `fetchWorkContext`
+- 前端 `app/src/main/assets/www/app.js` 中的接口解析和兜底逻辑
+
+投放结果上报预留：
+
+- `reportXingyuanDelivery`
+- `reportDeliveryResult`
+- 本地备份：`/sdcard/smart/cache/xingyuan_zhiling_delivery_backup.csv`
+- 本地 JSON 备份：`/sdcard/smart/cache/xingyuan_zhiling_delivery_backup.json`
+- 日志导出：`/sdcard/smart/logs/`
+
+## 版本
+
+当前应用版本：
+
+```text
+versionName: 1.2.18-wal-stability-fix
+versionCode: 107
+package: com.xingyuan.zhiling
+```