OAuth 登录

HandyCafe 支持使用设备授权授予（RFC 8628）的社交/OAuth 登录方式。此流程专为自助终端和公共环境设计，顾客无需在共享 PC 上输入凭证。

支持的提供商

每个提供商可在设置 > OAuth中单独启用或禁用。

认证流程

设备授权流程按以下步骤进行：

1. 顾客选择提供商 -- 在客户端待机画面上，顾客点击提供商按钮（如 Google、Discord）。
2. 客户端向服务端发送请求 -- 客户端通知 HandyCafe 服务端已发起 OAuth 登录。
3. 服务端请求设备码 -- 服务端联系所选提供商的设备授权端点，获取设备码、用户码和验证 URI。
4. 客户端显示验证码 -- 客户端向顾客展示 user_code 和 verification_uri，通常以二维码形式呈现以便扫描。
5. 顾客在手机上完成认证 -- 顾客用个人设备（手机或平板）扫描二维码，在提供商网站上完成认证。
6. 服务端轮询令牌 -- 服务端定期向提供商轮询令牌。轮询状态包括：
   • 待处理 -- 顾客尚未完成认证。
   • 请求过频 -- 轮询过于频繁；服务端降低频率。
   • 成功 -- 认证完成；已收到令牌。
   • 已过期 -- 设备码在认证前已过期。
   • 错误 -- 发生意外错误。
7. 服务端获取用户信息 -- 成功后，服务端使用令牌从提供商获取顾客资料，包括 provider_uid、email、name 和 avatar_url。
8. 管理员审批或拒绝 -- 登录请求出现在请求页面上。管理员或收银员审核后批准或拒绝。
9. 创建或关联会员 -- 批准后，创建新的会员账户或将 OAuth 身份关联到已有会员。
10. 客户端时段开始 -- 客户端收到确认，顾客的时段开始。

安全考虑

• 凭证不接触共享 PC。 顾客仅在个人设备上完成认证。客户端机器上不输入密码或令牌。
• 管理员审批门控。 每个 OAuth 登录请求必须经管理员或收银员批准后才能开始时段，防止未授权访问。
• 可配置的余额要求。 "允许无余额登录"选项可启用或禁用，控制顾客是否需要正余额才能通过 OAuth 登录。

配置

OAuth 提供商在设置 > OAuth中配置。每个提供商需要从其开发者控制台获取的客户端凭证（Client ID 和 Client Secret）。仅启用您想向顾客提供的提供商。