使用者與權限管理

先確認身份和操作對象

只有伺服器端認定的管理員才能存取 /admin/users 和對應的管理 API。401 表示身份無效，403 表示你不是管理員；透過修改頁面狀態或 access token 內容並不能取得管理權限。

使用者列表 API GET /api/v1/admin/users 支援 query 或 q 搜尋、page、pageSize；預設每頁 20 筆，最多 100 筆。單一使用者詳情為 GET /api/v1/admin/users/{userId}。請根據明確的 userId 進行操作，不要僅憑列表順序或看起來相似的郵箱來決定目標。

查看檔案與額度

使用者詳情可以幫助你核對角色和空間狀況。管理員查看指定使用者的檔案使用 GET /api/v1/admin/users/{userId}/files，一樣要遵循 cursor 分頁；查看記錄不代表你取得了該使用者才有的分享和發佈權限。

配額調整使用 PATCH /api/v1/admin/users/{userId}/quota，傳入字串格式的 limitBytes。如果新上限低於目前已記帳加上已預留的總和，伺服器會拒絕並回傳 409。調整前先讀取目前的值，調整後也要重新讀取做確認；不要把空值、請求失敗或 null 當成零。詳細的配額含義請參考配額。

角色變更

PATCH /api/v1/admin/users/{userId}/role 接受 {"role":"user"} 或 {"role":"admin"}。這是一項權限變更，請確認目標和目的之後再執行。變更後重新讀取使用者詳情做確認，必要時讓目標使用者重新進入管理頁面。

CORE_ADMIN_EMAILS 是在使用者第一次建立帳戶時決定是否初始化為 admin 的設定，並不是每次登入都會重寫現有帳戶的角色。不要單純修改環境變數中的郵箱列表就認為已有使用者的角色已經改變了。

當前不應承諾的操作

目前活躍的使用者路由沒有提供通用的刪除使用者、封禁/解封狀態切換、密碼重設或全裝置登出的管理 API。資料表中雖然有 status 欄位，但不代表公開介面支援它的完整生命週期。舊的歸檔管理文件或展示用元件也不能作為判斷目前可用操作的依據。

伺服器端的權限變更不等於刪除瀏覽器已取得的資訊。管理員應避免在截圖或公開報告中放入使用者的郵箱、檔案記錄、Cookie 或授權值。回報問題時，提供操作類型、脫敏後的狀態碼、時間以及經過處理的關聯識別碼即可。

驗證管理操作

建議先在可丟棄的測試實例、專門的測試帳戶上驗證查詢、翻頁和額度衝突等操作。角色變更會直接影響後續的權限檢查，請避免在唯一的管理帳戶上做實驗。管理指標和通知的說明分別在儀錶盤與通知。