电子钥匙

电子钥匙是用于 APP/小程序蓝牙开锁的凭证，用户需拥有电子钥匙才能使用蓝牙开锁功能。

与其他凭证的区别

特性	电子钥匙	其他凭证
使用方式	APP/小程序操作	门锁端直接验证
网络要求	需蓝牙连接	无需网络
典型场景	远程授权、临时访客	日常使用

电子钥匙的特殊性

电子钥匙是唯一一种纯软件凭证，不需要在门锁端录入任何数据。添加电子钥匙时，门锁只需存储凭证元数据（有效期、权限等），验证时通过蓝牙协议的会话鉴权完成身份确认。

指令列表

指令码	名称	方向	说明
0x0400	ListKeys	APP → 设备	获取电子钥匙列表
0x0401	GetKey	APP → 设备	获取电子钥匙详情
0x0402	AddKey	APP → 设备	添加电子钥匙
0x0403	UpdateKey	APP → 设备	更新电子钥匙
0x0404	DeleteKey	APP → 设备	删除电子钥匙
0x0405	ClearKeys	APP → 设备	清空所有电子钥匙

数据结构

message Key {
  uint32 credential_id = 1;    // 凭证ID（锁内唯一）
  uint32 user_id = 2;          // 归属用户ID
  uint32 created_by = 3;       // 创建者用户ID
  uint64 created_at = 4;       // 创建时间（UNIX毫秒时间戳）
  ValidityPeriod validity = 5; // 有效期
  uint32 use_count_limit = 6;  // 使用次数限制（0=不限）
  uint32 use_count = 7;        // 已使用次数
  string label = 8;            // 标签（如"张三的钥匙"）
  bool is_duress = 9;          // 是否胁迫凭证
}

字段	类型	说明
credential_id	uint32	凭证ID，锁内唯一标识
user_id	uint32	归属用户ID
created_by	uint32	创建者用户ID
created_at	uint64	创建时间（UNIX毫秒时间戳）
validity	ValidityPeriod	有效期，详见 凭证期限
use_count_limit	uint32	使用次数限制，0 表示不限制
use_count	uint32	已使用次数
label	string	用户自定义标签
is_duress	bool	是否胁迫凭证

ListKeys - 获取电子钥匙列表

指令码: 0x0400

ListKeysReq

message ListKeysReq {
  optional uint32 user_id = 1;  // 按用户ID筛选（不指定则返回所有）
}

ListKeysResp

message ListKeysResp {
  uint32 code = 1;
  string message = 2;
  repeated Key keys = 3;  // 电子钥匙列表
}

GetKey - 获取电子钥匙详情

指令码: 0x0401

GetKeyReq

message GetKeyReq {
  uint32 credential_id = 1;  // 凭证ID
}

GetKeyResp

message GetKeyResp {
  uint32 code = 1;
  string message = 2;
  Key key = 3;  // 电子钥匙详情
}

AddKey - 添加电子钥匙

指令码: 0x0402

AddKeyReq

message AddKeyReq {
  optional uint32 user_id = 1;          // 归属用户ID（不指定则自动创建用户）
  optional ValidityPeriod validity = 2; // 有效期
  optional uint32 use_count_limit = 3;  // 使用次数限制
  optional string label = 4;            // 标签
  optional bool is_duress = 5;          // 是否胁迫凭证
}

字段	必填	说明
user_id	否	不指定时自动创建新用户
validity	否	不指定时永久有效
use_count_limit	否	默认 0（不限制）
label	否	默认空字符串
is_duress	否	默认 false

AddKeyResp

message AddKeyResp {
  uint32 code = 1;
  string message = 2;
  uint32 credential_id = 3;  // 新建的凭证ID
  uint32 user_id = 4;        // 归属用户ID（自动创建时返回新用户ID）
}

UpdateKey - 更新电子钥匙

指令码: 0x0403

部分更新

仅更新请求中包含的字段，未包含的字段保持不变。

UpdateKeyReq

message UpdateKeyReq {
  uint32 credential_id = 1;             // 凭证ID（必填）
  optional ValidityPeriod validity = 2; // 有效期
  optional uint32 use_count_limit = 3;  // 使用次数限制
  optional string label = 4;            // 标签
  optional bool is_duress = 5;          // 是否胁迫凭证
}

UpdateKeyResp

message UpdateKeyResp {
  uint32 code = 1;
  string message = 2;
}

DeleteKey - 删除电子钥匙

指令码: 0x0404

DeleteKeyReq

message DeleteKeyReq {
  uint32 credential_id = 1;  // 凭证ID
}

DeleteKeyResp

message DeleteKeyResp {
  uint32 code = 1;
  string message = 2;
}

ClearKeys - 清空所有电子钥匙

指令码: 0x0405

危险操作

此操作将删除门锁上所有电子钥匙，不可恢复。

ClearKeysReq

message ClearKeysReq {
  // 无参数
}

ClearKeysResp

message ClearKeysResp {
  uint32 code = 1;
  string message = 2;
  uint32 count = 3;  // 删除的数量
}

相关文档

• 凭证管理概述
• 凭证期限
• 授权指令包 - 用于远程授权电子钥匙