sub2api/docs/design-drafts/v2/HANDOFF.md

PURO AI · 设计交付文档

把已有的 Claude / ChatGPT / Codex / Gemini 订阅聚合成统一 API · 让"已经付过钱的订阅"真正可编程

本文档面向接手实现这套设计的工程团队 / Coding Agent,说明每个 HTML 文件的用途、数据契约、交互逻辑,以及与后端的对接点。

---

0. 文件清单

文件	类型	说明
Landing.html	营销首页	未登录入口 · Hero / 模型墙 / 功能 / 代码示例 / Dashboard 预览 / Pricing / FAQ
Pricing.html	定价页	完整定价 + 成本估算器 + 工具兼容墙 + 10 条 FAQ
Docs.html	文档	快速开始 / 模型列表 / API 参考 / 各客户端配置
Login.html	登录	左侧叙事 + 右侧表单 · 支持 LinuxDO OAuth
Register.html	注册	带密码强度 · 下一步引导 · 送 $5
Binding.html	订阅绑定	核心差异化流程 · OAuth 接入 Claude Pro / ChatGPT Plus
Dashboard.html	控制台首页	余额 / 用量图表 / 近期请求 / 订阅池状态
API Keys.html	Key 管理	创建 / 吊销 / 预算限制 / 模型白名单
Design System.html	设计系统	色板 / 字号 / 组件索引
puro.css	全站样式	所有页面共用的 tokens + primitives(.btn / .pill / .tag / .input 等)

所有页面必须首行 meta: <meta name="color-scheme" content="dark"> —— 防止浏览器 auto-darken 覆盖 cyan 按钮。

---

1. 设计 Tokens(见 puro.css)

--bg-0: #0a0e1a      页面底
--bg-1: #0f172a      raised
--bg-2: #111827      card alt
--bg-code: #020617   代码面板

--border:  #1e293b
--border-2:#334155
--border-3:#475569

--text-0: #f8fafc    主
--text-1: #cbd5e1    次
--text-2: #94a3b8    说明
--text-3: #64748b    弱

--cyan:   #22d3ee    主强调(primary btn / 链接 / 数据点)
--cyan-2: #67e8f9    hover
--purple: #a855f7    次强调 / 装饰
--amber:  #fbbf24    提醒 / 限时标签
--green:  #34d399    成功 / 在线
--red:    #f87171    错误 / 危险

字体:Inter(正文)+ JetBrains Mono(所有数值 / 代码 / 元信息)。 圆角:--r-sm 6px / --r-md 8px / --r-lg 12px / --r-xl 16px。

---

2. 页面 → 后端契约

2.1 Landing · 无后端依赖(纯营销)

锚点:#pricing / #faq / #features / #code / #dashboard。注册 CTA → Register.html。

2.2 Register

提交表单需要 后端返回:

POST /auth/register
{ email, password, linuxdo_token? }
→ 200 { user_id, jwt, balance_credits: 5.00 /* $5 注册赠送 */ }

前端验证规则:

• 邮箱格式 ^[^\s@]+@[^\s@]+\.[^\s@]+$
• 密码强度 ≥ 2(长度 ≥ 8 + 字母大小写混合即可通过)
• 两次密码一致 + 勾选 terms 成功后跳 Binding.html。

2.3 Login

POST /auth/login
{ email, password } 或 { linuxdo_oauth_code }
→ 200 { jwt, user, has_subscriptions: boolean }

若 has_subscriptions === false,引导去 Binding.html;否则去 Dashboard.html。

2.4 Binding(核心差异化)

OAuth 流程,每个平台:

POST /bindings/oauth/start
{ provider: 'claude' | 'chatgpt' | 'codex' | 'gemini' }
→ { auth_url, state }

前端打开 auth_url 新窗口;OAuth 回调:

GET /bindings/oauth/callback?code=...&state=...
→ 302 → /binding/success?provider=claude&account_id=...

绑定列表:

GET /bindings
→ [ { id, provider, account_email, plan, status: 'healthy'|'cooling'|'error', quota_remaining_pct, bound_at } ]
DELETE /bindings/:id  解绑
POST /bindings/:id/test  发一条测试请求验证凭证有效

2.5 Dashboard

GET /me/overview
→ {
  balance: { credits: 45.23, bonus_credits: 12.00, expires_at: null },
  usage_today: { requests: 1842, tokens_in: 2.1e6, tokens_out: 4.8e5, cost: 1.23 },
  usage_30d: [{ date, cost, requests }, ...],
  recent_requests: [{ ts, model, route_to, status, latency_ms, tokens, cost }, ...],
  pool_status: [{ provider, accounts: [{ status, quota_pct }] }]
}

图表用 usage_30d 绘制折线(cyan 主线,purple 副线)。

2.6 API Keys

GET  /api-keys
POST /api-keys  { name, models?: string[], monthly_budget?: number }
DELETE /api-keys/:id

Key 前缀 sk-puro- + 32 字符。创建后仅显示一次完整值,之后只保留前 8 位。

2.7 Pricing

纯静态展示。充值 CTA 统一走:

POST /billing/topup
{ amount_usd, payment_method: 'alipay'|'wechat'|'usdt'|'stripe' }
→ { payment_url / qr_code, order_id }

阶梯赠送在前端计算并展示(见 Pricing.html 底部 script),后端下单时再次校验:

阶梯 = amount >= 500 ? 120%
     : amount >= 200 ? 110%
     : amount >= 99  ? 100%
     : amount >= 50  ? 70%
     : amount >= 30  ? 50%
     : amount >= 20  ? 35%
     : 21%

---

3. 统一 API Gateway(产品核心)

所有用户集成的终点:

https://api.puro.im/v1/chat/completions    # OpenAI 兼容
https://api.puro.im/v1/messages            # Anthropic 兼容
https://api.puro.im/v1beta/models/:m:generateContent  # Gemini 兼容

Header: Authorization: Bearer sk-puro-xxx

调度逻辑(文档化在 Docs.html):

1. 根据模型解析目标 provider
2. 从该 provider 的订阅池挑一个 status=healthy 的账号(权重:剩余配额 × 响应时延倒数)
3. 若 429 / 限流,标记 cooling 60-300s,failover 到下一个
4. 若该 provider 所有订阅都 cooling 且用户余额 > 0,fallback 到官方 API
5. 所有请求写入 request_logs(用户可见,保留周期按套餐)

---

4. 套餐与限制

	Starter $9.9	Pro $29.9 ⭐	Scale $99	Custom
赠送	+21%	+50%	+100%	阶梯
API Keys	1	3	10	按 Pro
RPM	60	120	300	按 Pro
日志保留	7d	30d	90d	按 Pro
自带订阅	❌	∞	∞	✅
多账号 failover	—	✅	✅ + 优先级	✅

Enterprise 走 Sales 线:私有化 / SLA / Invoice,不在普通订单流里。

---

5. 交互细节(容易漏)

• 余额不足:Gateway 返回 402 Payment Required,Dashboard 顶部红色 banner + 发邮件(80% / 95% 两档预警)
• 订阅 cooling 时 Dashboard 订阅卡片上角 amber 闪烁点
• API Key 创建:弹窗必须强制用户复制一次,关闭弹窗后永远看不到完整值
• 密码强度:评分 0-4,label 对应 — / 弱 / 中 / 强 / 极强,颜色 border / red / amber / cyan / green
• 登录成功:按钮变 green 显示 ✓ 登录成功,800ms 后 window.location 跳转
• LinuxDO OAuth 是 PURO 的目标用户群(开发者社区),作为次要登录按钮展示

---

6. 响应式断点

• <= 900px:Login/Register 的 split 变单列,narrative 折叠
• <= 820px:Pricing grid 从 4 列 → 1 列
• <= 820px:Landing pricing-grid-landing 从 3 列 → 1 列
• <= 960px:Pricing 的 calculator 从 2 列 → 1 列

---

7. 后端技术建议(非设计范畴,仅供参考)

• Gateway 层:Go / Rust 写高吞吐代理,HTTP/2 + streaming,每 provider 起独立 worker pool
• 调度:Redis ZSET 存每个订阅的健康分 + cooling 过期时间
• 日志:写 ClickHouse(列存 + 按日分区),Dashboard 直接查
• 凭证加密:每个订阅凭证用 AES-256-GCM 加密,key 放 KMS;解密只在 gateway worker 内存里,绝不落日志
• 计费:Pulsar / Redis Streams 实时扣费,最终一致性,异步对账

---

8. 已知 TODO(设计层面暂不处理,开发阶段补)

• Dashboard 真实图表联动(目前是静态 SVG)
• Binding OAuth 回调 loading / 成功动效
• 邮件模板(注册验证 / 余额预警 / 充值成功)
• 忘记密码流程
• 团队 / 多人协作 UI(Enterprise 档需要)
• i18n:当前仅中文,英文版待出

---

生成时间:2026-04 · 设计稿版本:v1

联系 Sam / 产品负责人确认实现细节。