卡片管理

IC卡/NFC卡凭证，通过门锁读卡器刷卡验证开锁。

指令列表

指令码	名称	方向	说明
0x0600	ListCards	APP → 设备	获取卡片列表
0x0601	GetCard	APP → 设备	获取卡片详情
0x0602	AddCard	APP → 设备	添加卡片（进入刷卡模式）
0x0603	UpdateCard	APP → 设备	更新卡片
0x0604	DeleteCard	APP → 设备	删除卡片
0x0605	ClearCards	APP → 设备	清空所有卡片

数据结构

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

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

卡号格式

卡号为二进制数据，展示时通常转换为十六进制字符串，如 A1B2C3D4。

添加流程

添加卡片需要用户在门锁端刷卡，流程如下：

ListCards - 获取卡片列表

指令码: 0x0600

ListCardsReq

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

ListCardsResp

message ListCardsResp {
  uint32 code = 1;
  string message = 2;
  repeated Card cards = 3;  // 卡片列表
}

GetCard - 获取卡片详情

指令码: 0x0601

GetCardReq

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

GetCardResp

message GetCardResp {
  uint32 code = 1;
  string message = 2;
  Card card = 3;  // 卡片详情
}

AddCard - 添加卡片

指令码: 0x0602

调用此指令后，门锁进入刷卡模式等待用户刷卡。

AddCardReq

message AddCardReq {
  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;          // 是否胁迫凭证
  optional uint32 timeout = 6;          // 等待超时（秒），默认30
}

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

AddCardResp

message AddCardResp {
  uint32 code = 1;   // 0=已进入刷卡模式
  string message = 2;
}

CardAddedNotify

刷卡完成后，设备主动推送结果：

message CardAddedNotify {
  uint32 code = 1;           // 0=成功
  string message = 2;
  uint32 credential_id = 3;  // 新建的凭证ID
  uint32 user_id = 4;        // 归属用户ID
  bytes card_number = 5;     // 卡号
}

UpdateCard - 更新卡片

指令码: 0x0603

卡号可更新

通过 UpdateCard 并指定 update_card_number = true，可让用户重新刷卡更换关联的卡片。

UpdateCardReq

message UpdateCardReq {
  uint32 credential_id = 1;             // 凭证ID（必填）
  optional ValidityPeriod validity = 2; // 有效期
  optional uint32 use_count_limit = 3;  // 使用次数限制
  optional string label = 4;            // 标签
  optional bool is_duress = 5;          // 是否胁迫凭证
  optional bool update_card_number = 6; // 是否更新卡号（需重新刷卡）
}

UpdateCardResp

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

DeleteCard - 删除卡片

指令码: 0x0604

DeleteCardReq

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

DeleteCardResp

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

ClearCards - 清空所有卡片

指令码: 0x0605

危险操作

此操作将删除门锁上所有卡片凭证，不可恢复。

ClearCardsReq

message ClearCardsReq {
  // 无参数
}

ClearCardsResp

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

相关文档

• 凭证管理概述
• 凭证期限