Leo
519423cb0d
- landing/app/mira/wiki: tag=mira-wiki list now shows all wiki paragraphs (depends on KBDB tag filter exposed in matrix/kbdb commit, separate repo) - landing: app/mira hub + feed split + various WIP from prior sessions - registry/components: claude_api / kbdb_create_block / kbdb_get / km_writer / platform_crypto / auth_oauth2 contracts + main.go (accumulated) - .component-builds: pkg-lock updates + index.ts adjustments (WIP) - .agents/specs/arcrun/frontend-redesign: design notes - docs/test_credentials, docs/user_requirements/arcrun-landing-page: WIP docs - cypher-executor: auth-dispatcher / wasi-shim adjustments (WIP) Includes accumulated work from prior sessions plus the wiki UI tag-filter update that surfaces the AI-generated wiki paragraphs at /mira/wiki. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
160 lines
8.2 KiB
Markdown
160 lines
8.2 KiB
Markdown
# 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 錯誤。
|