docs: sync truth docs, frontend audits, and runbooks

docs/research/2026-05-27-asxs-vs-sub2api-web-ux-audit.md

@@ -0,0 +1,427 @@
+# asxs.top vs sub2api Web UX Audit (2026-05-27)
+
+## 1. 范围与证据边界
+
+本次目标：整理 `asxs.top` 页面/功能清单，并与当前 `sub2api` 用户门户做对比，为后续插件 Web 端优化提供借鉴。
+
+### 已验证证据
+
+- 公开页面：`https://asxs.top/zh-CN`、`/zh-CN/login`
+- 当前项目门户：`https://sub.tksea.top/portal/`
+- 当前项目门户源码：`deploy/tksea-portal/index.html`
+- 浏览器自动化截图证据：
+  - `browser_screenshot_fe81c4a1e2854b36b13e85a7b51f1181.png`
+  - `browser_screenshot_3dea97c5e37d45a8b2f1aeb06ec99133.png`
+
+### 本轮未拿到的证据
+
+- **未捕获到 asxs.top 的“已登录中转站用户控制台”页面**。
+- 当前自动化浏览器打开 `asxs.top` 时，实际展示的是 **MoeMail 临时邮箱站点**，不是中转控制台。
+- 本机 Chromium 配置中也**未检出 `asxs.top` 的历史记录 / cookie**，因此无法自动复用“你电脑浏览器已登录”的状态。
+
+> 结论：本文件里的 asxs 侧结论，当前仅能基于**公开可见页面**与可验证站点事实；不能把“已登录面板体验更好”伪装成已实证结论。
+
+---
+
+## 2. asxs.top 当前可验证页面清单
+
+### 2.1 首页 `/zh-CN`
+
+定位：公开产品首页，当前呈现的是 **MoeMail 临时邮箱服务**。
+
+#### 页面模块
+
+1. 顶部导航
+   - Logo: `MoeMail`
+   - 语言切换
+   - 主题切换
+   - `登录/注册`
+2. Hero 区
+   - 主标题：`MoeMail`
+   - 价值点卡片：
+     - `隐私保护`
+     - `邮箱分享`
+     - `自动过期`
+     - `开放 API`
+3. 主 CTA
+   - `登录/注册`
+4. 额外入口
+   - `获取网站源代码`
+
+#### 当前可见 UX 特征
+
+- 信息层级简单，首页决策负担低
+- Hero + 价值点卡片很标准，首屏可读性好
+- 顶部导航动作少，主流程聚焦
+- 视觉上比当前 `sub2api` 门户更“产品化”，不是“工具面板堆叠”
+
+### 2.2 登录页 `/zh-CN/login`
+
+#### 页面模块
+
+1. 欢迎文案
+2. Tab 切换
+   - `登录`
+   - `注册`
+3. 登录表单
+   - 用户名
+   - 密码
+   - 登录按钮
+4. 第三方登录
+   - GitHub
+   - Google
+5. `获取网站源代码`
+
+#### 当前可见 UX 特征
+
+- 登录/注册合并在同一交互容器中
+- 支持第三方登录，减少注册阻力
+- 页面目标单一，没有在登录态前暴露太多业务复杂度
+
+---
+
+## 3. 当前 sub2api 门户功能清单（实证）
+
+目标页面：`https://sub.tksea.top/portal/`
+源码：`deploy/tksea-portal/index.html`
+
+### 3.1 顶部说明区
+
+- `Sub2API 公网多模型接入中心`
+- `兼容 OpenAI root endpoint`
+- `旧地址 /kimi-portal 自动跳转`
+- Base URL / `/v1` / Portal 地址展示
+
+### 3.2 会话状态
+
+- 登录态展示
+- 刷新状态
+- 退出登录
+- 账户余额
+- 已开通分组
+- 活跃订阅
+- 已有 Key 数量
+
+### 3.3 分组与模型线路
+
+当前固定展示 4 条线路卡片：
+
+- `Kimi A7M`
+- `GPT asxs 中转`
+- `MiniMax 53hk 中转`
+- `DeepSeek 官方`
+
+每张卡片包含：
+
+- group id
+- 线路标签
+- 推荐模型
+- 是否待开通/需开通
+- 当前账号状态提示
+
+### 3.4 历史 Key
+
+- `GET /api/v1/keys?page=1&page_size=20`
+- 历史 key 列表
+- 一键复制
+
+### 3.5 注册与登录
+
+- 注册：邮箱 + 密码 + `注册并登录`
+- 登录：邮箱 + 密码 + `登录`
+- 当前文案显示：`当前无需邮箱验证码、邀请码或 Turnstile`
+
+### 3.6 创建测试 Key
+
+- Key 名称
+- 线路选择器
+- 创建 Key 按钮
+
+### 3.7 结果与接入信息
+
+- Access Token
+- API Key
+- 复制按钮
+- 当前线路说明
+- 推荐配置（base_url / model / api_key）
+
+### 3.8 前端实现特征（源码实证）
+
+- 纯静态单页 HTML
+- 通过 `fetch()` 调 `PORTAL_PROXY_PREFIX = /portal-proxy/api/v1`
+- 会话保存在 `localStorage`
+  - `sub2api.portal.accessToken`
+  - `sub2api.portal.email`
+- 页面状态统一存于 JS `state`
+  - `accessToken`
+  - `user`
+  - `groups`
+  - `subscriptions`
+  - `keys`
+  - `lastCreatedKey`
+  - `selectionGroupID`
+
+---
+
+## 4. 对比结论（基于当前可证据，不做臆测）
+
+## A. 首屏任务聚焦
+
+### asxs（公开页）
+
+- 首屏只做 1 件事：解释产品 + 引导登录
+- 没有把复杂业务对象提前暴露给未登录用户
+
+### sub2api 当前门户
+
+- 未登录时同时展示：
+  - 会话状态
+  - 线路卡片
+  - 历史 key
+  - 注册/登录
+  - 创建 key
+  - 接入结果区
+- 首屏信息密度高，首次用户理解成本更大
+
+### 借鉴
+
+- **未登录首屏应更像产品入口页，而不是运维面板**。
+
+---
+
+## B. 信息架构
+
+### asxs（公开页）
+
+- IA 很浅：首页 -> 登录/注册
+- 模块少、转化路径短
+
+### sub2api 当前门户
+
+- IA 把“介绍页、用户中心、资源市场、key 管理、接入文档”都压在一个单页里
+
+### 借鉴
+
+- 应拆成更清晰的 3 段式：
+  1. `未登录营销/说明层`
+  2. `登录后账户总览层`
+  3. `资源/Key/接入详情层`
+
+---
+
+## C. 登录体验
+
+### asxs（公开登录页）
+
+- 登录/注册共用容器
+- 支持 GitHub/Google 第三方登录
+- 目标明确
+
+### sub2api 当前门户
+
+- 登录/注册只是大页面中的两个区块
+- 无第三方登录
+- 登录前就暴露了大量“登录后能力”区域
+
+### 借鉴
+
+- 登录/注册可独立成单独弹层或单独页面
+- 优先做“最小阻力登录流程”
+- 登录后再进入业务面板
+
+---
+
+## D. 视觉表达
+
+### asxs（公开页）
+
+- Hero 明确
+- 功能卖点卡片简短
+- 视觉语言统一
+- 更偏“消费级产品页”
+
+### sub2api 当前门户
+
+- 更偏“静态控制台”
+- 视觉结构尚可，但产品感不足
+- 模块层级多，文案偏技术化
+
+### 借鉴
+
+- 保留当前 portal 的卡片式结构，但需要：
+  - 更强的 Hero/主流程提示
+  - 更少的技术术语直接暴露
+  - 更明确的 CTA 层级
+
+---
+
+## E. 用户心智
+
+### asxs（公开页）
+
+- 用户更容易理解：
+  - 这是一个产品
+  - 我先登录
+  - 然后进入服务
+
+### sub2api 当前门户
+
+- 用户需要先理解：
+  - endpoint
+  - group
+  - subscription
+  - key
+  - token
+  - 线路
+- 对非技术用户门槛较高
+
+### 借鉴
+
+- 先让用户完成“拿到可用 Key”
+- 再渐进暴露 `group/subscription/model route` 等概念
+
+---
+
+## 5. 对后续插件 Web 端最值得借鉴的点
+
+按优先级排序：
+
+### P0：未登录态与已登录态彻底分层
+
+- 未登录：只保留产品说明 + 登录/注册 CTA
+- 已登录：再展示线路、key、接入信息
+
+### P0：主流程可视化
+
+页面顶部直接给出 4 步：
+
+1. 登录/注册
+2. 选择线路
+3. 创建 Key
+4. 复制接入配置
+
+### P1：把“资源说明”和“操作面板”拆开
+
+- 当前线路卡片、接入说明、key 结果混在同页
+- 建议拆成：
+  - `概览页`
+  - `线路页`
+  - `Key 管理页`
+  - `接入指南页`
+
+### P1：登录表单产品化
+
+- 支持独立登录页/弹窗
+- 更轻量的注册引导
+- 若后续有能力，可评估第三方登录
+
+### P1：状态表达更明确
+
+当前存在“待开通但可选择”的灰区。
+建议区分：
+
+- 已开通可创建
+- 可申请未开通
+- 仅展示不可创建
+- 创建成功但不可调用
+
+### P2：技术术语延迟暴露
+
+首屏不先讲：
+
+- root endpoint
+- subscription
+- group
+- access token
+
+改为：
+
+- 线路
+- 权限
+- 可用模型
+- 接入地址
+
+### P2：结果区按需展开
+
+- 没创建 key 前结果区默认折叠
+- 创建成功后自动展开并高亮复制动作
+
+---
+
+## 6. 当前 sub2api 门户的具体 UX 问题清单
+
+1. 未登录态信息过载
+2. 登录前可见操作太多，用户不清楚哪些动作真正可执行
+3. 线路状态与创建权限边界不清晰
+4. 结果区默认占位过大
+5. 文案偏技术化
+6. 页面承载“说明 + 账户 + 资源 + 创建 + 接入”五类职责，单页负担偏重
+
+---
+
+## 7. 建议的插件 Web 端信息架构（草案）
+
+### 页面 1：Landing / 入口页
+
+- 产品价值
+- 支持的模型线路
+- 登录/注册 CTA
+
+### 页面 2：用户首页 / 概览
+
+- 当前账号状态
+- 已开通线路
+- 最近创建的 Key
+- 快速入口
+
+### 页面 3：线路页
+
+- 每条线路能力
+- 推荐模型
+- 权限状态
+- 开通方式
+
+### 页面 4：Key 管理页
+
+- 历史 key
+- 新建 key
+- 复制/禁用/备注
+
+### 页面 5：接入指南页
+
+- base_url
+- `/v1` 示例
+- 模型映射
+- SDK 示例
+
+---
+
+## 8. 下一步建议
+
+### A. 先做“证据补全”
+
+需要拿到 **asxs 已登录控制台** 的真实页面证据（URL / 截图 / DOM），否则“asxs 用户端更好”的结论无法做逐页实证对比。
+
+### B. 以当前已验证问题先产出 portal v2 方案
+
+即使没有 asxs 登录态面板，也已经足够支撑一轮优化规划：
+
+- 登录前后分层
+- IA 拆页
+- 线路状态重构
+- Key 结果区按需展示
+
+### C. 若要进入实现，优先顺序建议
+
+1. 先出 `portal v2 IA + wireframe`
+2. 再决定是继续静态页增强，还是迁移到独立 `web/` 前端
+3. 最后再把 asxs 的具体好体验点对照补进去
+
+---
+
+## 9. 本轮结论（短版）
+
+- **已确认**：当前 `asxs.top` 公开页面不是中转控制台，而是 `MoeMail` 首页/登录页。
+- **已确认**：当前 `sub2api` 门户功能完整，但未登录态信息过载、单页职责过多、用户主流程不够聚焦。
+- **高概率正确的优化方向**：学习 asxs 这类产品页的“轻首屏 + 强 CTA + 登录后再进控制台”模式，而不是继续把所有能力堆在一个未分层单页里。
+- **当前 blocker**：还缺 `asxs` 已登录用户控制台证据，无法做“逐页功能清单级”精确对标。