new-api/.trae/documents/prd.md

ModelsToken 管理平台 - 产品需求文档 (PRD)

1. 产品概述

ModelsToken 是一个 AI API 管理与分发平台，为开发者和企业提供统一的 AI 模型接入、密钥管理、用量计费、渠道代理等一站式服务。新前端将采用 React + DaisyUI 5 + TypeScript 构建，替换现有的 Default/Classic 双前端，同时新增本地文档管理功能。

• 目标用户：AI 应用开发者、企业运维人员、API 服务管理者
• 核心价值：简化 AI API 的管理复杂度，提供直观的操作界面和完整的文档支持

2. 核心功能

2.1 用户角色

角色	注册方式	核心权限
普通用户	用户名/邮箱/OAuth	密钥管理、充值、订阅、日志查看、文档访问
管理员	由超级管理员指定	渠道管理、用户管理、兑换码、模型管理、订阅管理
超级管理员	系统初始化	全部权限 + 系统设置

2.2 功能模块

公共页面（无需登录）

1. 首页：Hero 区域、特性展示、快速入门指引
2. 登录页：用户名/密码、OAuth 登录（GitHub/Discord/OIDC/LinuxDO/微信/Telegram/自定义）
3. 注册页：注册表单 + Turnstile 人机验证
4. 忘记密码：邮箱重置链接
5. 模型定价：模型价格列表、搜索筛选
6. 关于页面：项目信息、版本、许可证
7. 用户协议/隐私政策
8. 初始化向导：首次部署配置

用户功能（需登录）

1. 仪表盘：额度概览、使用趋势图、API 信息面板、公告、FAQ
2. API 密钥管理：创建/编辑/删除/批量操作、额度限制、模型限制、IP 限制
3. 钱包/充值：余额查看、兑换码充值、在线支付（易支付/Stripe/Creem/Waffo）、签到
4. 订阅管理：查看计划、购买订阅、当前订阅状态
5. 使用日志：请求日志搜索/筛选、MJ 日志、任务日志、统计图表
6. 个人设置：资料编辑、2FA 设置、Passkey 管理、OAuth 绑定、语言切换
7. Playground：API 在线调试、Chat Completions 测试
8. 文档中心（新增）：本地文档管理、分类浏览、搜索、Markdown 渲染

管理员功能

1. 渠道管理：CRUD、测试、余额更新、标签管理、批量操作、多密钥、Codex OAuth、Ollama 管理
2. 用户管理：列表/搜索/创建/编辑/升降级/启禁/额度调整
3. 兑换码管理：CRUD、批量删除无效码
4. 模型管理：模型元数据 CRUD、上游同步、缺失模型检测
5. 供应商管理：CRUD
6. 订阅管理：计划 CRUD、用户订阅管理
7. 部署管理：io.net 部署 CRUD、容器管理、日志

超级管理员 - 系统设置

1. 站点设置：名称/Logo/页脚/公告/首页内容/服务器地址
2. 认证设置：注册/登录开关、OAuth 配置、Turnstile、Passkey、自定义 OAuth
3. 计费设置：额度/倍率/支付配置/签到/分组倍率
4. 内容设置：公告/FAQ/Uptime Kuma/聊天/绘图/Midjourney
5. 模型设置：透传/思维模型/Gemini/Claude 配置
6. 运维设置：重试/自动禁用/SMTP/性能监控/日志
7. 安全设置：速率限制/敏感词/SSRF 防护/IP 过滤

2.3 新增功能 - 本地文档管理

功能	说明
文档分类	支持多级分类树，管理员可创建/编辑/删除分类
文档 CRUD	管理员创建/编辑/删除文档，支持 Markdown 编辑器
文档浏览	用户按分类浏览文档，支持搜索
文档搜索	全文搜索文档标题和内容
文档版本	文档更新历史记录
权限控制	可设置文档为公开/登录可见/管理员可见

3. 核心流程

3.1 用户认证流程

flowchart TD
    "访问平台" --> "已登录?"
    "已登录?" -->|"是"| "仪表盘"
    "已登录?" -->|"否"| "登录页"
    "登录页" --> "输入凭证"
    "输入凭证" --> "需要2FA?"
    "需要2FA?" -->|"是"| "输入2FA码"
    "需要2FA?" -->|"否"| "验证成功"
    "输入2FA码" --> "验证成功"
    "验证成功" --> "仪表盘"
    "登录页" --> "OAuth登录"
    "OAuth登录" --> "OAuth回调"
    "OAuth回调" --> "已绑定账号?"
    "已绑定账号?" -->|"是"| "仪表盘"
    "已绑定账号?" -->|"否"| "绑定/注册"

3.2 API 调用流程

flowchart TD
    "创建API密钥" --> "配置密钥参数"
    "配置密钥参数" --> "使用密钥调用API"
    "使用密钥调用API" --> "平台路由到渠道"
    "平台路由到渠道" --> "返回结果"
    "返回结果" --> "记录日志"
    "记录日志" --> "扣除额度"

3.3 文档管理流程（新增）

flowchart TD
    "管理员创建分类" --> "创建文档"
    "创建文档" --> "Markdown编辑"
    "Markdown编辑" --> "设置可见性"
    "设置可见性" --> "发布文档"
    "发布文档" --> "用户浏览/搜索"

4. 用户界面设计

4.1 设计风格

• 主色调：深蓝 (#1e293b) + 亮蓝 (#3b82f6) 渐变，搭配 DaisyUI 的 business 主题
• 辅助色：翡翠绿 (#10b981) 用于成功/在线状态，琥珀色 (#f59e0b) 用于警告
• 按钮风格：DaisyUI 默认圆角按钮，主要操作用 btn-primary，危险操作用 btn-error
• 字体：JetBrains Mono（代码/密钥）+ Noto Sans SC（中文正文）
• 布局风格：左侧固定导航栏 + 顶部状态栏 + 主内容区，响应式折叠
• 图标：Lucide React 图标库
• 动效：DaisyUI 内置动画 + 页面切换淡入

4.2 页面设计概览

页面	模块	UI 元素
首页	Hero	渐变背景、特性卡片、快速开始按钮
登录	表单	居中卡片、OAuth 按钮组、Turnstile
仪表盘	统计卡片	4 列额度卡片、折线图、公告栏、API 信息
密钥管理	数据表	搜索栏、筛选器、表格、批量操作栏
渠道管理	数据表+表单	标签筛选、测试按钮、多密钥管理抽屉
系统设置	标签页	7 大分类侧边导航、表单分组、开关/输入框
文档中心	侧边树+内容	分类树导航、Markdown 渲染、搜索框、面包屑
Playground	分栏	左侧参数面板、右侧响应面板、模型选择器

4.3 响应式设计

• 桌面优先（1280px+）
• 平板适配（768px-1279px）：侧边栏折叠为抽屉
• 移动端适配（<768px）：单列布局，表格改为卡片列表

4.4 布局结构

┌──────────────────────────────────────────────┐
│  顶部导航栏 (Navbar)                           │
│  Logo | 搜索 | 通知 | 用户菜单 | 主题切换        │
├──────┬───────────────────────────────────────┤
│      │                                       │
│ 侧边 │         主内容区                        │
│ 导航 │                                       │
│ 栏   │  ┌─────────────────────────────────┐  │
│      │  │  面包屑 + 页面标题 + 操作按钮      │  │
│ 仪表盘│  ├─────────────────────────────────┤  │
│ 密钥  │  │                                 │  │
│ 渠道  │  │     页面内容                      │  │
│ 用户  │  │                                 │  │
│ 日志  │  │                                 │  │
│ 钱包  │  └─────────────────────────────────┘  │
│ 订阅  │                                       │
│ 文档  │                                       │
│ 设置  │                                       │
│      │                                       │
└──────┴───────────────────────────────────────┘