账号管理业务文档

适用于把 KeyHub 当作轻量账号授权服务的项目。客户端用账号、手机号、邮箱或自定义标识作为 key 注册，再用同一个 key 做有效性校验。

项目要求

后台创建项目时，项目类型选择 账号管理
客户端需要保存 project_name 和用户标识
后台仍可禁用、删除或备注账号授权

客户端接口

POST /api/register

注册或重新注册账号标识。

POST /api/verify

验证账号标识是否仍然有效。

请求示例

注册账号

{
    "key": "user@example.com",        // 必填：账号标识，可以是邮箱、手机号、用户ID
    "project_name": "VR Account Project", // 必填：后台项目名称，必须完全一致
    "remarks": "门店账号"             // 可选：后台备注，方便管理员识别
}

验证账号

{
    "key": "user@example.com",        // 必填：要验证的账号标识
    "project_name": "VR Account Project" // 必填：账号管理项目名称
}

返回示例

注册成功

{
    "success": true,                  // 是否注册成功
    "key": "user@example.com",        // 已注册的账号标识
    "message": "注册成功"             // 服务端提示信息
}

验证成功

{
    "valid": true,                    // 客户端主要判断字段：true 表示账号可用
    "message": "验证通过",            // 验证结果说明
    "id": 12,                         // 授权记录ID
    "key": "user@example.com",        // 当前账号标识
    "project_id": 3,                  // 项目ID
    "project_name": "VR Account Project", // 项目名称
    "project_type": "account",       // 项目类型：账号管理
    "is_active": true,                // 后台是否启用
    "auth_type": "unlimited",        // 账号管理默认不限次数/日期
    "remaining_plays": null,          // 播控项目才使用，账号项目为 null
    "valid_until": null,              // 播控项目才使用，账号项目为 null
    "machine_code": null,             // 播控项目才使用，账号项目为 null
    "last_play_started_at": null,     // 播控项目最后播放时间
    "playable": true,                 // 综合授权状态
    "expired": false                  // 是否过期
}

验证失败

{
    "valid": false,                   // false 表示不可用
    "message": "未找到该密钥在此项目下的授权" // 失败原因，可直接展示或记录
}

接入说明

账号管理项目适合已有账号系统的简单授权开关，不负责密码登录。
建议客户端只把稳定用户标识传给 KeyHub，不要传明文密码。
后台禁用授权后，下一次 /api/verify 会返回无效。