From de7122611d1b4bfcdbc55f36de6b93dd2779871b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B1=89=E7=A7=8B?= <497055328@qq.com> Date: Tue, 4 Aug 2026 14:05:12 +0800 Subject: [PATCH] docs: rewrite project README --- README.md | 311 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 219 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 2ae9309..bfb73e5 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,219 @@ -# ZhiFlyFollow - - - -## Getting started - -To make it easy for you to get started with GitLab, here's a list of recommended next steps. - -Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)! - -## Add your files - -- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files -- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command: - -``` -cd existing_repo -git remote add origin http://47.97.8.103/develop/android/zhiflyfollow.git -git branch -M main -git push -uf origin main -``` - -## Integrate with your tools - -- [ ] [Set up project integrations](http://47.97.8.103/develop/android/zhiflyfollow/-/settings/integrations) - -## Collaborate with your team - -- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/) -- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) -- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically) -- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) -- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html) - -## Test and Deploy - -Use the built-in continuous integration in GitLab. - -- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html) -- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/) -- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html) -- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/) -- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html) - -*** - -# Editing this README - -When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template. - -## Suggestions for a good README -Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information. - -## Name -Choose a self-explaining name for your project. - -## Description -Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors. - -## Badges -On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge. - -## Visuals -Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method. - -## Installation -Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. - -## Usage -Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README. - -## Support -Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc. - -## Roadmap -If you have ideas for releases in the future, it is a good idea to list them in the README. - -## Contributing -State if you are open to contributions and what your requirements are for accepting them. - -For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self. - -You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser. - -## Authors and acknowledgment -Show your appreciation to those who have contributed to the project. - -## License -For open source projects, say how it is licensed. - -## Project status -If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers. +# 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` 中的配置为准。