升级说明

本文档说明 V2 协议相对于 V1 的主要改进点，以及设计决策背后的考量。

兼容性说明

• V2 协议与 V1 协议不兼容
• 设备需通过固件升级支持 V2
• APP 通过协议版本协商选择 V1 或 V2
• 过渡期内两套协议并行，V1 进入维护模式

1. 废弃"通用扩展指令"

V1 问题：所有扩展功能挤在 0x3030 一个指令下，通过子指令码区分。这导致：

• 协议解析需要两层判断
• 子指令码分配混乱（2, 3, 19, 74...）
• 文档结构被迫嵌套

V2 方案：每个操作都是独立指令，按功能块分配连续编号。

2. 消除模板参数

V1 问题：几乎每个指令都要携带 KeyID、UserID、Token、AuthCodeLen、AuthCode 等重复字段，请求体臃肿。

V2 方案：

• 身份认证信息移至协议头，一次握手，全程有效
• 请求体只包含业务参数
• 鉴权通过会话机制而非逐条签名

3. 加密和鉴权改进

V1 问题：

• 使用复杂、冗余、无用的伪公钥私钥模式
• 子用户拥有锁端最高权限（公钥私钥），存在越权安全隐患

V2 方案：

• 使用单一的门锁权限 Token 进行鉴权和加密
• 授权指令包：可将jwt签名后的"添加电子钥匙"数据包安全地交由近锁端新用户执行，无越权风险
• 使用用户维度凭证，杜绝越权问题

4. Protobuf 序列化

V1 问题：使用自定义的字节拼接方式，字段顺序、长度、对齐都需要手动处理，容易出错。

V2 方案：

• 主推 Protobuf：类型安全、自动生成代码、向前向后兼容
• 兼容 JSON：便于调试和日志
• 兼容原始字节：固件升级等大块数据传输场景

5. 语义化指令标识

V1 问题：

• 指令使用十六进制数值（0x3040），需要查表才知道含义
• 协议文档缺乏命名约束，各端实现的常量名、变量名不一致，难以协作

V2 方案：

• 指令使用语义化名称：GetDeviceInfo、UnlockDoor、AddFingerprint
• 提供指令映射表：0x0101 ↔ GetDeviceInfo
• 请求体和响应体命名规范：GetDeviceInfoReq / GetDeviceInfoResp
• 协议文档层面提供统一命名建议，各端实现保持一致

6. 有序的指令编号

V1 问题：指令码散乱分布（0x3001, 0x3030, 0x30E0, 0x30F4...），无法从编号推断功能类型。

V2 方案：按功能块划分，高字节表示模块，低字节表示具体操作。详见 指令表。

7. 简化时间参数

V1 问题：时间字段使用 UNIX 时间戳，但存在 StartDate、EndDate、StartTime、EndTime 等多个字段，语义重叠。

V2 方案：

• 统一使用 ISO 8601 格式或 UNIX 毫秒时间戳
• 有效期使用单一 ValidityPeriod 结构体封装
• 循环规则使用标准 RRULE 格式（参考 iCalendar）

8. 错误处理标准化

V1 问题：错误码散落在各个指令的响应中，同一含义的错误在不同指令中可能使用不同的值。

V2 方案：

• 响应体统一包含 code + message 字段
• 成功响应 code = 0，错误响应 code > 0
• 各模块自行定义错误码，message 携带人类可读描述