登录与会话

邮箱验证码的完整流程、限流规则、会话刷新机制、角色说明以及退出登录的实际行为。

验证码登录

/signin 使用邮箱加六位数字验证码登录，不使用密码。发送请求会返回 challengeId、expiresInSeconds: 600 和 resendAfterSeconds: 60。验证时需要提供同一组邮箱、challengeId 和验证码；如果换了邮箱或重新发码，就按页面上的新挑战继续。

服务端按 UTC 小时统计发送请求：每个邮箱上限 5 次、每个 IP 上限 20 次，还有邮箱 60 秒冷却。多人共用同一出口时，可能会遇到同一个 IP 上限。收到 429 时等一等就好，不要换网络或循环重试。每个挑战最多允许 5 次错误尝试；验证码一旦成功使用，就只能消费一次。

响应	含义和处理方式
请求返回 202	投递请求已接受，但你还需要确认实际收到邮件
验证返回 400	邮箱、挑战或六位数字的格式不对
验证返回 401	挑战无效、已过期或已经用过了——回到页面重新申请
返回 429	发送限流或验证次数耗尽，按限制等待即可
返回 503	身份服务、数据库、Redis 或邮件依赖暂时不可用，稍后重试并联系运营者

注册、角色与访问范围

第一次成功验证时会自动创建账户；如果你已经有账户，会直接登录到原来的账户。/signup、/register、/reset-password 这些兼容入口只是做了跳转，并不代表仍支持密码注册、密码恢复或邀请码流程。

普通用户登录后进入 /account，管理员进入 /admin/overview。管理权限由服务端检查，在浏览器里隐藏按钮或修改角色字段不会真正授予权限。管理接口返回 403 说明当前身份没有管理员权限，不需要反复请求。

会话会怎样失效

登录返回的 access token 有效期是 900 秒。浏览器通过 HttpOnly refresh cookie 刷新，会话空闲期限为 30 天、绝对期限为 90 天。刷新时会轮换 refresh token，旧 token 如果被重用会触发会话防护。客户端会自动协调刷新，但这并不保证你能永远保持登录状态。

生产环境的 refresh cookie 使用 Secure、SameSite=Lax，路径为 /api/v1/auth。请从正确的 HTTPS 同源入口访问，不要在不同域名之间混用登录页面和 API。access token、Cookie、验证码这些敏感信息，都不要放到 URL、截图或公开问题报告里。

安全退出与常见误解

"退出登录"会调用服务端撤销当前 refresh session 并清除 cookie，然后跳回登录页。退出不会删除你的文件，也不等于所有设备同时退出——已签发的 access token 还有自己的剩余有效期。目前没有账户自助删除或全设备会话管理的操作。

如果邮件已经发出去了但就是验证不了，先核对当前邮箱和最新的挑战，记下错误状态和发生时间就好，不要把验证码发给文档 AI。更多排查步骤见排错。