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 仓库，首次同步需要能够访问这些仓库。
获取工程
git clone ssh://git@gitea.zhifly.cn:2222/lujiuyin/kiosk.git
cd kiosk
git checkout main
仓库使用 SSH 端口 2222。拉取前请确认本机 SSH 公钥已添加到 Gitea 账号。
本地依赖
打印、地图和语音能力依赖 app/libs/ 中的本地 AAR、JAR 及原生库。至少应确认下列文件存在：
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 中运行
- 使用 Android Studio 打开工程根目录。
- 将 Gradle JDK 设置为 Android Studio 内置 JBR（JDK 17）。
- 等待 Gradle Sync 完成；Android Studio 会自动生成包含 SDK 路径的
local.properties。 - 使用数据线连接真机，并在设备上允许 USB 调试。
- 在设备选择器中选择目标真机，运行
app的debug构建。 - 首次启动时按系统提示授予相机、照片、定位和安装未知应用等业务所需权限。
可以用下面的命令确认设备已连接：
adb devices
设备状态应为 device。如果显示 unauthorized，请解锁设备并确认 USB 调试授权弹窗。
命令行构建与安装
仓库当前的 gradlew 使用 CRLF 换行且没有执行权限。在 macOS 或 Linux 首次使用时，先执行：
perl -pi -e 's/\r$//' gradlew
chmod +x gradlew
构建 Debug APK：
./gradlew :app:assembleDebug
安装到已连接的真机：
./gradlew :app:installDebug
启动应用：
adb shell am start -n com.yzx.kiosk/.SplashActivity
APK 输出目录为：
app/build/outputs/apk/debug/
app/build/outputs/apk/release/
APK 文件名会自动包含应用名、版本号、版本代码、构建类型和构建时间，例如：
照片打印机_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 口令。
真机和打印机检查
运行完整业务前建议依次确认：
- 真机系统版本不低于 Android 8.0。
- 网络能够访问对应的测试或正式接口。
- 设备已完成业务侧的终端绑定和 Token 配置。
- DNP 打印机已上电、装纸并与终端正确连接。
- 应用内打印机管理页能够识别设备，状态不是离线。
- 使用测试照片完成一次打印，并核对打印结果、纸张余量和服务端任务状态。
RX1 使用约 1840 × 1240 的横向打印画布，QW410 使用约 1266 × 1836 的纵向打印画布。应用会根据识别到的打印机型号处理图片方向和缩放。
常用质量检查
# 编译 Debug
./gradlew :app:assembleDebug
# JVM 单元测试
./gradlew :app:testDebugUnitTest
# Android Lint
./gradlew :app:lintDebug
# 需要已连接真机或模拟器
./gradlew :app:connectedDebugAndroidTest
目前工程自动化测试覆盖较少，Lint 也仍有待处理的问题。发布前不要只以“能够编译安装”作为质量判断依据。
目录结构
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 拼写错误；重命名时需要同步修改包名和引用。
已知问题与发布前检查
详细问题和修复建议见 工程代码审查报告。当前需要优先处理：
- 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 中的配置为准。