登入與會話

郵箱驗證碼的流程與限制、會話的有效期與刷新機制，以及安全退出的實際行為。

驗證碼登入

/signin 採用郵箱加六位數字驗證碼的方式登入，不使用密碼。發送請求會回傳 challengeId、expiresInSeconds: 600 和 resendAfterSeconds: 60。驗證時需要同一組郵箱、challengeId 和驗證碼；如果換了郵箱或重新發碼，請依照當前頁面上的新挑戰繼續操作。

伺服器按 UTC 小時統計發送請求：每個郵箱上限 5 次、每個 IP 上限 20 次，另外每個郵箱有 60 秒冷卻時間。共用同一個出口 IP 的多人可能會碰到同一個 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、驗證碼都不應該出現在網址、截圖或公開的問題報告中。

安全退出與常見誤解

「退出登入」會呼叫伺服器撤銷當前的 refresh session 並清除 cookie，然後回到登入頁。退出不會刪除檔案，也不代表所有裝置同時登出——已簽發的 access token 仍有自己的有效期。目前的指南沒有帳戶自助刪除或全裝置會話管理的操作方式。

如果郵件已發送卻無法通過驗證，先確認你用的是當前郵箱和最新的挑戰，把錯誤狀態與發生時間記下來就好；請不要把驗證碼提供給文件 AI。更多排查步驟可以參考排錯。