sub2api/docs/superpowers/specs/2026-04-19-puro-ai-landing-auth-design.md

# PURO AI · Landing + Auth 重设计（v2）

> 2026-04-19 · 分支 `feat/design-landing-auth` · **v2 更新：Claude Design 产出 10 页 + puro.css 后，定了路径 B 执行**

本文档是「PURO AI 公开页面重设计」的设计 spec：
- **Stage 1（完成）**：信息架构 + 中文文案 + 风格方向 + 布局选型
- **Stage 2（完成）**：在 claude.ai/design 出了 10 页视觉稿 + `puro.css` 设计系统，归档到 `docs/design-drafts/v2/`
- **Stage 3（本期范围）**：挑 **4 个页面** 落地 — Landing（精修版）、Login、Register、Docs（精简版）+ 设计 tokens 落地到 Tailwind
- **Stage 4**：merge → Drone CI → ai.puro.im 实机验证

## 本期范围决策（路径 B · 分层交付）

### 本期做（feat/design-landing-auth）
1. **puro.css 落地为 Tailwind config + global styles**（`tailwind.config.ts` 扩展 color/radius/font；`puro.css` 挪成 `frontend/src/assets/puro.css` 全局引入）
2. **Landing 页**（路由 `/` 未登录态）· 6 段结构，**精修版文案**（见第 3 节）
3. **Login / Register 页** 套新左右分栏 + 保留现有 OAuth/Turnstile/2FA 逻辑
4. **Docs 页精简版**（路由 `/docs`，公开访问）· 快速接入 + curl 示例 + 支持模型

### 二期做（另开 feat/design-dashboard 分支，不本期）
5. Dashboard 换皮（沿用 puro.css）
6. API Keys 管理页换皮
7. Design System 页（给团队内部看的）

### 永不做 / 远期再说
- **Binding 页**：Claude Design 预设用户自己 BYO-Subscription 绑定，但 Sub2API 是 admin 统一管账号池，概念不符
- **Pricing 页**：iShare 接管钱包/订阅后由 iShare 处理
- 注册送 $5 / 充值阶梯赠送等"赠送经济"特性

---

## 1. 项目背景

| 项 | 值 |
|---|---|
| **公开品牌名** | **PURO AI** |
| **内部代码名** | sub2api（Wei-Shaw/sub2api fork，不改） |
| **域名** | https://ai.puro.im |
| **现状** | 登录后是 Vue 3 + Tailwind 后台；无公开首页；登录页用浅色 `AuthLayout` |
| **目标受众** | 个人开发者 / 小团队 — 已有 ChatGPT Plus / Claude Pro / Codex / Gemini 订阅，想程序化调用而不付 API 费率 |
| **核心叙事** | "你的 AI 订阅，已经付过钱了"——把已付订阅复用为 API |

---

## 2. 风格方向

**暗黑科技**（Dark Tech）—— 对标 Linear / Vercel / Railway / Supabase / Cloudflare Workers。

### 配色（建议）
| 角色 | 色值 | 用途 |
|---|---|---|
| 主底 | `#0a0e1a` ~ `#0f172a` | 页面背景，slate-950 区间 |
| 卡片底 | `#0f172a` | 表单卡片、特性卡 |
| 边框 | `#334155` | 次要边框 |
| 主文 | `#f8fafc` | 标题 |
| 副文 | `#94a3b8` ~ `#cbd5e1` | 描述、菜单 |
| **主品牌色** | `#22d3ee`（cyan-400） | Logo、CTA、链接 |
| **辅品牌色** | `#a855f7`（purple-500） | 渐变叠加、装饰光晕 |
| 警示 | `#fbbf24`（amber-400） | "💡"标签、数字对比 |

### 视觉语汇
- 暗底上**圆形 radial gradient 光晕**（青/紫双色）
- 等宽字体（ui-monospace / SF Mono）用于 code demo
- 主体字体：sans-serif（Inter / SF Pro / 系统默认）
- 边框 1px 实线 / 关键分割用 dashed
- CTA 圆角 8px；卡片圆角 12px
- 不要拟物、不要软阴影、不要 Bootstrap 4 那种 gradient 按钮

### 排版氛围
- 大量留白
- 标题大、字距稍紧（letter-spacing -0.02em）
- 内容居中收敛（max-width ~1100px）

---

## 3. Landing 页（路由 `/`，未登录态）· 精修版

### 3.1 信息架构（6 段，剔除 Pricing/FAQ/CTA banner）

```
NAV     · ⬢ PURO AI · 产品 · 文档 · [登录][免费试用 →]
① HERO  · 主标 + 副标 + CTA×2 + 微文案
② 模型墙 · 4 个支持的 AI 平台
③ 三特性 · ⚡ 一个 key 多模型 · 🔄 账号池高可用 · 📊 用量看板
④ Code Demo · codex config 片段 + curl 示例
⑤ Dashboard · 真实 mockup 预览（不用截图了，设计稿里是 HTML 渲染的）
⑥ Footer · 4 列（品牌 / 产品 / 资源 / 联系）
```

### 3.2 完整中文文案

#### NAV
- Logo: `⬢ PURO AI`
- 菜单: 产品 · 文档
- 右侧: `[登录]`（边框）`[免费试用 →]`（cyan 实底；Nav 里保留注册入口，但 Hero CTA 不走这里）

#### ① HERO
- **主标**: 你的 AI 订阅，**已经付过钱了。**
- **副标**: Claude Pro · ChatGPT Plus · Codex · Gemini 订阅<br>聚合成统一 API，零改动接入 OpenAI / Anthropic SDK
- **主 CTA**: `登录 →`（cyan 实底，已有账号用户直接进）
- **副 CTA**: `联系咨询`（边框，mailto:admin@puro.im 或未来跳 iShare 咨询页）
- **微文案**: 已验证可用 Codex CLI · Claude Code · curl · 服务器出口新加坡

#### ② 模型墙
- **小标题**: 支持的 AI 平台
- **副标**: 通过 OAuth 直接复用你的订阅，无需申请官方 API key
- **Logos**:
  - ⚪ Claude Pro / Max
  - 🟢 ChatGPT Plus / Pro
  - 🟡 Codex CLI
  - 🔵 Gemini Code Assist
  - ⚫ 更多（规划中，灰显）

#### ③ 三大特性
| 图标 | 标题 | 描述 |
|---|---|---|
| ⚡ | 一个 key 接所有模型 | 不再为每个 provider 申请 API key、配置 base_url。统一 sk- 走 Claude / GPT / Gemini，按 model 自动路由到对应账号池。|
| 🔄 | 账号池高可用 | 支持多账号自动调度与 failover。某个上游触发限流 / 冷却时，流量切到下一个健康账号，token 刷新全自动。|
| 📊 | 用量看板 | 每条请求的 tokens、费用、上游账号、延迟全可视化。模型分布饼图 + 趋势曲线 + Top 排行。|

#### ④ Code Demo
- **标题**: 把 base_url 一改，就能用
- **副**: 兼容 OpenAI / Anthropic / Gemini SDK，**零代码改动**
- **代码块**:
  ```toml
  # Codex CLI
  # ~/.codex/config.toml
  [model_providers.OpenAI]
  base_url = "https://ai.puro.im"
  wire_api = "responses"
  ```
  ```bash
  # 或直接 curl
  $ curl https://ai.puro.im/responses \
      -H "Authorization: Bearer sk-xxx" \
      -d '{"model":"gpt-5.4","input":"hello"}'
  ```
- **底注**: 支持 OpenAI Responses API · Anthropic Messages API · Gemini generateContent · 流式 SSE & WebSocket

#### ⑤ Dashboard
- **标题**: 每条请求都看得见
- **副**: 不像第三方 API 池子那种"扣了多少不告诉你"。你能看到每次调用：扣了哪个账号、跑了哪个模型、用了多少 tokens、花了多少钱、上游响应几秒。
- **图**: 使用 Claude Design v2 产出的 **纯 HTML 渲染 mockup**（stats grid + chart 卡片 + log table with provider dots），见 `docs/design-drafts/v2/Landing.html` 里 `#dashboard` 段。本期 Vue 翻译时保持静态数据，不对接真实 API。

#### ⑥ Footer
| 列 | 内容 |
|---|---|
| 品牌 | ⬢ PURO AI<br>Self-hosted on puro.im<br>© 2026 puro.im · MIT License<br>fork of Wei-Shaw/sub2api |
| 产品 | 文档 · 更新日志 |
| 资源 | GitHub · API 状态 · Codex 配置示例 |
| 联系 | admin@puro.im · git.puro.im |

---

## 4. Auth 页（登录 / 注册）

### 4.1 布局选型：左右分栏

```
┌─────────────────────────┬─────────────────────┐
│  左：品牌叙事区          │  右：表单区          │
│  - Logo                 │  - 标题（登录/注册）  │
│  - 主标语（5→1 对比）    │  - 副标               │
│  - 副文（双卖点排比）     │  - email / password  │
│  - 装饰光晕 cyan/purple │  - CTA                │
│  - 底栏小字（支持平台）   │  - 切换链接           │
└─────────────────────────┴─────────────────────┘
```

移动端：左侧叙事降级为顶部小 banner 或完全隐藏，单列表单。

### 4.2 左侧叙事文案

- **Logo**: `⬢ PURO AI`
- **主标语**:
  > **5** 个订阅<br>
  > → **1** 个 key
  
  数字 `5` 用 amber/orange 强调；`1` 用主品牌色 cyan 强调。
- **副文**（三句排比）:
  > 省去切换账号的繁琐，<br>
  > 省去为多个高昂订阅重复买单。<br>
  > <small style="color:#64748b">PURO（纯粹）—— 让 AI 调用回归本质。</small>
- **底栏小字**: `Claude · ChatGPT · Codex · Gemini`

### 4.3 右侧表单

#### 登录页（`/login`）
- 标题: 登录
- 副: 用你的 PURO AI 账户继续
- 字段:
  - 📧 邮箱（input, type=email, required）
  - 🔒 密码（input, type=password, required, 带眼睛切换显示）
- 选项:
  - 忘记密码？（router-link）
  - Turnstile captcha（条件显示）
- CTA: `登录 →`
- 分隔: `或`
- OAuth 按钮（条件显示）:
  - 使用 LinuxDO 登录
  - 使用 OIDC 登录
- 底部链接: 没有账户？**注册**

#### 注册页（`/register`）
- 标题: 创建账户
- 副: 5 分钟开始用 PURO AI
- 字段:
  - 📧 邮箱
  - 🔒 密码
  - 🔒 确认密码
  - （可选）邮箱验证码（条件显示，配置 `email_verify_required` 时）
- Turnstile captcha（条件）
- CTA: `创建账户 →`
- 底部链接: 已有账户？**登录**

#### 其他保留页（不重设计本期）
- `/forgot-password`
- `/reset-password`
- `/verify-email`
- OAuth 回调页

---

## 4.5 Docs 页（新增 · 本期做精简版）

路由 `/docs`，公开访问（不需登录）。沿用 puro.css 设计系统。

### 结构

```
NAV (复用)
── HERO      · "快速接入 PURO AI"（简短）
── § 1       · 获取 API key（流程说明：联系 admin / iShare）
── § 2       · Codex CLI 接入（config.toml 示例）
── § 3       · Claude Code 接入（~/.claude/settings.json 例）
── § 4       · curl 测试（/responses + /v1/messages 两段）
── § 5       · 支持的模型（列表：gpt-5.4, claude-opus-4-7, gemini-2.5-pro 等）
── § 6       · 问题反馈 mailto:admin@puro.im
FOOTER (复用)
```

### 文案原则
- 代码块用 JetBrains Mono，带语法高亮
- 每段开头 1-2 句说明，然后直接上代码，不啰嗦
- 所有 base_url 用真实值：`https://ai.puro.im`

---

## 5. 给 claude.ai/design 的 brief（Stage 2 输入，**已执行完成 · 历史参考**）

> ⚠️ **此节是喂给 Claude Design 的原始 brief**，Claude Design 已按此产出 10 个页面。Stage 2 之后**内容精修 + 范围剪裁**以第 3/4/4.5 节为准，本节仅作历史存档。

复制下方文字到 https://claude.ai/design：

````
我要做两个网页设计，请帮我生成高保真 HTML/React 视觉稿。

## 品牌
名字：PURO AI（拉丁语「纯粹」）
Logo：六边形 ⬢ + 文字
域名：ai.puro.im
定位：把多个 AI 订阅（Claude Pro / ChatGPT Plus / Codex / Gemini）聚合成统一 API
核心叙事：你的 AI 订阅，已经付过钱了

## 风格
暗黑科技风，对标 Linear / Vercel / Railway。
配色：
- 主底 #0a0e1a / #0f172a（slate-950 区间）
- 主品牌色 #22d3ee（cyan-400）
- 辅品牌色 #a855f7（purple-500）
- 强调色 #fbbf24（amber-400，仅用于数字对比）
- 主文 #f8fafc，副文 #94a3b8 ~ #cbd5e1
- 卡片/表单底 #0f172a，边框 #334155

视觉元素：
- 暗底上 radial gradient 光晕（青/紫双色，60% 透明度，blur）
- 大量留白，max-width 1100px
- 圆角：CTA 8px，卡片 12px
- 字体：Inter 或 SF Pro（sans-serif），代码用 ui-monospace
- 不要拟物、不要软阴影、不要 gradient 按钮

## 页面 1：Landing（路由 /，未登录）
6 个 section + 顶部 nav，全部中文。

NAV
- 左：⬢ PURO AI
- 中：产品、文档（定价灰显）
- 右：[登录]（边框）[免费试用 →]（cyan 实底）

① HERO（居中，垂直 padding 大）
主标：你的 AI 订阅，**已经付过钱了。**
（"已经付过钱了" 用 cyan 高亮）
副标：Claude Pro · ChatGPT Plus · Codex · Gemini 订阅
聚合成统一 API，零改动接入 OpenAI / Anthropic SDK
CTA：[立即开始 →][查看文档]
微文案（小灰字）：无需信用卡 · 用你已有的订阅 · 5 分钟跑通

② 模型墙
小标题：支持的 AI 平台
副：通过 OAuth 直接复用你的订阅，无需申请官方 API key
横排 5 个 logo 卡片：Claude Pro/Max · ChatGPT Plus/Pro · Codex CLI · Gemini Code Assist · 更多（灰显）

③ 三特性（3 列卡片）
卡片 1：⚡ 一个 key 接所有模型 / 不再为每个 provider 申请 API key、配置 base_url。统一 sk- 走 Claude / GPT / Gemini，按 model 自动路由到对应账号池。
卡片 2：🔄 账号池高可用 / 多账号自动调度。某个 ChatGPT Plus 触发限流，自动 failover 到下一个。重启、刷新 token 全自动。
卡片 3：📊 用量看板 / 每条请求的 tokens、费用、上游账号、延迟全可视化。模型分布饼图 + 趋势曲线 + Top 排行。

④ Code Demo
标题：把 base_url 一改，就能用
副：兼容 OpenAI / Anthropic / Gemini SDK，零代码改动
代码块（深色 terminal 配色，syntax highlight）：
- 上方一段 toml（codex config）
- 下方一段 bash（curl 示例）
底注小字：支持 OpenAI Responses API · Anthropic Messages API · Gemini generateContent · 流式 SSE & WebSocket

⑤ Dashboard
标题：每条请求都看得见
副：不像第三方 API 池子那种"扣了多少不告诉你"。你能看到每次调用：扣了哪个账号、跑了哪个模型、用了多少 tokens、花了多少钱、上游响应几秒。
图：dashboard 截图占位（深色饼图 + 折线图 + 表格）

⑥ Footer
4 列：
- 品牌列：⬢ PURO AI / Self-hosted on puro.im / © 2026 puro.im · MIT / fork of Wei-Shaw/sub2api
- 产品列：文档 · 套餐（暂隐）· 更新日志
- 资源列：GitHub · API 状态 · Codex 配置示例
- 联系列：admin@puro.im · git.puro.im

## 页面 2：登录页（路由 /login）
左右分栏，桌面端 50/50 分。

左侧（叙事区）：
- 顶部 Logo：⬢ PURO AI
- 中部主标：5 个订阅 → 1 个 key
  （5 用 amber #fbbf24 强调，1 用 cyan #22d3ee 强调，字号 36-48px，weight 800）
- 主标下副文（三句排比）：
  省去切换账号的繁琐，
  省去为多个高昂订阅重复买单。
  PURO（纯粹）—— 让 AI 调用回归本质。
- 底部小字：Claude · ChatGPT · Codex · Gemini
- 背景：linear-gradient(135deg, #0a0e1a, #1e1b4b) + 角落 radial gradient 光晕（cyan + purple）

右侧（表单区）：
- 标题：登录
- 副：用你的 PURO AI 账户继续
- 邮箱输入（带 📧 icon）
- 密码输入（带 🔒 icon + 眼睛切换显示）
- 行：忘记密码？（右对齐链接）
- 主 CTA：登录 →（cyan 实底）
- 分隔：—— 或 ——
- OAuth 按钮：使用 LinuxDO 登录（边框样式）
- 底部：没有账户？注册（链接）

移动端：左侧叙事区收为顶部小 banner（只保留 Logo + 短主标），表单全宽。

## 页面 3：注册页（路由 /register）
和登录页同布局，右侧表单字段：
- 标题：创建账户 / 副：5 分钟开始用 PURO AI
- 邮箱、密码、确认密码
- 主 CTA：创建账户 →
- 底部：已有账户？登录

请生成完整可预览的 HTML（含 inline CSS）或 React 组件。
````

---

## 5.5 Stage 2 产出清单（已完成，参考用）

`docs/design-drafts/v2/` 目录下：

| 文件 | 用途 | 本期用 |
|---|---|---|
| `puro.css` | 设计系统（tokens + primitives .btn/.card/.input 等） | ✅ 全站落地 |
| `Landing.html` | 营销首页（7 段，我们只取 6 段） | ✅ 参考翻译 |
| `Login.html` | 登录页 | ✅ 参考翻译 |
| `Register.html` | 注册页 | ✅ 参考翻译 |
| `Docs.html` | 文档页（精简版参考） | ✅ 参考翻译 |
| `Dashboard.html` | 控制台首页 | ⏳ 二期 |
| `API Keys.html` | Key 管理 | ⏳ 二期 |
| `Design System.html` | 设计系统展示页 | ⏳ 二期（给团队看）|
| `Binding.html` | 订阅绑定 | ❌ 不做（架构不符）|
| `Pricing.html` | 定价 | ❌ 不做（iShare 管） |
| `HANDOFF.md` | 交付文档（含后端契约，部分不适用） | 参考但不全部实现 |

---

## 6. Stage 3 实施约束（给未来的我看）

技术栈（不改动）:
- Vue 3.4+ Composition API + TypeScript
- Tailwind CSS（已配 dark mode、`primary-*` 色板）
- Vite 5
- Vue Router 4 / Pinia / vue-i18n
- 现有组件库（`@/components/common`、`@/components/layout/AuthLayout`）

实施要点:
1. **puro.css 落地**：
   - CSS 变量（--bg-0 等）保留作为全局 tokens，挪到 `frontend/src/assets/puro.css`
   - `main.ts` 里 `import './assets/puro.css'`
   - 在 `tailwind.config.ts` 的 `theme.extend.colors` 里同步一份 cyan/purple/amber/provider 色值，方便 Vue 组件里用 Tailwind class
   - primitives（.btn / .card / .input）可作为全局 class 直接用，也可以包 Vue 组件；**本期直接用 class，不抽组件**
2. **Landing 页是新页**：新建 `frontend/src/views/landing/HomeView.vue`；改 `router/index.ts`，未登录访问 `/` 显示 landing，已登录跳 `/dashboard`
3. **Auth 页改造**：改 `frontend/src/components/layout/AuthLayout.vue` 为左右分栏；改 `LoginView.vue` / `RegisterView.vue` 适配新 layout，**保留所有现有逻辑**（OAuth、Turnstile、2FA、表单校验）
4. **Docs 页是新页**：新建 `frontend/src/views/docs/DocsView.vue`，路由 `/docs`，public 可访问
5. **i18n**：新文案进 `frontend/src/i18n/locales/zh.ts`；本期只补中文（默认语言），英文 key 留空 / 复用现有
6. **Dashboard mockup in Landing**：直接按 Claude Design 的 HTML 翻成 Vue 静态标记（不对接真实数据，纯展示）
7. **不动的**：Setup Wizard / 后台所有页面 / API 层 / store

---

## 7. 验收标准

本地 preview（http://127.0.0.1:4173）已过：

- [x] `puro.css` 已引入为全局样式，`--cyan: #22d3ee` 等变量在 DevTools :root 可见
- [x] 未登录访问 / → LandingView 呈现（route meta.redirectIfAuth=/dashboard 生效分支）
- [x] 已登录访问 / → guard 跳 /dashboard
- [x] Landing 6 个 section 内容全部呈现（Nav + Hero + Models + Features + Code Demo + Dashboard mockup + Footer），移动端可堆叠
- [x] Landing ⑤ Dashboard mockup 为静态 HTML + 内嵌 SVG，无后端依赖
- [x] /login 左右分栏布局，narrative "5→1" 文案 + 登录表单 / heading "登录"
- [x] /register 左右分栏，heading "创建账户" / "5 分钟开始用 PURO AI"
- [x] /docs 公开访问，含 curl / Codex config.toml / Claude Code settings.json 示例
- [x] 所有现有 auth 功能代码未改动（OAuth section / Turnstile / 2FA modal / password toggle 均在原位）
- [x] 后台 /dashboard 等页面使用 style.css 的 .btn/.input/.card（puro.css 已 scoped 到 .puro-page，不污染）
- [x] `pnpm run typecheck` 0 error，`pnpm run build` 成功
- [ ] CI 构建通过，部署后 ai.puro.im 加载正常（Task 13 完成）