Arcrun/system-dev/docs/3-specs/portal-auth/requirements.md

portal-auth — Requirements（RAG Portal 多人授權）

狀態：草稿（待總管/leo 審） 建立：2026-07-13 | 最後更新：2026-07-13 對應交辦：Gitea Leo/Arcrun #24（Portal 拆分，rag-wave1 T1）＋ #25（多用戶＋登入＋session，rag-wave1 T2） 需求上游：Leo/arcrun-rag system-dev/docs/3-specs/rag-wave1/design.md §2/§3/§8；issue 留言 191/192/194/195（leo 2026-07-12、07-13 兩輪拍板）

---

一句話說明

企業 RAG 實例的 Arcrun RAG Portal：多人帳號（email＋密碼登入）＋庫級查詢權限（每帳號綁「可查哪些庫」，server-side enforce）＋admin 管帳號管權限——全部用 Arcrun 既有機制（KBDB 萬用表、KV TTL session、既有查詢 API），零新 D1 表。

背景

• 現行 console 是「單一 owner 帳密」（console-auth.ts：全站一組 email/password，登入只為擋外人看頁面，後端仍用固定租戶字串 CONSOLE_TENANT 打 KBDB）。企業產品要發帳號給多位同仁，且財務/機密庫非人人可查——單人模型不夠。
• #47/#48 已完成品牌與頁面裁剪地基（CONSOLE_BRAND 覆蓋字樣、CONSOLE_PROFILE=rag 裁成搜尋落地 4 頁），但那是「config 裁剪」不是授權——本 SDD 補上多人授權。

User Stories

• US1（一般用戶）：我用 admin 發給我的 email＋密碼登入 Portal，只看得到兩頁：搜尋頁（keyword/semantic/graph 三模式＋來源溯源）＋設定頁（改自己密碼、看自己權限）。我只搜得到「我被授權的庫」的內容。
• US2（admin）：我除了 US1 的兩頁，多「帳號管理」：新增/停用/重設同仁帳號、設定每個帳號可查哪些庫。停用立即生效（該用戶既有 session 失效）。
• US3（owner／導入者）：Admin Console（owner secret）照舊不動；我能用 owner 身份 bootstrap 第一個 Portal admin。
• US4（第二波預告，不實作）：客戶自家 AI 走 MCP 查知識庫時，token 也綁庫集合（PR#15 地基擴充）。

驗收標準（合併 #24/#25 驗收）

1. leo21c（或企業實例）上 /portal 可開；未登入只見登入殼。
2. 三模式查詢（keyword/semantic/graph）與結果來源溯源可用；頁面零 Mira 字樣（Arcrun 品牌，CONSOLE_BRAND 可覆蓋）。
3. admin 新增的用戶能登入查詢；只查得到被授權的庫（server-side filter 驗證：直接 curl Portal 查詢 API 帶該用戶 session 也繞不過，不是前端藏）。
4. 停用用戶登入被拒，且既有 session 立即失效。
5. KBDB 無新 D1 表（D6 萬用表鐵律）；密碼抽查非明碼（雜湊）。
6. Admin Console（owner secret）行為一字不變；Mira 實例（CONSOLE_PROFILE 未設）零影響。

範圍

In Scope（第一波）

• portal_user 用戶模型（KBDB 萬用表）＋帳號狀態（active/disabled）＋角色（user/admin）。
• email＋密碼登入、KV TTL session、登出、改密碼。
• 「庫」的定義與登記（見 design §3）＋每帳號綁可查庫集合＋查詢 API server-side enforce。
• Portal 頁面：登入殼、搜尋頁（三模式＋溯源）、設定頁；admin 加帳號管理頁；工作流頁顯示（見 design §6 裁量）。
• owner bootstrap 第一個 admin 的流程。

Out of Scope（明寫不做，第二波以後）

• SSO / AD / SAML。
• Google OAuth2 登入（fast-follow，不進第一波）。
• per-user MCP token／MCP 庫級 scope（第二波；design §9 只留擴充預告）。
• 審計 log（誰查了什麼）。
• 忘記密碼 email 自助重設（第一波由 admin 重設）。
• Mira 生活面頁（駕駛艙、分流台、專案管理、自動開發）——一律不進企業版（leo 2026-07-13 拍板）。
• 私人筆記（Portal 只顯示公司公用庫，rag-wave1 §-1.2 硬切割）。

鐵律（上游規定，本 SDD 不越）

• 查詢一律走既有 cypher/kbdb API，不開新資料路徑。
• 零新 D1 表（D6）；session/暫存才准 KV；密碼永不明碼。
• Admin Console 現狀不動——拆分是「加一個面」不是重構。
• B 類平台維護流程：本 SDD 總管審 → 實作 PR → component-pr-review-standard 逐條 → 總管 review → gated 部署 leo21c。

風險與降級（rag-wave1 §8 對接）

• Portal/認證是框架級新面積＝第一波最大單件。降級方案：若 pilot 時程被拖住（判準：pilot 日前 P2/P3 未過總管審），先用「CONSOLE_PROFILE=rag console＋共享唯讀連結（單一 token）＋Cloudflare WAF IP 白名單」頂替登入，用戶管理延後——啟用與否回 leo 裁。