协议设计

本文档定义 V2 协议的分类设计和约束规范，后续协议文档编写应遵循此规范。

协议分类

按功能模块

├── 设备管理          # 设备信息、状态、配对
├── 用户与权限        # 用户 CRUD、角色、权限
├── 锁操作            # 开锁、上锁、锁状态
├── 凭证管理          # 密码、卡片、生物特征
│   ├── 电子钥匙
│   ├── 密码
│   ├── 卡片
│   ├── 指纹
│   ├── 人脸
│   ├── 掌静脉
│   └── 遥控器
├── 事件与记录        # 操作日志、报警记录
├── 功能设置          # 门锁参数配置
├── 固件升级          # OTA
└── 配网              # WiFi 配置

按消息方向

方向	说明
Request	APP → 设备，请求执行操作
Response	设备 → APP，操作结果响应
Notify	设备 → APP，主动推送事件
Ack	APP → 设备，确认收到推送

按操作类型

每个模块内的指令遵循 CRUD 语义：

操作	命名规范	说明
查询	Get* / List*	获取单个或列表
创建	Add* / Create*	新增资源
更新	Update* / Set*	修改资源
删除	Delete* / Clear*	删除单个或全部
执行	Do* / 动词	执行动作（如 Unlock）

设计约束

数据约束

1. 禁止 null 值：所有字段必须有明确的值，不允许 null
2. 必填与可选：通过 Protobuf 的 optional 关键字区分，但即使可选字段存在时也不能为 null
3. 默认值：未提供的可选字段使用类型默认值（数值为 0，字符串为空，布尔为 false）

命名约束

类型	风格	示例
指令名	PascalCase	GetDeviceInfo、AddFingerprint
字段名	snake_case	device_id、valid_from
枚举值	UPPER_SNAKE_CASE	ROLE_ADMIN、STATUS_SUCCESS

结构约束

1. 每个指令必须定义 *Req 和 *Resp 两个结构体
2. 推送消息使用 *Notify 后缀
3. 所有响应必须包含 code 和 message 字段

编号约束

1. 同一模块内指令编号连续分配
2. 预留 0x00-0x0F 给模块级通用操作
3. 每个模块预留 20% 空间给未来扩展

文档约束

1. 每个指令独立章节，包含：指令码、名称、描述、请求体、响应体、示例
2. Protobuf 定义与文档同步维护