双端说明：用户控制台 vs 平台管理端

平台包含两个独立的 UI 端，共享同一套后端服务，通过不同的 API 前缀、认证方式和权限体系进行隔离。

1. 端点总览

维度 用户控制台 平台管理端
访问对象 注册用户（个人用户 / 企业用户） 平台运营人员 / 超级管理员
前端域名 https://console.example.com https://admin.example.com
API 前缀 /api/v1/ /admin/v1/
登录方式 账号密码 / 手机号 / 三方 OAuth 账号密码 + 强制 2FA（TOTP/短信）
会话 Token JWT，有效期 2 小时 JWT，有效期 8 小时，IP 绑定
数据范围 仅自身账号数据 全平台所有用户数据
Token 刷新 支持静默刷新 8 小时后需重新完整登录

2. 用户控制台 — 功能页面与 API 映射

认证页面

页面 核心 API
登录 POST /api/v1/auth/login，POST /api/v1/auth/login/phone
注册 POST /api/v1/users/register
找回密码 POST /api/v1/auth/forgot-password，POST /api/v1/auth/reset-password
第三方登录 GET /api/v1/auth/oauth/{provider}/authorize

主控制台页面

页面 核心 API
首页概览（Dashboard） GET /api/v1/tokens/usage/dashboard，GET /api/v1/wallet/balance，GET /api/v1/messages/unread-count
模型广场 GET /api/v1/models
AI 对话 POST /api/v1/chat/completions（SSE 流式）
对话历史 GET /api/v1/chat/history，GET /api/v1/chat/history/{session_id}
排队状态 GET /api/v1/chat/queue/status

Token 用量统计

页面 核心 API
用量仪表盘 GET /api/v1/tokens/usage/dashboard
每日趋势 GET /api/v1/tokens/usage/daily
Top 10 模型 GET /api/v1/tokens/usage/top-models
API Key 统计 GET /api/v1/tokens/usage/by-apikey
实时用量 GET /api/v1/tokens/usage/realtime
价格对比 GET /api/v1/tokens/price-comparison
费用预估 POST /api/v1/tokens/estimate

财务页面

页面 核心 API
钱包 / 余额 GET /api/v1/wallet/balance
充值 POST /api/v1/wallet/recharge
代金券 GET /api/v1/wallet/vouchers，POST /api/v1/wallet/vouchers/redeem
订单记录 GET /api/v1/orders
交易流水 GET /api/v1/transactions
月度账单 GET /api/v1/billing/invoices
申请开票 POST /api/v1/wallet/invoices

会员与个人

页面 核心 API
会员中心 GET /api/v1/membership/me，GET /api/v1/membership/plans
个人信息 GET /api/v1/users/me，PUT /api/v1/users/me
企业信息 GET /api/v1/enterprise/profile（企业账号专属）
企业成员管理 GET /api/v1/enterprise/members（企业管理员专属）
API Key 管理 GET /api/v1/users/me/apikeys
第三方账号绑定 GET /api/v1/auth/bindings
安全设置 PUT /api/v1/users/me/password

消息与通知

页面 核心 API
消息中心 GET /api/v1/messages，GET /api/v1/messages/unread-count
实时推送 GET /api/v1/messages/stream（SSE 长连接）
通知偏好设置 GET /api/v1/notifications/preferences，PUT /api/v1/notifications/preferences

3. 平台管理端 — 功能页面与 API 映射

管理端登录流程

POST /admin/v1/auth/login        → 验证账号密码，返回临时 token（5分钟）
POST /admin/v1/auth/2fa/verify   → 验证 TOTP/短信，返回正式 access_token（8h，IP绑定）
POST /admin/v1/auth/logout
POST /admin/v1/auth/refresh      → 无法静默刷新，过期需重新登录

数据总览

页面 核心 API
运营仪表盘 GET /admin/v1/stats/overview
收入趋势 GET /admin/v1/stats/revenue
用户增长 GET /admin/v1/stats/user-growth
平台用量 Top 10 GET /admin/v1/tokens/usage/top-users

用户管理

页面 核心 API
用户列表 GET /admin/v1/users（支持类型/状态筛选）
用户详情 GET /admin/v1/users/{user_id}
冻结 / 解冻 PUT /admin/v1/users/{user_id}/freeze，PUT /admin/v1/users/{user_id}/unfreeze
重置密码 PUT /admin/v1/users/{user_id}/reset-password
企业列表 GET /admin/v1/enterprises
企业认证审核 PUT /admin/v1/enterprises/{id}/verify，PUT /admin/v1/enterprises/{id}/reject
角色权限配置 GET /admin/v1/roles，PUT /admin/v1/roles/{role_id}/permissions

财务管理

页面 核心 API
充值订单 GET /admin/v1/orders
退款审批 POST /admin/v1/orders/{order_id}/refund
交易流水 GET /admin/v1/transactions
手动余额调整 POST /admin/v1/wallet/adjust
对账管理 POST /admin/v1/accounting/reconciliation
开票审核 GET /admin/v1/accounting/vat-invoices，处理/拒绝
月度账单 GET /admin/v1/billing/invoices

模型管理

页面 核心 API
提供商配置 GET /admin/v1/model-providers，POST /admin/v1/model-providers/{id}/test
模型列表 GET /admin/v1/models，启用/禁用
模型定价 GET /admin/v1/tokens/pricing，PUT /admin/v1/tokens/pricing/{id}
限流规则 GET /admin/v1/models/rate-limits
降级策略 GET /admin/v1/models/fallback-rules
队列监控 GET /admin/v1/models/queue/stats

Token 管理

页面 核心 API
Token 定价配置 GET /admin/v1/tokens/pricing
第三方市场价 GET /admin/v1/tokens/market-prices
平台用量统计 GET /admin/v1/tokens/usage/top-users

会员与营销

页面 核心 API
套餐配置 GET /admin/v1/membership/plans，POST /admin/v1/membership/plans
活动管理 GET /admin/v1/marketing/campaigns
券类型配置 GET /admin/v1/marketing/voucher-types
批量生成券码 POST /admin/v1/marketing/voucher-codes/generate
自动发放规则 GET /admin/v1/marketing/distribution-rules
手动发放 POST /admin/v1/marketing/distribute

消息与通知

页面 核心 API
公告管理 GET /admin/v1/messages/announcements，发布/撤回
通知模板 GET /admin/v1/notifications/templates
广播消息 POST /admin/v1/notifications/broadcast
发送日志 GET /admin/v1/notifications/send-logs

系统与网关

页面 核心 API
路由规则 GET /admin/v1/gateway/routes
Webhook 配置 GET /admin/v1/gateway/webhooks
访问日志 GET /admin/v1/gateway/logs
审计日志 GET /admin/v1/gateway/audit-logs
管理员账号 GET /admin/v1/admins，POST /admin/v1/admins
操作日志 GET /admin/v1/system/operation-logs

4. 管理端专属接口

以下接口仅在 /admin/v1/ 下存在，对普通用户不可见：

方法 路径 说明
GET /admin/v1/stats/overview 平台运营总览
GET /admin/v1/stats/revenue 收入趋势
GET /admin/v1/stats/user-growth 用户增长趋势
PUT /admin/v1/users/{user_id}/freeze 冻结用户
PUT /admin/v1/users/{user_id}/unfreeze 解冻用户
PUT /admin/v1/users/{user_id}/reset-password 重置用户密码
PUT /admin/v1/enterprises/{id}/verify 审核通过企业认证
PUT /admin/v1/enterprises/{id}/reject 拒绝企业认证
POST /admin/v1/wallet/adjust 手动调整用户余额
GET /admin/v1/admins 管理员账号列表
POST /admin/v1/admins 创建管理员账号
PUT /admin/v1/admins/{id}/disable 禁用管理员账号
GET /admin/v1/system/operation-logs 管理员操作日志