Appearance
数据同步
本文档描述蓝牙门锁的数据同步机制。WiFi 门锁通过 MQTT 实时同步，不存在此问题。
蓝牙门锁采用离线优先架构，所有数据存储在设备本地。APP 通过蓝牙连接时进行数据同步。
架构说明
数据流向：
| 数据类型 | 写入端 | 同步方向 | 同步方式 |
|---|---|---|---|
| 用户、凭证、设置 | 云端/设备 | 云端 → 设备 | APP 连接设备时自动下发 |
| 用户、凭证（本地） | 设备 | 设备 → 云端 | APP 中点击"同步数据" |
| 事件记录 | 设备 | 设备 → 云端 | APP 连接设备时自动上报 |
数据一致性
设备本地的管理操作（如在门锁屏幕录入指纹）不会自动同步到云端。如需云端记录完整数据，请在 APP 中手动点击"同步数据"。
为什么不是双向自动同步？
你可能会问：为什么不让云端和设备都能自由管理，然后自动合并数据？这涉及分布式系统的经典难题。详见 数据同步的难点。
数据版本号
设备为每类数据维护独立的版本号，任意变更时版本号 +1：
| 数据类型 | 版本号字段 | 说明 |
|---|---|---|
| 设备设置 | settings_version | 设置变更时 +1 |
| 用户列表 | users_version | 用户增删改时 +1 |
| 电子钥匙 | keys_version | 该类型凭证增删改时 +1 |
| 密码 | passwords_version | 该类型凭证增删改时 +1 |
| 卡片 | cards_version | 该类型凭证增删改时 +1 |
| 指纹 | fingerprints_version | 该类型凭证增删改时 +1 |
| 人脸 | faces_version | 该类型凭证增删改时 +1 |
| 掌静脉 | palm_veins_version | 该类型凭证增删改时 +1 |
| 遥控器 | remotes_version | 该类型凭证增删改时 +1 |
云端同样为每个设备维护一套版本号。通过对比版本号，可快速判断哪类数据需要同步。
添加设备到云端
将设备添加到 APP 时，执行一次全量上报：
涉及的指令：
| 步骤 | 指令 | 所属模块 |
|---|---|---|
| 获取设备信息 | GetDeviceInfo | 设备管理 |
| 拉取用户 | ListUsers | 用户管理 |
| 拉取凭证 | ListCredentials | 凭证管理（各类型） |
| 拉取事件 | QueryEvents | 事件记录 |
| 获取版本号 | GetDataVersions | 设备管理 |
日常同步
每次 APP 通过蓝牙连接门锁时，执行以下同步操作。
管理数据下发（云端 → 设备）
通过版本号对比，仅下发有变更的数据类型：
同步策略：
| 情况 | 处理 |
|---|---|
| 云端版本 > 设备版本 | 云端数据全量覆盖设备 |
| 云端版本 = 设备版本 | 无需同步 |
| 云端版本 < 设备版本 | 设备有本地变更，不自动处理 |
事件上报（设备 → 云端）
事件记录只增不改不删，使用 last_event_id 增量拉取：
手动同步
用户在 APP 中点击"同步数据"时，将设备数据全量上报云端：
手动同步的作用：将设备本地的变更（如门锁屏幕录入的指纹）同步到云端。
注意事项
- 同步耗时： 手动同步可能需要数秒到数分钟，取决于数据量。APP 应显示同步进度。
- 移除未包含数据： 全量同步时，云端需要移除未包含在设备的所有数据。
用户关联
设备用户与云端账户（手机号）的关联关系仅存储在云端，设备不感知。
关联规则：
| 规则 | 说明 |
|---|---|
| 一对一 | 同一设备上，一个云端账户最多关联一个设备用户 |
| 跨设备 | 一个云端账户可关联不同设备上的多个用户 |
| 可选 | 设备用户可以不关联云端账户 |
| 可变 | 关联关系可随时建立、解除或变更 |
为什么设备不存储关联信息？
保持设备的独立性。设备只管理本地用户和凭证，云端账户体系由云端处理。这样设备可以在不同云平台间迁移，也便于离线使用。