220 lines
7.3 KiB
Markdown
220 lines
7.3 KiB
Markdown
# KIOSK 自助照片打印
|
||
|
||
KIOSK 是一套运行在 Android 终端上的自助照片打印应用，面向线下自助设备场景。应用负责设备绑定、照片获取与裁剪、打印任务处理、打印机状态上报、海报展示以及在线升级等功能。
|
||
|
||
当前应用名称为“自助照片打印”，包名为 `com.yzx.kiosk`。
|
||
|
||
## 主要功能
|
||
|
||
- 上传、选择、裁剪并打印照片
|
||
- 扫码取片及隐私打印任务处理
|
||
- 人脸识别与照片检索
|
||
- DNP RX1、QW410 照片打印机接入
|
||
- WebSocket 长连接、任务接收和设备心跳
|
||
- 打印机状态、纸张余量和打印记录管理
|
||
- 海报、视频及直播内容展示
|
||
- APK 在线检查、下载和安装更新
|
||
- 开机启动及应用更新后自动恢复
|
||
|
||
## 技术栈
|
||
|
||
- Kotlin 2.1.10
|
||
- Jetpack Compose + ViewBinding
|
||
- Android Gradle Plugin 8.10.0
|
||
- Gradle 8.11.1
|
||
- Hilt、KSP、Room、Retrofit、OkHttp、MMKV
|
||
- CameraX、ML Kit、ZXing
|
||
- 阿里云 OSS、语音合成、高德地图
|
||
- DNP 本地打印 SDK
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 要求 |
|
||
| --- | --- |
|
||
| Android Studio | 支持 AGP 8.10.0 的较新稳定版本 |
|
||
| JDK | JDK 17，推荐直接使用 Android Studio 内置 JBR |
|
||
| Android SDK | Compile SDK 36 / Target SDK 36 |
|
||
| 最低系统版本 | Android 8.0（API 26） |
|
||
| 调试设备 | 开启开发者选项和 USB 调试的 Android 真机 |
|
||
| 打印设备 | DNP RX1 或 QW410，打印功能需要对应设备及驱动环境 |
|
||
|
||
项目依赖 Google、Maven Central、华为、JitPack 和阿里云 Maven 仓库，首次同步需要能够访问这些仓库。
|
||
|
||
## 获取工程
|
||
|
||
```bash
|
||
git clone ssh://git@gitea.zhifly.cn:2222/lujiuyin/kiosk.git
|
||
cd kiosk
|
||
git checkout main
|
||
```
|
||
|
||
仓库使用 SSH 端口 `2222`。拉取前请确认本机 SSH 公钥已添加到 Gitea 账号。
|
||
|
||
## 本地依赖
|
||
|
||
打印、地图和语音能力依赖 `app/libs/` 中的本地 AAR、JAR 及原生库。至少应确认下列文件存在：
|
||
|
||
```text
|
||
app/libs/
|
||
├── dnpext.aar
|
||
├── dnpphotocolorcnv-1.2.aar
|
||
├── dnpphotoprintlib-1.2.aar
|
||
├── AMap3DMap_10.1.600_AMapSearch_9.7.4_AMapLocation_6.5.1_20251020.jar
|
||
├── nuisdk-release.aar
|
||
├── fastjson-1.1.46.android.jar
|
||
├── arm64-v8a/
|
||
└── armeabi-v7a/
|
||
```
|
||
|
||
缺少这些文件时，Gradle 同步可能失败，或者应用能够安装但对应硬件能力无法工作。
|
||
|
||
## 在 Android Studio 中运行
|
||
|
||
1. 使用 Android Studio 打开工程根目录。
|
||
2. 将 Gradle JDK 设置为 Android Studio 内置 JBR（JDK 17）。
|
||
3. 等待 Gradle Sync 完成；Android Studio 会自动生成包含 SDK 路径的 `local.properties`。
|
||
4. 使用数据线连接真机，并在设备上允许 USB 调试。
|
||
5. 在设备选择器中选择目标真机，运行 `app` 的 `debug` 构建。
|
||
6. 首次启动时按系统提示授予相机、照片、定位和安装未知应用等业务所需权限。
|
||
|
||
可以用下面的命令确认设备已连接：
|
||
|
||
```bash
|
||
adb devices
|
||
```
|
||
|
||
设备状态应为 `device`。如果显示 `unauthorized`，请解锁设备并确认 USB 调试授权弹窗。
|
||
|
||
## 命令行构建与安装
|
||
|
||
仓库当前的 `gradlew` 使用 CRLF 换行且没有执行权限。在 macOS 或 Linux 首次使用时，先执行：
|
||
|
||
```bash
|
||
perl -pi -e 's/\r$//' gradlew
|
||
chmod +x gradlew
|
||
```
|
||
|
||
构建 Debug APK：
|
||
|
||
```bash
|
||
./gradlew :app:assembleDebug
|
||
```
|
||
|
||
安装到已连接的真机：
|
||
|
||
```bash
|
||
./gradlew :app:installDebug
|
||
```
|
||
|
||
启动应用：
|
||
|
||
```bash
|
||
adb shell am start -n com.yzx.kiosk/.SplashActivity
|
||
```
|
||
|
||
APK 输出目录为：
|
||
|
||
```text
|
||
app/build/outputs/apk/debug/
|
||
app/build/outputs/apk/release/
|
||
```
|
||
|
||
APK 文件名会自动包含应用名、版本号、版本代码、构建类型和构建时间，例如：
|
||
|
||
```text
|
||
照片打印机_1.1.1_21_debug_yyyyMMdd_HHmm.apk
|
||
```
|
||
|
||
## 构建环境
|
||
|
||
| 构建类型 | 后端环境 | 调试 | 代码压缩 |
|
||
| --- | --- | --- | --- |
|
||
| `debug` | 测试环境 `api-test.zhifly.cn` | 开启 | 关闭 |
|
||
| `release` | 正式环境 `api.zhifly.cn` | 关闭 | 关闭 |
|
||
|
||
请勿使用 Release 包连接测试设备随意操作，Release 会访问正式接口并连接正式 WebSocket。
|
||
|
||
### Release 签名警告
|
||
|
||
当前工程存在发布阻断问题：
|
||
|
||
- Debug 和 Release 的 keystore 路径及口令直接写在 `app/build.gradle.kts` 中。
|
||
- `release` 构建当前实际选择的是 Debug 签名，而不是已声明的 Release 签名。
|
||
- keystore 已存在于工程目录中，泄露后可能被用于签署可覆盖安装的 APK。
|
||
|
||
在正式发布前，必须将签名信息迁移到本机安全配置或 CI Secret，修正 Release 签名配置，并根据已发布版本情况评估密钥轮换。不要在 README、提交记录或聊天中传播 keystore 口令。
|
||
|
||
## 真机和打印机检查
|
||
|
||
运行完整业务前建议依次确认：
|
||
|
||
1. 真机系统版本不低于 Android 8.0。
|
||
2. 网络能够访问对应的测试或正式接口。
|
||
3. 设备已完成业务侧的终端绑定和 Token 配置。
|
||
4. DNP 打印机已上电、装纸并与终端正确连接。
|
||
5. 应用内打印机管理页能够识别设备，状态不是离线。
|
||
6. 使用测试照片完成一次打印，并核对打印结果、纸张余量和服务端任务状态。
|
||
|
||
RX1 使用约 `1840 × 1240` 的横向打印画布，QW410 使用约 `1266 × 1836` 的纵向打印画布。应用会根据识别到的打印机型号处理图片方向和缩放。
|
||
|
||
## 常用质量检查
|
||
|
||
```bash
|
||
# 编译 Debug
|
||
./gradlew :app:assembleDebug
|
||
|
||
# JVM 单元测试
|
||
./gradlew :app:testDebugUnitTest
|
||
|
||
# Android Lint
|
||
./gradlew :app:lintDebug
|
||
|
||
# 需要已连接真机或模拟器
|
||
./gradlew :app:connectedDebugAndroidTest
|
||
```
|
||
|
||
目前工程自动化测试覆盖较少，Lint 也仍有待处理的问题。发布前不要只以“能够编译安装”作为质量判断依据。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
KIOSK/
|
||
├── app/
|
||
│ ├── libs/ # 打印、地图、语音及原生依赖
|
||
│ ├── src/main/java/com/yzx/kiosk/
|
||
│ │ ├── datastore/ # 本地状态与配置
|
||
│ │ ├── navigation/ # Compose 页面导航
|
||
│ │ ├── network/ # 接口、数据库和数据仓库
|
||
│ │ ├── priter/ # 打印机接入（历史目录名）
|
||
│ │ ├── ui/ # 页面和 ViewModel
|
||
│ │ ├── utils/ # 上传、下载、更新等工具
|
||
│ │ └── websocket/ # 长连接及打印任务
|
||
│ └── build.gradle.kts # Android、构建类型和签名配置
|
||
├── docs/
|
||
│ └── 工程代码审查报告.md
|
||
├── gradle/libs.versions.toml # 依赖版本目录
|
||
└── settings.gradle.kts
|
||
```
|
||
|
||
`priter` 是工程中现有的历史目录名，并非 README 拼写错误；重命名时需要同步修改包名和引用。
|
||
|
||
## 已知问题与发布前检查
|
||
|
||
详细问题和修复建议见 [工程代码审查报告](docs/工程代码审查报告.md)。当前需要优先处理：
|
||
|
||
- Release 签名与密钥管理
|
||
- 打印最终结果的可靠判定
|
||
- 隐私政策同意流程和敏感数据保护
|
||
- WebSocket、上传下载与状态通知的并发可靠性
|
||
- APK 更新文件的完整性及签名校验
|
||
- Room 数据迁移、自动化测试和 Lint
|
||
|
||
## 版本信息
|
||
|
||
- Version Name：`1.1.1`
|
||
- Version Code：`21`
|
||
- Application ID：`com.yzx.kiosk`
|
||
- Root Project：`KIOSK`
|
||
|
||
版本号以 `app/build.gradle.kts` 中的配置为准。
|