2026-04-19 13:58:25 +00:00
1 changed files with 99 additions and 25 deletions
--- a/docs/superpowers/specs/2026-04-19-puro-ai-landing-auth-design.md
+++ b/docs/superpowers/specs/2026-04-19-puro-ai-landing-auth-design.md
@@ -1,12 +1,30 @@
-# PURO AI · Landing + Auth 重设计
+# PURO AI · Landing + Auth 重设计（v2）

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

 本文档是「PURO AI 公开页面重设计」的设计 spec：
- **Stage 1（已完成 – brainstorm）**：信息架构 + 中文文案 + 风格方向 + 布局选型
- **Stage 2（待执行 – user）**：拿本文档去 https://claude.ai/design 产出高保真视觉稿
- **Stage 3（待执行 – Claude Code）**：把视觉稿翻译成 Vue 3 组件，对齐 Tailwind / router / i18n
- **Stage 4（待执行 – CI）**：merge → Drone CI → ai.puro.im 实机验证
+- **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 / 充值阶梯赠送等"赠送经济"特性

 ---

@@ -54,17 +72,17 @@

 ---

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

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

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

@@ -72,14 +90,15 @@ NAV     · ⬢ PURO AI · 产品 · 文档 · [登录][免费试用]

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

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

 #### ② 模型墙
 - **小标题**: 支持的 AI 平台
@@ -95,7 +114,7 @@ NAV     · ⬢ PURO AI · 产品 · 文档 · [登录][免费试用]
 | 图标 | 标题 | 描述 |
 |---|---|---|
 | ⚡ | 一个 key 接所有模型 | 不再为每个 provider 申请 API key、配置 base_url。统一 sk- 走 Claude / GPT / Gemini，按 model 自动路由到对应账号池。|
-| 🔄 | 账号池高可用 | 多账号自动调度。某个 ChatGPT Plus 触发限流，自动 failover 到下一个。重启、刷新 token 全自动。|
+| 🔄 | 账号池高可用 | 支持多账号自动调度与 failover。某个上游触发限流 / 冷却时，流量切到下一个健康账号，token 刷新全自动。|
 | 📊 | 用量看板 | 每条请求的 tokens、费用、上游账号、延迟全可视化。模型分布饼图 + 趋势曲线 + Top 排行。|

 #### ④ Code Demo
@@ -120,13 +139,13 @@ NAV     · ⬢ PURO AI · 产品 · 文档 · [登录][免费试用]
 #### ⑤ Dashboard
 - **标题**: 每条请求都看得见
 - **副**: 不像第三方 API 池子那种"扣了多少不告诉你"。你能看到每次调用：扣了哪个账号、跑了哪个模型、用了多少 tokens、花了多少钱、上游响应几秒。
- **图**: 截图占位 → 实施时取 ai.puro.im 实拍（模型分布饼图 + Token 趋势 + Top 模型 + 性能指标）
+- **图**: 使用 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 |

@@ -201,7 +220,34 @@ NAV     · ⬢ PURO AI · 产品 · 文档 · [登录][免费试用]

 ---

-## 5. 给 claude.ai/design 的 brief（Stage 2 输入）
+## 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：

@@ -317,6 +363,26 @@ CTA：[立即开始 →][查看文档]

 ---

+## 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 实施约束（给未来的我看）

 技术栈（不改动）:
@@ -327,22 +393,30 @@ CTA：[立即开始 →][查看文档]
 - 现有组件库（`@/components/common`、`@/components/layout/AuthLayout`）

 实施要点:
-1. **Landing 页是新页**：新建 `frontend/src/views/landing/HomeView.vue`；改 `router/index.ts`，未登录访问 `/` 显示 landing，已登录跳 `/dashboard`
-2. **Auth 页改造**：改 `frontend/src/components/layout/AuthLayout.vue` 为左右分栏；改 `LoginView.vue` / `RegisterView.vue` 适配新 layout，**保留所有现有逻辑**（OAuth、Turnstile、2FA、表单校验）
-3. **i18n**：新文案进 `frontend/src/i18n/locales/zh.ts`；本期只补中文（默认语言），英文 key 留空 / 复用现有
-4. **Tailwind 配色**：如果新色值不在 `tailwind.config` 里，按需扩展 `colors.brand` / `colors.accent`
-5. **Dashboard 截图**：实施时手动截 ai.puro.im 后台 → 放 `frontend/public/landing/dashboard.png`
-6. **不动的**：Setup Wizard / 后台所有页面 / API 层 / store
+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. 验收标准

+- [ ] `puro.css` 已引入为全局样式，CSS 变量在 DevTools :root 可见
 - [ ] 未登录访问 https://ai.puro.im/ → 看到 PURO AI Landing 页
 - [ ] 已登录访问 https://ai.puro.im/ → 跳到 /dashboard（保持现有行为）
 - [ ] Landing 6 个 section 内容全部呈现，移动端可堆叠
+- [ ] Landing 的 ⑤ Dashboard mockup 是静态 HTML 渲染，不依赖真实数据
 - [ ] /login 是左右分栏布局，文案与 spec 一致
 - [ ] /register 同上
+- [ ] /docs 可公开访问，包含 curl 示例、Codex CLI 配置、Claude Code 配置
 - [ ] 所有现有 auth 功能（OAuth、Turnstile、2FA、密码重置）仍可用
 - [ ] 后台所有页面（dashboard、账号管理、API key 等）外观不变
 - [ ] CI 构建通过，部署后 ai.puro.im 加载正常