相机记忆系统设计

概述

相机功能所有持久化状态统一存储在 JSON 文件中，方便调试和手动修改。

文件存储位置

文件	路径	用途	说明
camera_memory_schema.json	filesDir/camera/	Schema 定义（默认值 + 可选值 + 说明）	首次运行自动从内置 JSON 生成
camera_memory.json	filesDir/camera/	当前运行时状态	每次状态变更自动写入

文件路径示例：

/data/data/com.codenote/files/camera/camera_memory_schema.json
/data/data/com.codenote/files/camera/camera_memory.json

Schema 结构

schema.json 格式

{
  "defaults": {
    "field_name": default_value,
    ...
  },
  "options": {
    "field_name": [enum_values],
    "field_name": null,
    ...
  },
  "descriptions": {
    "field_name": "field description",
    ...
  }
}

• defaults: 每个字段的默认值
• options: 枚举可选值列表，null 表示连续范围
• descriptions: 字段说明

完整字段定义

字段	默认值	可选值	说明
last_used_tab	"scan"	["scan", "watermark"]	上次使用的相机 Tab
last_lens_facing	0	[0, 1]	上次使用的摄像头：0=后置，1=前置
scan_batch_allowed	false	[true, false]	允许批量扫码，控制预览界面是否可切换到批量模式。持久化保存，冷启动保留
scan_batch_enabled	false	[true, false]	批量扫描模式开关。当前会话有效，冷启动重置为 false
scan_batch_max_count	50	1 ~ 200	批量扫描单次结果数上限
scan_batch_codes	[]	-	批量扫描累积列表，上限由 scan_batch_max_count 指定（默认 50 条），FIFO 截断。持久化保存，切 Tab/杀进程均保留
scan_resolution	"640x480"	["640x480", "1280x720", "1920x1080"]	扫码分辨率
scan_sound_enabled	true	[true, false]	扫码成功播放声音
scan_vibration_enabled	true	[true, false]	扫码成功震动
scan_zoom_ratio	1.0	1.0 ~ 8.0	扫码模式缩放比例
watermark_preset_index	0	[0, 1]	当前选中的水印预设模板索引：0=默认（精简），1=详细
watermark_preset_configs	见下方默认值	-	各预设模板的独立配置，每个 preset 包含完整 WatermarkConfig

预设模板默认值：

预设	字段	默认值
0（默认/精简）	showTime, showLocation, showAddress, showRemark, showSitePhoto	true
0（默认/精简）	showAltitude, showWeather	false
0（默认/精简）	remark	""
1（详细）	showTime, showLocation, showAddress, showAltitude, showWeather, showRemark, showSitePhoto	true
1（详细）	remark	""
watermark_zoom_ratio	1.0	1.0 ~ 8.0
exposure_compensation	0	-24 ~ +24
white_balance_mode	"AUTO"	["AUTO", "CLOUDY", "DAYLIGHT", "INCANDESCENT", "FLUORESCENT"]
color_effect	"NONE"	["NONE", "MONO", "NEGATIVE", "SEPIA"]
auto_torch_enabled	false	[true, false]
photo_resolution	"标准"	["高质量", "标准", "低质量"]

初始化流程

┌────────────────────────────────────┐
│ App 进入相机 → repository.init()    │
│ 检查 schema 文件是否存在？            │
└──────────────┬─────────────────────┘
               │
  ┌────────────┴────────────┐      ┌─────────────────────────────────┐
  │ 存在                    │      │ 不存在 → 从内置字符串生成 schema │
  ↓                         ↓      ↓                                 ↓
┌────────────────────────────────────┐
│ 检查状态文件是否存在且合法？         │
└──────────────┬─────────────────────┘
               │
      ┌────────┴────────┐
      ↓ 存在且合法      ↓ 不存在/损坏
┌──────────────────┐    ┌──────────────────────────────┐
│ 读取状态文件      │    │ 尝试从 DataStore 迁移旧数据      │
│ 更新到 StateFlow │    │ 迁移失败回退到 schema.defaults    │
└──────────────────┘    │ 写入新的状态文件               │
                         └──────────────────────────────┘

业务规则

规则	说明
lastLensFacing	持久化保存
watermarkZoomRatio	持久化保存
watermarkPresetIndex	持久化保存，跨重启恢复
watermarkPresetConfigs	持久化保存，各预设模板独立记忆，切换预设不覆盖字段值
scanBatchCodes	持久化保存，上限由 scanBatchMaxCount 控制（默认 50），FIFO 截断。全部清除 按钮手动清空
scanBatchAllowed	持久化保存，设置页控制，冷启动保留
scanBatchEnabled	当前会话有效，冷启动重置为 false（单次模式）

代码架构

// 数据模型
data class CameraMemorySchema  // schema 结构（defaults + options + descriptions）
data class CameraMemoryState    // 当前状态

// Repository（单例）
class CameraMemoryRepository {
    val memory: StateFlow<CameraMemoryState>

    suspend fun init()          // 初始化（读取文件，schema 不存在则生成）
    suspend fun updateXxx(...)  // 各个字段的更新方法
}

边界约束

Repository 层强制边界检查：

• scanBatchCodes 上限由 scanBatchMaxCount 字段控制（1~200，默认 50），超出 FIFO 截断
• scanBatchMaxCount coerce 1 .. 200
• scanZoomRatio, watermarkZoomRatio coerce 1f .. 8f
• exposureCompensation coerce -24 .. +24

手动操作指南

查看 schema 和状态

adb pull /data/data/com.codenote/files/camera/camera_memory_schema.json ./
adb pull /data/data/com.codenote/files/camera/camera_memory.json ./

修改后推送

# 编辑 camera_memory.json 后
adb push ./camera_memory.json /data/data/com.codenote/files/camera/

恢复默认值

adb shell rm /data/data/com.codenote/files/camera/camera_memory.json

下次启动自动使用默认值重新创建。

新增字段

如需新增状态字段：

1. 在 CameraMemoryState 加字段（带默认值）
2. 在 CameraMemoryRepository 加对应的 updateXxx 方法
3. 修改 CameraMemoryRepository.BUILTIN_SCHEMA_JSON 更新内置默认值
4. 下次启动 schema 文件会保留原有内容，新增字段默认值生效