awoooi/docs/adr/ADR-UI-01-operator-console-architecture.md

ADR-UI-01: Operator Console Architecture

狀態：Accepted 日期：2026-05-03（台北） 決策者：統帥 範圍：AwoooP Operator Console 前端整體架構、與現有 apps/web/ 的整合方式 關聯：ADR-106（六合約）、ADR-112（contract governance）、ADR-115（principal mapping）

---

背景

AwoooP 需要一個 Operator Console（管理員後台），讓平台管理員可以：

1. 管理 tenant（project）和 principal 角色
2. 查看和管理 contract revisions（六合約的 draft/publish/activate）
3. 監控 runs（run state, saga steps, budget usage）
4. 執行 approval decisions（human approval for WAITING_APPROVAL runs）

現有 apps/web/ 是 Next.js 14 前端，已有 AI 監控 dashboard。Operator Console 需要在不破壞現有功能的情況下整合。

---

決策

D1 — 整合方式：子路由擴展（不建新應用）

Operator Console 作為 apps/web/ 的新路由段：

apps/web/src/app/
├── (existing)/           ← 現有頁面（不動）
│   ├── dashboard/
│   ├── incidents/
│   └── ...
└── awooop/               ← 新增 Operator Console
    ├── layout.tsx        ← Console layout（sidebar + auth gate）
    ├── tenants/          ← Tenant 管理
    │   ├── page.tsx
    │   └── [project_id]/
    │       ├── page.tsx
    │       └── principals/
    ├── contracts/        ← Contract governance
    │   ├── page.tsx
    │   └── [contract_id]/
    │       ├── page.tsx
    │       └── revisions/
    ├── runs/             ← Run 監控
    │   ├── page.tsx
    │   └── [run_id]/
    │       └── page.tsx
    └── approvals/        ← Approval decisions
        ├── page.tsx
        └── [run_id]/
            └── page.tsx

D2 — Auth Gate（Operator Console 專屬）

Operator Console 需要 platform_subject.roles 中包含 admin 或 approver：

// apps/web/src/app/awooop/layout.tsx
import { redirect } from "next/navigation"
import { getServerSession } from "@/lib/auth"
import { hasOperatorRole } from "@/lib/awooop-auth"

export default async function AwoooPLayout({ children }) {
  const session = await getServerSession()
  if (!session || !hasOperatorRole(session.user)) {
    redirect("/unauthorized")
  }
  return (
    <div className="awooop-operator-layout">
      <AwoooPSidebar />
      <main>{children}</main>
    </div>
  )
}

D3 — API Client 分層

apps/web/src/lib/
├── awooop/
│   ├── client.ts         ← AwoooP Platform API client（/v1/platform/...）
│   ├── types.ts          ← TypeScript types（從 API spec 生成）
│   ├── runs.ts           ← Run 相關 API calls
│   ├── contracts.ts      ← Contract 相關 API calls
│   ├── tenants.ts        ← Tenant 相關 API calls
│   └── approvals.ts      ← Approval 相關 API calls

API base URL：

// 從環境變數讀取（禁止 hardcode 內網 IP，feedback_frontend_internal_ip_ban）
const AWOOOP_API_BASE = process.env.NEXT_PUBLIC_AWOOOP_API_URL
// K8s ConfigMap 設置：NEXT_PUBLIC_AWOOOP_API_URL=https://api.awoooi.com

D4 — 8 個 UI 模組（Phase 5 實作）

模組	路由	功能	ADR 關聯
M1 Tenant List	/awooop/tenants	列出所有 project，建立/停用	ADR-115
M2 Principal Manager	/awooop/tenants/[id]/principals	角色管理，auto-provision 確認	ADR-115
M3 Contract Dashboard	/awooop/contracts	六合約總覽，active revision 狀態	ADR-106
M4 Contract Editor	/awooop/contracts/[id]/revisions	draft/publish/activate 操作	ADR-112
M5 Run Monitor	/awooop/runs	所有 run 的即時狀態	ADR-114
M6 Run Detail	/awooop/runs/[run_id]	saga_steps, budget, trace_id	ADR-119
M7 Approval Queue	/awooop/approvals	WAITING_APPROVAL run 列表	ADR-114
M8 Approval Decision	/awooop/approvals/[run_id]	approve/reject + token 生成	ADR-116

各模組的詳細設計在 ADR-UI-02 / ADR-UI-03 / ADR-UI-04。

D5 — 設計原則

1. 禁止 emoji，使用 Lucide icon（feedback_no_emoji_use_icons）
2. 全站統一字體/顏色（feedback_design_system_consistency）
3. 100% next-intl i18n（feedback_i18n_zero_hardcode）— 所有文字走翻譯 key
4. 禁止內網 IP（feedback_frontend_internal_ip_ban）— NEXT_PUBLIC_* 只用公網域名
5. Logo SVG 與正式環境一致（feedback_brand_logo_consistency）

D6 — 即時更新（WebSocket / SSE）

Run Monitor（M5）和 Approval Queue（M7）需要即時更新：

// Server-Sent Events（比 WebSocket 更簡單，適合單向推送）
// GET /v1/platform/runs/stream?project_id=awoooi&status=RUNNING,WAITING_APPROVAL

const eventSource = new EventSource(
  `/v1/platform/runs/stream?project_id=${projectId}`
)
eventSource.onmessage = (event) => {
  const update = JSON.parse(event.data) as RunStateUpdate
  updateRunInCache(update)
}

---

後果

Benefits

• 複用現有 apps/web/ 的 auth、i18n、設計系統（不重造輪子）
• 子路由設計：現有功能不受影響，可獨立部署 Operator Console 路由
• Phase 5 前，/awooop/* 路由可以用 feature flag 隱藏（9 個 feature flag 中的 ENABLE_OPERATOR_CONSOLE）

Costs

• 需要在 apps/web/ 建立 awooop/ 目錄結構（~15 個新檔案）
• API client 需要 TypeScript type generation（從 OpenAPI spec）

Risks

• Operator Console 的 auth gate 若有漏洞 → 非管理員可存取敏感操作
• 緩解：auth gate 在 layout.tsx 實作（server-side），不依賴 client-side 隱藏

---

驗收標準

• /awooop 路由在 apps/web/src/app/ 建立（Phase 5）
• auth gate：非 admin/approver → redirect /unauthorized（整合測試）
• NEXT_PUBLIC_AWOOOP_API_URL 不含內網 IP（CI lint check）
• 8 個模組全部有對應路由（Phase 5 完成）

關聯

• ADR-106（六合約，Contract Dashboard M3/M4 的資料來源）
• ADR-112（contract governance API，M4 的操作路徑）
• ADR-114（run state，M5 M6 的資料來源）
• ADR-115（principal mapping，M1 M2）
• ADR-116（approval token，M8 核心功能）