# 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 裁**。
