Appearance
用户管理
本文档定义用户管理和权限控制相关的指令。
用户角色
用户分为三种角色：
| 角色 | 标识 | 说明 |
|---|---|---|
| 拥有者 | OWNER | 门锁的所有者，拥有最高权限 |
| 管理员 | ADMIN | 被授权的管理员，拥有日常管理权限 |
| 普通用户 | USER | 普通用户，仅有开锁等基本权限 |
权限矩阵
| 权限 | 拥有者 | 管理员 | 普通用户 |
|---|---|---|---|
| 开锁/上锁 | ✓ | ✓ | ✓ |
| 查看自己的凭证 | ✓ | ✓ | ✓ |
| 查看自己的操作记录 | ✓ | ✓ | ✓ |
| 添加/删除用户 | ✓ | ✓ | ✗ |
| 管理任意用户的凭证 | ✓ | ✓ | ✗ |
| 查看全部操作记录 | ✓ | ✓ | ✗ |
| 修改门锁设置 | ✓ | ✗ | ✗ |
| 添加管理员 | ✓ | ✗ | ✗ |
| 删除门锁/恢复出厂 | ✓ | ✗ | ✗ |
拥有者与管理员的区别
管理员可以进行日常的用户和凭证管理，但以下操作仅拥有者可执行：
- 修改门锁设置
- 添加/删除管理员
- 删除门锁/恢复出厂设置
这是一个安全保护机制，防止管理员误操作或恶意操作。
获取用户列表
获取门锁上的所有用户列表。
| 指令码 | 指令名 | 方向 | 鉴权 |
|---|---|---|---|
0x0200 | ListUsers | APP → 设备 | userSecret |
请求参数
无参数。
响应参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | uint32 | 是 | 状态码，0=成功 |
| users | array | 是 | 用户列表 |
| users[].userId | uint32 | 是 | 用户ID |
| users[].role | uint8 | 是 | 用户角色（0=USER, 1=ADMIN, 2=OWNER） |
| users[].nickname | string | 否 | 用户昵称 |
| users[].createdAt | uint64 | 是 | 创建时间（UNIX毫秒时间戳） |
| users[].createdBy | uint32 | 是 | 创建者用户ID |
响应示例
json
{
"code": 0,
"users": [
{
"userId": 1,
"role": 2,
"nickname": "房主",
"createdAt": 1710000000000,
"createdBy": 0
},
{
"userId": 2,
"role": 1,
"nickname": "管家",
"createdAt": 1710100000000,
"createdBy": 1
},
{
"userId": 3,
"role": 0,
"nickname": "租客",
"createdAt": 1710200000000,
"createdBy": 1
}
]
}权限说明
所有用户均可获取用户列表，但普通用户只能看到自己和直接相关的用户信息。
添加用户
创建新用户。创建成功后返回新用户的 userSecret，用于后续该用户的蓝牙通信鉴权。
| 指令码 | 指令名 | 方向 | 鉴权 |
|---|---|---|---|
0x0201 | AddUser | APP → 设备 | userSecret（管理员或拥有者权限） |
执行方式
此指令支持两种执行方式：
| 方式 | 适用场景 | 说明 |
|---|---|---|
| 直接执行 | WiFi 设备、委托者在场 | 委托者直接连接设备执行指令 |
| 委托执行 | 蓝牙设备、委托者不在场 | 通过授权指令包委托新用户自行激活 |
委托执行流程
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| role | uint8 | 是 | 用户角色（0=USER, 1=ADMIN） |
| nickname | string | 否 | 用户昵称，最长32字节 |
请求示例
json
{
"role": 0,
"nickname": "新租客"
}响应参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | uint32 | 是 | 状态码，0=成功 |
| userId | uint32 | 否 | 新用户ID（成功时返回） |
| userSecret | bytes | 否 | 用户密钥，16字节（成功时返回） |
响应示例
json
{
"code": 0,
"userId": 4,
"userSecret": "a1b2c3d4e5f6..."
}权限限制
- 只有拥有者可以创建管理员（role=1）
- 管理员只能创建普通用户（role=0）
- 不能通过此接口创建拥有者（role=2）
userSecret 的重要性
userSecret 是新用户操作门锁的唯一凭证，创建后仅返回一次。APP应：
- 立即保存到本地安全存储
- 同步到云端（建议端到端加密）
- 如丢失需删除用户重新创建
更新用户
更新用户的基本信息。
| 指令码 | 指令名 | 方向 | 鉴权 |
|---|---|---|---|
0x0202 | UpdateUser | APP → 设备 | userSecret |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | uint32 | 是 | 目标用户ID |
| nickname | string | 否 | 新昵称，最长32字节 |
请求示例
json
{
"userId": 3,
"nickname": "王先生"
}响应参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | uint32 | 是 | 状态码，0=成功 |
响应示例
json
{
"code": 0
}权限说明
- 用户可以修改自己的信息
- 管理员和拥有者可以修改任意用户的信息
删除用户
删除指定用户及其所有凭证。
| 指令码 | 指令名 | 方向 | 鉴权 |
|---|---|---|---|
0x0203 | DeleteUser | APP → 设备 | userSecret（管理员或拥有者权限） |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | uint32 | 是 | 要删除的用户ID |
请求示例
json
{
"userId": 3
}响应参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | uint32 | 是 | 状态码，0=成功 |
响应示例
json
{
"code": 0
}删除限制
- 不能删除拥有者：拥有者无法被删除
- 管理员不能删除其他管理员：只有拥有者可以删除管理员
- 级联删除：删除用户时，其名下所有凭证（密码、指纹、卡片等）将一并删除
不可逆操作
删除用户是不可逆操作，被删除用户的所有凭证将永久丢失。建议在APP中实现二次确认机制。
设置角色
修改用户的角色。仅拥有者可执行此操作。
| 指令码 | 指令名 | 方向 | 鉴权 |
|---|---|---|---|
0x0204 | SetUserRole | APP → 设备 | userSecret（拥有者权限） |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | uint32 | 是 | 目标用户ID |
| role | uint8 | 是 | 新角色（0=USER, 1=ADMIN） |
请求示例
提升为管理员：
json
{
"userId": 3,
"role": 1
}降级为普通用户：
json
{
"userId": 2,
"role": 0
}响应参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | uint32 | 是 | 状态码，0=成功 |
响应示例
json
{
"code": 0
}角色变更限制
| 操作 | 允许 | 说明 |
|---|---|---|
| USER → ADMIN | ✓ | 提升普通用户为管理员 |
| ADMIN → USER | ✓ | 降级管理员为普通用户 |
| 变更 OWNER | ✗ | 拥有者角色不能变更 |
使用场景
- 提升管理员：当需要授权某人进行日常管理（添加/删除用户、管理凭证）时
- 降级管理员：当某人不再需要管理权限时，降级以减少安全风险
错误码
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 2001 | 用户不存在 |
| 2002 | 用户已存在 |
| 2003 | 权限不足 |
| 2004 | 不能删除拥有者 |
| 2005 | 不能删除管理员（当前用户为管理员时） |
| 2006 | 用户数量已达上限 |
| 2007 | 昵称过长 |
| 2008 | 不能修改拥有者角色 |
| 2009 | 无效的角色值 |