掌静脉管理

掌静脉识别凭证，通过门锁红外传感器验证开锁。

生物特征凭证

掌静脉是生物特征凭证，原始数据存储在门锁本地，无法导出或修改。UpdatePalmVein 仅能更新标签、有效期等属性，如需修改需删除后重新录入。

指令列表

指令码	名称	方向	说明
0x0900	ListPalmVeins	APP → 设备	获取掌静脉列表
0x0901	GetPalmVein	APP → 设备	获取掌静脉详情
0x0902	StartPalmVeinEnroll	APP → 设备	启动掌静脉录入
0x0903	CancelPalmVeinEnroll	APP → 设备	取消掌静脉录入
0x0904	UpdatePalmVein	APP → 设备	更新掌静脉信息
0x0905	DeletePalmVein	APP → 设备	删除掌静脉
0x0906	ClearPalmVeins	APP → 设备	清空所有掌静脉
0x0980	PalmVeinEnrollProgress	设备 → APP	录入进度通知
0x0981	PalmVeinEnrollResult	设备 → APP	录入结果通知

数据结构

message PalmVein {
  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	是否胁迫凭证

录入流程

掌静脉录入需要用户将手掌对准红外传感器，系统会采集静脉纹路：

StartPalmVeinEnroll - 启动掌静脉录入

指令码: 0x0902

StartPalmVeinEnrollReq

message StartPalmVeinEnrollReq {
  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
}

StartPalmVeinEnrollResp

message StartPalmVeinEnrollResp {
  uint32 code = 1;   // 0=已进入录入模式
  string message = 2;
}

PalmVeinEnrollProgress - 录入进度通知

指令码: 0x0980

方向: 设备 → APP（Notify）

message PalmVeinEnrollProgress {
  uint32 current = 1;   // 当前已完成次数
  uint32 total = 2;     // 总共需要次数
  uint32 quality = 3;   // 本次采集质量（0-100）
  string hint = 4;      // 提示信息（如"请保持手掌稳定"）
}

hint 示例	说明
请将手掌对准传感器	初始提示
请保持手掌稳定	采集中
请稍微移近	距离过远
请稍微移远	距离过近

PalmVeinEnrollResult - 录入结果通知

指令码: 0x0981

方向: 设备 → APP（Notify）

message PalmVeinEnrollResult {
  uint32 code = 1;           // 0=成功
  string message = 2;
  uint32 credential_id = 3;  // 新建的凭证ID（成功时有效）
  uint32 user_id = 4;        // 归属用户ID（成功时有效）
}

其他指令

掌静脉管理的 List、Get、Cancel、Update、Delete、Clear 指令结构与 指纹管理 完全一致，仅将 Fingerprint 替换为 PalmVein，指令码使用 0x09xx 区块。

指令	请求结构	响应结构
ListPalmVeins	ListPalmVeinsReq	ListPalmVeinsResp
GetPalmVein	GetPalmVeinReq	GetPalmVeinResp
CancelPalmVeinEnroll	CancelPalmVeinEnrollReq	CancelPalmVeinEnrollResp
UpdatePalmVein	UpdatePalmVeinReq	UpdatePalmVeinResp
DeletePalmVein	DeletePalmVeinReq	DeletePalmVeinResp
ClearPalmVeins	ClearPalmVeinsReq	ClearPalmVeinsResp

相关文档

• 凭证管理概述
• 指纹管理 - 结构相似，可参考详细字段定义
• 凭证期限