使用者與權限管理

先確認身份和操作對象

只有服務端認定的管理員可以訪問 /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。服務端拒絕低於當前已記帳與預留之和的上限。調整前讀當前值，調整後重新讀取確認；不要把空缺、請求失敗或 null 當成零。具體含義見配額。

角色變更

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

CORE_ADMIN_EMAILS 在首次創建使用者時決定是否初始化為 admin，不是每次登入都會重寫現有帳戶的角色。不要僅修改環境中的郵箱列表就假定已有使用者角色已經改變。

當前不應承諾的操作

活躍的使用者路由沒有通用刪除使用者、封禁/解封狀態切換、密碼重置或全設備退出的管理 API。資料表擁有 status 字段，不等於公開接口提供其全部生命週期。舊歸檔管理文件或演示組件也不能作為當前可用操作的依據。

伺服器權限變更不等於刪除瀏覽器已取得的信息；管理員應避免把使用者郵箱、檔案記錄、Cookie 或授權值放入截圖和公共報告。報告問題時使用操作類型、脫敏狀態碼、時間和經過處理的關聯標識。

驗證管理操作

先在可丟棄測試實例、專門測試帳戶上驗證查詢、翻頁和額度衝突。角色變更會影響後續權限檢查，避免在唯一管理帳戶上進行試驗。管理指標和通知分別閱讀儀錶盤與通知。