kiosk/README.md

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 中运行

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. 首次启动时按系统提示授予相机、照片、定位和安装未知应用等业务所需权限。

可以用下面的命令确认设备已连接：

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	开启	关闭
releaseDebug	正式环境 api.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 的纵向打印画布。应用会根据识别到的打印机型号处理图片方向和缩放。

常用质量检查

# 编译 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 中的配置为准。