CheckShot - Android 图片检查与拼图工具

CheckShot 是一个面向 Android 的图片处理与检查工具，包含水印处理、拼图合成、以及丰富的设置能力，配合 AirTest 自动化测试用例，帮助实现端到端的图像工作流。

核心功能

• 相机模块

  • 使用 CameraX 库实现拍照、自动/手动对焦、曝光调节
  • 拍摄后自动叠加水印（时间+地点）

• 水印处理

  • 时间水印：拍摄后在左下角叠加时间戳，格式固定为 "yyyy年-MM月-dd日 HH:mm:ss"
  • 地点水印：优先通过 Geocoder 联网解析地址，失败时回落显示经纬度。可在设置中配置校准方式
  • 样式：提供三种预设样式（默认/简约/醒目），并可在设置中预览和应用

• 多图拼图（合成）模块

  • 布局规则：支持 2x2 和 3x3 两种网格布局，图片自动缩放裁剪以适配网格
  • 核心能力：图片拼接、模板化布局编辑（替换/删除图片）、合成质量控制（分辨率/清晰度）
  • 交互：支持替换网格中的图片、删除图片、添加新图片、设置合成质量

• 文字编辑模块

  • 在合成图片的顶部（标题）和底部（内容）添加带矩形背景的文字说明
  • 支持智能换行，自动适应指定宽度
  • 提供预设文字样式选择

• 图片管理

  • 本地存储、分类管理、预览、导出/分享
  • 遵循分区存储规则，通过 MediaStore 保存至系统相册
  • 文件命名规则：巡检报告_{巡检主题}_{生成时间}.jpg

• 设置与通用配置

  • 水印设置、合成设置、通用设置、关于等配置项，均可通过设置界面调整

• 测试与自动化

  • 集成 AirTest 测试用例，覆盖水印、相册、拼图、设置等场景，便于回归验证

---

通用拼图布局组件技术规格

1. 逻辑结构

采用“上-中-下”三段式布局：

┌─────────────────────────┐
│      标题区 (Title)     │  高度自适应，支持 1 行文本
├─────────────────────────┤
│                         │
│      图片网格区         │  2x2 或 3x3 栅格布局
│      (Grid Area)        │
│                         │
├─────────────────────────┤
│    底部文字区 (Text)    │  200dp 高度，包含标题+内容
└─────────────────────────┘

2. 核心布局参数化

参数	说明	当前值
Grid_Columns	列数	2 或 3
Grid_Rows	行数	2 或 3
S	单元格间距	4dp
P	容器内边距	16dp

布局模板自动匹配：根据图片数量自动选择最接近的栅格模板。

3. 内容渲染规则

• 标题区：位于顶部，高度自适应，支持 1 行文本
• 图片网格区：位于栅格正下方，由图片组成
• 内容区：位于底部，由 Title（加粗）和 Content（常规）组成

---

4. 缩放算法规格

等比缩放 (Proportional Scaling)

• 锁定原始宽高比，严禁 X 或 Y 轴独立拉伸
• 计算缩放比例：k = max(Wt / W_orig, Ht / H_orig)

其中：

• Wt = 目标单元格宽度（物理像素）
• Ht = 目标单元格高度（物理像素）
• W_orig = 原始图片宽度
• H_orig = 原始图片高度

填充模式

• Aspect Fill：图片须完全覆盖单元格区域，不允许出现留白（Gap-free）

采样策略

• 下采样 (Downsampling)：针对大图缩小，采用双线性（Bilinear）过滤，避免出现锯齿或摩尔纹

对齐规则

• Center Aligned：初始加载时，图片几何中心与单元格几何中心重合

分辨率限制

• Max DPI 限制：缩小后的图片逻辑像素密度不低于 320dpi，确保在高分屏下的视觉清晰度

---

5. 布局通用适配规则

1. 系统根据当前选定的布局模板（2x2 或 3x3），计算出单个单元格的目标物理像素 (Wt, Ht)
2. 原始图片输入后，自动计算缩放比例 k = max(Wt/W_orig, Ht/H_orig)
3. 图片按 k 倍数进行等比缩小
4. 缩小后的图片根据单元格中心进行溢出裁切，确保视觉上的严丝合缝

---

架构与实现要点

• Watermark：时间文本来自系统时间，地点文本通过 LocationHelper/Geocoder 获取。
• Puzzle：通过 Bitmap 拼接与 Canvas/Matrix 实现多种布局，支持图片替换、删除与质量控制。
• Settings：使用 DataStore 保存用户偏好。

快速开始

构建与运行

• 构建调试 APK：./gradlew assembleDebug
• 构建发布 APK：./gradlew assembleRelease
• 在设备/模拟器上安装：adb install -r app/build/outputs/apk/debug/app-debug.apk

发布签名配置

本项目已配置自动签名，使用 app/my-release.jks 密钥库：

1. 生成签名密钥（已配置）：

   keytool -genkeypair -v -alias my-key -keyalg RSA -keysize 2048 -validity 10000 -keystore my-release.jks
   

2. 签名配置：

   • 在 app/build.gradle.kts 中配置了 signingConfigs
   • 签名密码存储在 gradle.properties 中（不提交到版本控制）

3. 构建签名 APK：

   ./gradlew assembleRelease
   

   构建产物：app/build/outputs/apk/release/app-release.apk

AirTest 测试

• 安装依赖：

  pip install airtest pocoui
  

• 运行测试用例：

  # 确保设备已连接（模拟器或真机）
  adb devices
  
  # 运行拼图测试
  airtest run test/airtest/test_puzzle_merge.py --device Android:///
  

• 手动测试脚本：

  python test_android.py  # 基础功能测试
  python test_camera.py   # 相机功能测试
  python test_gallery.py  # 相册功能测试
  

项目结构与升级

• 主要代码位于：
  • app/src/main/... 业务代码与 UI 组件
  • app/src/test/... 单元测试
  • test/airtest/... AirTest 的 UI 测试用例
• README 作为版本演进的记录，后续变更请同步更新。

设置选项说明

水印设置

• 水印样式：默认样式、简约样式、醒目样式
• 地点校准方式：
  • 联网查询校准（默认）
  • 经纬度+距离校准

合成与文字设置

• 默认合成布局：2x2 网格、3x3 网格
• 合成图片质量：高清（95%）、标准（85%）、流畅（70%）
• 默认文字样式：分别为标题和内容提供预设样式选择

通用设置

• 默认巡检主题：预设默认的巡检主题名称
• 巡检员信息：填写姓名或工号（扩展项）
• 关于：显示应用版本号、开发者信息

持续集成与发布

• 建议在 CI 中执行：编译、单元测试、AirTest 测试并在通过后打包发行版。

联系与贡献

• 如需进一步定制文档结构，或需要将某些部分拆分为单独的开发指南，请告知偏好。