凭证管理

凭证是用户开锁的"钥匙"，包括电子钥匙、密码、卡片、指纹、人脸、掌静脉、遥控器等。

凭证类型

类型	标识	说明
电子钥匙	KEY	APP/小程序蓝牙开锁
密码	PASSWORD	用户设置的固定密码
离线密码	OFFLINE_PASSWORD	算法生成，无需联网验证
卡片	CARD	IC卡/NFC卡
指纹	FINGERPRINT	指纹识别
人脸	FACE	3D人脸识别
掌静脉	PALM_VEIN	掌静脉识别
遥控器	REMOTE	蓝牙遥控器

凭证与用户的关系

核心规则：每个凭证必须归属于一个用户。

• 凭证不能独立存在，必须关联到用户
• 删除用户时，其所有凭证一并删除
• 一个用户可以拥有多个凭证，也可以没有凭证

凭证归属

添加凭证时有两种方式指定归属：

方式	操作	结果
指定用户	设置 user_id	凭证归属指定用户
自动创建	不指定用户	自动创建新用户，凭证归属新用户

典型场景

场景	操作	结果
APP 为自己添加指纹	指定 user_id = 当前用户	指纹归属当前用户
APP 为家人添加指纹	指定 user_id = 家人用户ID	指纹归属家人用户
门锁屏幕添加指纹	不指定用户	自动创建新用户

凭证归属与事件追溯

凭证一旦创建，其归属用户无法修改。当使用该凭证开锁时，事件记录会关联到凭证归属的用户。

如果在门锁屏幕上添加凭证时选择了"新建用户"，后续该凭证的所有开锁记录都会关联到这个自动创建的用户，而非实际使用者的账号。

如需将凭证关联到正确的用户，建议删除该凭证后重新录入，并在录入时指定正确的归属用户。

通用属性

所有凭证类型都具有以下通用属性：

属性	说明
credential_id	凭证ID（锁内唯一）
type	凭证类型
user_id	归属用户ID
created_by	创建者用户ID
created_at	创建时间
validity	有效期
use_count_limit	使用次数限制（0=不限）
use_count	已使用次数
label	凭证标签（如"右手拇指"）
is_duress	是否胁迫凭证

详细数据结构参见 数据结构。

通用操作

每个凭证模块都提供以下标准操作：

操作	指令模式	说明
列表查询	List*	获取凭证列表
详情查询	Get*	获取单个凭证详情
添加	Add* / Start*Enroll	添加凭证
更新	Update*	更新凭证属性
删除	Delete*	删除单个凭证
清空	Clear*	清空该类型所有凭证

生物特征凭证

指纹、人脸、掌静脉等生物特征凭证的添加使用 Start*Enroll 启动录入流程，录入过程中设备会推送进度通知。生物特征数据无法修改，Update* 仅能更新标签、有效期等通用属性。

胁迫凭证

胁迫凭证是一种安全机制：使用胁迫凭证开锁时，门正常打开，同时静默触发报警。

• 所有凭证类型都支持设置为胁迫凭证
• 典型场景：录入两个指纹，食指正常开锁，小指为胁迫指纹

胁迫凭证使用建议

• 建议为每个用户设置至少一个胁迫凭证
• 人脸通常不适合作为胁迫凭证（无法主动选择使用）
• 胁迫报警需配合后台服务实现通知功能

凭证模块

模块	指令区块	说明
电子钥匙	0x04xx	APP/小程序蓝牙开锁凭证
密码管理	0x05xx	自定义密码
离线密码	-	算法生成，无指令交互
卡片管理	0x06xx	IC卡/NFC卡
指纹管理	0x07xx	指纹识别
人脸管理	0x08xx	3D人脸识别
掌静脉管理	0x09xx	掌静脉识别
遥控器管理	0x0Axx	蓝牙遥控器