# Frontend Redesign — Requirements

> 來源：Claude Design bundle `JAdpACs3cSyw_vN6Ketj1Q`（已歸檔於 `design-source/`）。
> 此 SDD 擴展 `../landing-page.md` 的範圍：landing 從「單頁 + OAuth + Dashboard」升級為「5 screen app shell」。

---

## 1. 背景

`arcrun/landing/` 目前只提供：

- `/` — Landing hero + code demo
- `/login` — Google / GitHub OAuth
- `/dashboard` — API Key 管理
- `/api-docs` — Swagger UI（外部）
- `/integrations` — 20 個 recipe 靜態清單

Claude Design 交付一套完整 5 screen 設計（Landing / Auth / API Keys / Dashboard / Workflow Viewer），與現有前端相比多了：

- **Dashboard 的 Apps Grid 與 Workflows Table**（現在沒有應用/workflow 清單 UI）
- **API Keys 獨立頁**（現在和 dashboard 混在一起）
- **Workflow Viewer**：node-based canvas，對應 YAML workflow 的視覺化（目前 acr push YAML 後只有 CLI 輸出）

---

## 2. User Stories

### US-1：新訪客認識 arcrun
- 作為沒用過 arcrun 的工程師，我要在 landing 看到兩條路（For Developers / For Everyone），5 秒內判斷這是否符合我要的用法。
- 驗收：hero + 雙 path card + feature strip 在首屏呈現；CTA「Start free」可點擊到 `/auth`。

### US-2：取得 / 登入會員
- 作為訪客，我要用 GitHub / Google / Email 登入建立帳號。
- 驗收：`/auth` 支援 Sign in / Sign up tabs、GitHub + Google OAuth、Email + Password 表單。OAuth 成功後導向 `/dashboard`。

### US-3：看見應用全貌
- 作為已登入用戶，我要在 Dashboard 看到我已部署的 App（packaged workflow）和 Workflow 清單。
- 驗收：
  - Apps Grid：每個 app 卡片顯示名稱、描述、「Open app」「Edit in Claude」。
  - Workflows Table：顯示 workflow 名稱、節點數、最後修改、執行次數、狀態。
  - 若 app / workflow 為空，顯示新建 CTA（非硬編 mock）。

### US-4：管理 API Keys
- 作為已登入用戶，我要建立、檢視、停用、刪除 API Key。
- 驗收：
  - 剛產生的 Key 顯示在頂部高亮卡片（含警示文字「不會再顯示」）。
  - 全部 Keys 在下方表格顯示（名稱、遮蔽後 key、建立時間、最後使用、狀態、toggle、trash）。
  - Rotate / Revoke 立即生效（呼叫 cypher-executor）。

### US-5：檢視 Workflow graph
- 作為已登入用戶，我要點 workflow 進到 viewer，看到節點 DAG 與每個節點的 I/O schema 與參數。
- 驗收：
  - Canvas 顯示節點（含 icon / type badge），節點以 bezier 曲線相連。
  - 選中節點後右側面板顯示 input / output schema、configuration（針對 ai.completion 等節點顯示 triplet 編輯器）。
  - 工具列含 Share / Export YAML / Edit in Claude。
  - Minimap + zoom 控制顯示可用。
  - 「Export YAML」呼叫 cypher-executor 取得該 workflow 的原始 YAML。

### US-6：Dogfooding
- 作為 arcrun 核心維護者，我要前端所有與服務打交道的動作都透過 arcrun 自家 API（cypher-executor）完成，不依賴第三方 OAuth / workflow / backend 服務。
- 驗收（見 §6）。

---

## 3. 非功能需求

| 項目 | 規範 |
|---|---|
| 技術棧 | Next.js 15 App Router、React 19、Tailwind v4、TypeScript（沿用 `landing/` 現有堆疊） |
| 部署 | Cloudflare Pages（`@cloudflare/next-on-pages`），沿用 `landing/wrangler.toml` |
| 字型 | Inter、JetBrains Mono — 用 `next/font/google`，不拉 unpkg / fonts.googleapis.com `<link>` |
| 依賴 | 僅 Next / React / Tailwind；禁止 tRPC、React Query、SWR、Auth.js/Clerk、ReactFlow/XYFlow、Radix、shadcn CLI install、animation library（framer-motion）等第三方 |
| 狀態管理 | React 內建（useState / useReducer / Context）；持久化用 `localStorage` 或 server session cookie |
| 國際化 | 延後；本次一律英文（與設計稿一致）。現有 `?lang=zh` 不擴展 |
| 無障礙 | 按鈕 `aria-label`、Form 控件有 `<label>`；鍵盤可完成登入 / 複製 key 流程 |
| 效能 | Landing 首屏無阻塞 JS（RSC）；Dashboard / Workflow Viewer 可為 Client Component |

---

## 4. 視覺基準

| 項目 | 值（source of truth：`design-source/index.html` 的 CSS 變數） |
|---|---|
| 主背景 | `#0F0F0F`（現有是 `#0a0a0a` — 本次改為 `#0F0F0F`） |
| Card | `#1A1A1A` |
| Line | `#262626` / `#303030` |
| Primary | `#6366F1`（indigo） → `#8B5CF6`（violet）漸層 |
| Text | `#EDEDED` / dim `#A0A0A0` / mute `#6B6B6B` |
| 字型 | Inter 300/400/500/600/700/800；Mono 400/500/600 |

---

## 5. 範圍界線

### 納入
- 5 screen（Landing、Auth、Dashboard、API Keys、Workflow Viewer）
- Logo（SVG arc wordmark）、Icon set（inline SVG，從 primitives.jsx port）
- TopNav / Footer / Sidebar 三個 shell 元件

### 不納入（本次 SDD）
- **Multi-tenant workspace 切換**（設計稿有 "Northwind" breadcrumb，本次純顯示用戶 email）
- **Multi-API-key CRUD 後端**（cypher-executor 現只支援每帳號一把 key，多 key table 先以「目前只支援一把」狀態呈現 — 見 §6.2）
- **Workflow 編輯**（只做 read-only viewer；編輯仍走 acr CLI / YAML）
- **即時執行狀態 stream**（minimap / zoom 僅 UI，不做真實 pan-zoom transform）
- **i18n 中英切換**、**Hall of Fame**、**Donate**
- **Swagger UI 頁（/api-docs）** — 保留現狀

---

## 6. API 依賴（全部打 `cypher.arcrun.dev`）

### 6.1 既有（已實作於 cypher-executor）
- `GET /me` — 取得登入用戶 + api_key（driver：dashboard 側欄 avatar / API Keys 頁的單把 key）
- `PUT /me/api-key/rotate`、`DELETE /me/api-key` — Rotate / Revoke
- `GET /auth/google/start`、`GET /auth/github/start` — OAuth 起點
- `POST /auth/logout`
- `POST /webhooks/named/{name}/trigger` — 觸發（給 Landing 文案展示）

### 6.2 需新增的 endpoint（阻擋項；**本 SDD 只定義契約，cypher-executor 實作歸屬於另一個 task**）

| Method | Path | 說明 | 用途 |
|---|---|---|---|
| GET | `/workflows` | 列出當前 api_key 名下的 workflow（名稱、nodes、modified、run_count、status） | Dashboard / Workflows Table |
| GET | `/workflows/:name` | 取得 workflow 詳細（含 graph 節點 + edges + YAML） | Workflow Viewer |
| GET | `/workflows/:name/yaml` | 下載 raw YAML | Workflow Viewer Export |
| GET | `/apps` | 列出 app（= workflow 標上 icon/tone/description metadata） | Dashboard / Apps Grid |
| GET | `/api-keys` | 列出多把 key（若後端仍是單把，回傳單元素 array） | API Keys 頁 |
| POST | `/api-keys` | 建立新 key | API Keys 頁「Create new key」 |
| PATCH | `/api-keys/:id` | `{ active: boolean }` 切換 | API Keys 頁 toggle |
| DELETE | `/api-keys/:id` | 刪除 | API Keys 頁 trash |

**在後端尚未實作前**：前端用型別化 fetch wrapper 封裝呼叫；遇到 404 顯示 empty state（而非假資料）。本 SDD 明確禁止 hard-code mock fixture。

### 6.3 登入前後可用的公開資訊
- Integrations 清單（20 個 recipe）：現有 `/integrations` 頁已有靜態清單，繼續複用。

---

## 7. Dogfooding 紅線

| 禁止 | 用哪個 arcrun 內部替代 |
|---|---|
| Auth0 / Clerk / Supabase Auth | cypher-executor `/auth/*` + session cookie（現行 `arcrun_session`） |
| Segment / PostHog | 不加，或用後續 arcrun `analytics` 零件 |
| Vercel KV / Upstash | Cloudflare KV（經 cypher-executor） |
| 直接寫第三方 API（Slack / Notion 等）作 dashboard demo | 透過 arcrun workflow + trigger 模擬 |
| ReactFlow / XYFlow | 純 SVG 手刻（設計稿本來就是手刻） |

---

## 8. 驗收總清單

- [ ] 5 個 screen 全部在 `/`, `/auth`, `/dashboard`, `/keys`, `/workflows/[id]` 可達。
- [ ] 設計稿的 spacing / color / border-radius 100% 對得上（以 `design-source/index.html` CSS 變數為準）。
- [ ] middleware 保護 `/dashboard`, `/keys`, `/workflows/*`（未登入 → `/auth?redirect=...`）。
- [ ] 只打 `cypher.arcrun.dev`（可透過 `NEXT_PUBLIC_API_BASE` override），grep 結果不含其他外部 API host。
- [ ] `package.json` 新增依賴 = 0（本次不引入新 npm 套件）。
- [ ] 無 mock 資料：若後端未實作，顯示 loading 或 empty state，不編假陣列給 UI。
- [ ] `pnpm build` 通過，`next-on-pages` 輸出無 edge-runtime 錯誤。