MBE Desktop 认证流程设计文档
📋 概述
本文档详细设计 MBE Desktop 的认证流程，包括首次启动注册、后续启动登录、以及用户后台展示。
🚀 启动流程
流程图
启动 MBE Desktop
↓
检查配置文件是否存在
↓
├─→ 不存在 → 显示注册页面
│ ↓
│ 用户注册
│ ↓
│ 保存凭证（加密）
│ ↓
│ 自动登录
│ ↓
│ 进入用户后台
│
└─→ 存在 → 读取保存的凭证
↓
显示登录页面（自动填充）
↓
用户点击登录
↓
验证凭证
↓
连接服务器
↓
进入用户后台
📝 详细设计
1. 首次启动 - 注册流程
1.1 注册页面 UI
窗口尺寸: 480px × 600px 居中显示: 屏幕中央
页面元素:
┌─────────────────────────────────────────┐
│ │
│ [MBE Desktop Logo] │
│ (64×64px) │
│ │
│ 欢迎使用 MBE Desktop │
│ AI驱动的行为智能引擎生态系统 │
│ │
│ ┌───────────────────────────────────┐ │
│ │ 创建账户 │ │
│ ├───────────────────────────────────┤ │
│ │ │ │
│ │ 邮箱 * │ │
│ │ [________________________] │ │
│ │ │ │
│ │ 密码 * │ │
│ │ [________________________] │ │
│ │ 至少8位，包含大小写字母和数字 │ │
│ │ │ │
│ │ 确认密码 * │ │
│ │ [________________________] │ │
│ │ │ │
│ │ 开发者类型（可选） │ │
│ │ ○ 应用开发者 │ │
│ │ ○ 专家创建者 │ │
│ │ ○ API用户 │ │
│ │ │ │
│ │ ☑ 我已阅读并同意 │ │
│ │ 《服务条款》和《隐私政策》 │ │
│ │ │ │
│ │ [注册并登录] │ │
│ │ │ │
│ └───────────────────────────────────┘ │
│ │
│ 注册即表示您同意我们的服务条款 │
│ │
└─────────────────────────────────────────┘
1.2 注册验证
前端验证:
- 邮箱格式验证（正则表达式）
- 密码长度验证（≥8位）
- 密码复杂度验证（大小写字母+数字）
- 密码一致性验证
- 服务条款确认
后端验证:
- 邮箱唯一性检查
- 密码哈希存储
- 创建用户账户
- 生成 API Key
- 返回 Token
1.3 注册成功处理
操作流程:
- 显示"注册成功"提示
- 获取开发者信息和 API Key:
POST /api/developer-feedback/register { "email": "user@example.com", "developer_name": "开发者名称", "developer_type": "expert_creator", # 或 "app_developer", "api_user" "organization": "组织名称（可选）" } 响应: { "success": true, "api_key": "mbe_xxx...", # 仅显示一次，需要保存 "developer_type": "expert_creator", "message": "注册成功" } - 重要: 提示用户保存 API Key（仅显示一次）
- 保存凭证到配置文件（加密）:
{ "user": { "email": "user@example.com", "password_encrypted": "encrypted_hash", "remember_password": true, "developer_type": "expert_creator", "developer_name": "开发者名称" }, "server": { "url": "https://mbe.hi-maker.com", "api_key": "mbe_encrypted_key_xxx..." }, "session": { "access_token": "jwt_token", "refresh_token": "refresh_token", "expires_at": "2026-02-07T10:30:00Z", "user_id": "user_123" } } - 自动登录（使用返回的 Token）
- 连接到服务器
- 根据开发者角色进入对应的控制台:
expert_creator→ 专家创建者工作台app_developer→ 应用开发者控制台api_user→ API 用户控制台
2. 后续启动 - 登录流程
2.1 登录页面 UI
窗口尺寸: 480px × 500px 居中显示: 屏幕中央
页面元素:
┌─────────────────────────────────────────┐
│ │
│ [MBE Desktop Logo] │
│ (64×64px) │
│ │
│ 欢迎回来 │
│ │
│ ┌───────────────────────────────────┐ │
│ │ 登录账户 │ │
│ ├───────────────────────────────────┤ │
│ │ │ │
│ │ 邮箱 │ │
│ │ [user@example.com____________] │ │
│ │ ↑ 自动填充（从配置文件读取） │ │
│ │ │ │
│ │ 密码 │ │
│ │ [••••••••••••••••] │ │
│ │ ↑ 自动填充（显示为圆点） │ │
│ │ │ │
│ │ ☑ 记住密码 │ │
│ │ ↑ 默认勾选 │ │
│ │ │ │
│ │ [登录] │ │
│ │ │ │
│ │ [忘记密码？] │ │
│ │ │ │
│ │ 没有账户？ [立即注册] │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ 连接信息 │ │
│ │ 服务器: https://mbe.hi-maker.com │ │
│ │ 状态: ⚠️ 未连接 │ │
│ │ [更改服务器] │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
2.2 自动填充逻辑
实现步骤:
- 启动时读取配置文件
- 如果存在
user.email和user.password_encrypted:- 填充邮箱字段（明文显示）
- 填充密码字段（显示为圆点
•） - 勾选"记住密码"复选框
- 如果不存在:
- 显示空表单
- "记住密码"默认勾选
密码显示:
- 自动填充的密码：显示为圆点（不显示明文）
- 用户手动输入：显示/隐藏切换按钮（眼睛图标）
2.3 登录验证流程
步骤:
- 用户点击"登录"按钮
- 显示加载状态:
[登录按钮] → [正在登录...] (禁用状态) - 发送登录请求:
POST /api/users/login { "email": "user@example.com", "password": "decrypted_password" } - 验证响应:
- 成功：获取 Token 和 API Key
- 失败：显示错误提示
2.4 登录成功处理
操作流程:
- 保存新的 Token 到配置文件
- 获取用户信息和开发者角色:
GET /api/developer-feedback/me Headers: Authorization: Bearer {access_token} 响应: { "user_id": "user_123", "email": "user@example.com", "developer_type": "expert_creator", # 或 "app_developer", "api_user" "api_key": "mbe_xxx...", "developer_name": "开发者名称" } - 保存 API Key 到配置文件（加密）
- 测试服务器连接:
GET /api/health Headers: Authorization: Bearer {access_token} - 连接成功:
- 更新状态栏显示"✅ 已连接"
- 根据开发者角色显示对应的控制台:
expert_creator→ 专家创建者工作台app_developer→ 应用开发者控制台api_user→ API 用户控制台
- 连接失败:
- 显示错误提示
- 提供重试按钮
3. 用户后台（开发者控制台）
重要说明: 用户后台即 MBE 系统的开发者门户/控制台，根据用户注册时选择的开发者角色显示不同的内容。
3.1 登录后获取用户角色
API 调用:
GET /api/developer-feedback/me
Headers: Authorization: Bearer {access_token}
响应:
{
"user_id": "user_123",
"email": "user@example.com",
"developer_type": "expert_creator", # 或 "app_developer", "api_user"
"api_key": "mbe_xxx...",
"developer_name": "开发者名称",
"organization": "组织名称（可选）"
}
角色类型:
expert_creator: 专家创建者app_developer: 应用开发者api_user: API 用户
3.2 专家创建者工作台（Expert Creator Dashboard）
窗口尺寸: 最小 1200px × 800px
布局结构:
┌─────────────────────────────────────────────────────────────┐
│ [MBE Desktop] [专家创建者工作台] [用户头像] [设置] [窗口控制] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────────────────────────────┐ │
│ │ │ │ 欢迎回来，user@example.com │ │
│ │ 侧边栏 │ │ 角色: 专家创建者 │ │
│ │ │ │ │ │
│ │ • 概览 │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ • 知识库 │ │ │知识库│ │专家 │ │调用 │ │收益 │ │ │
│ │ • 专家 │ │ │ 12 │ │ 8 │ │1,234│ │¥123 │ │ │
│ │ • 专家市场 │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │
│ │ • 收益 │ │ │ │
│ │ • API Key │ │ 最近活动: │ │
│ │ • 设置 │ │ • 2小时前 - 发布了专家"经济学导师" │ │
│ │ │ │ • 5小时前 - 上传了知识库"投资理财" │ │
│ │ │ │ • 昨天 - 专家"健身教练"被调用23次 │ │
│ └──────────┘ │ │ │
│ │ 快速操作: │ │
│ │ [创建知识库] [创建专家] [发布到市场] │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ✅ 已连接 | API Key: mbe_xxx... | 服务器: mbe.hi-maker.com │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
功能模块:
- 知识库管理: 创建、上传、训练、管理知识库
- 专家管理: 创建、训练、发布专家
- 专家市场: 发布、更新、下架专家到市场
- 使用统计: 专家调用次数、评分、用户反馈
- 收益查看: 专家收益、分成统计、结算记录
- API Key 管理: 查看、复制、重新生成 API Key
3.3 应用开发者控制台（App Developer Dashboard）
布局结构:
┌─────────────────────────────────────────────────────────────┐
│ [MBE Desktop] [应用开发者控制台] [用户头像] [设置] [窗口控制] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────────────────────────────┐ │
│ │ │ │ 欢迎回来，user@example.com │ │
│ │ 侧边栏 │ │ 角色: 应用开发者 │ │
│ │ │ │ │ │
│ │ • 概览 │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ • 应用开发 │ │ │应用 │ │API调用│ │专家 │ │收益 │ │ │
│ │ • 应用市场 │ │ │ 3 │ │1,234│ │ 6 │ │¥456 │ │ │
│ │ • 专家市场 │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │
│ │ • 收益 │ │ │ │
│ │ • SDK下载 │ │ 最近活动: │ │
│ │ • API Key │ │ • 2小时前 - 发布了应用"在线教育平台" │ │
│ │ • 设置 │ │ • 5小时前 - 集成了专家"经济学导师" │ │
│ │ │ │ • 昨天 - API调用了234次 │ │
│ └──────────┘ │ │ │
│ │ 快速操作: │ │
│ │ [新建应用] [浏览专家] [下载SDK] │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ✅ 已连接 | API Key: mbe_xxx... | 服务器: mbe.hi-maker.com │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
功能模块:
- 应用开发: 创建、编辑、测试应用项目
- 应用管理: 发布、更新应用到应用市场
- 专家市场: 浏览、选择专家集成到应用
- SDK 下载: Python、JavaScript、MCP Server 等
- 使用统计: API 调用次数、成功率、响应时间
- 收益查看: 应用收益、分成统计
- API Key 管理: 查看、复制、重新生成 API Key
3.4 API 用户控制台（API User Dashboard）
布局结构:
┌─────────────────────────────────────────────────────────────┐
│ [MBE Desktop] [API用户控制台] [用户头像] [设置] [窗口控制] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────────────────────────────┐ │
│ │ │ │ 欢迎回来，user@example.com │ │
│ │ 侧边栏 │ │ 角色: API用户 │ │
│ │ │ │ │ │
│ │ • 概览 │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ • API文档 │ │ │API调用│ │配额 │ │成功率│ │响应 │ │ │
│ │ • API测试 │ │ │1,234 │ │80% │ │99.5%│ │120ms│ │ │
│ │ • Webhook│ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │
│ │ • 批量操作│ │ │ │
│ │ • API Key│ │ 快速操作: │ │
│ │ • 设置 │ │ [查看API文档] [测试API] [配置Webhook] │ │
│ │ │ │ │ │
│ └──────────┘ │ API使用情况: │ │
│ │ • 今日调用: 234次 │ │
│ │ • 剩余配额: 7,766次 │ │
│ │ • 限流状态: 正常 │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ✅ 已连接 | API Key: mbe_xxx... | 服务器: mbe.hi-maker.com │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
功能模块:
- API 文档: 完整的 API 参考文档
- API 测试工具: 在线测试 API 调用
- Webhook 配置: 配置和管理 Webhook 端点
- 批量操作: 批量 API 调用工具
- 使用统计: 调用次数、配额、限流状态
- API Key 管理: 查看、复制、重新生成 API Key
3.5 用户信息显示
顶部栏用户信息:
- 用户头像（圆形，默认显示首字母）
- 用户邮箱/用户名
- 角色标识（专家创建者/应用开发者/API用户）
- 下拉菜单：
- 个人资料
- 账户设置
- 切换角色（如果用户有多个角色）
- 退出登录
3.6 连接状态管理
状态显示:
- ✅ 已连接：绿色指示器，显示服务器地址和 API Key（部分隐藏）
- ⚠️ 连接中：黄色指示器，显示"正在连接..."
- ❌ 未连接：红色指示器，显示"未连接"
自动重连:
- Token 过期时自动刷新
- 网络断开时自动重连
- 显示重连进度
🔐 安全设计
1. 密码存储
加密方式:
- 使用系统密钥加密（Windows: DPAPI, macOS: Keychain, Linux: Secret Service）
- 密码哈希存储在服务器端
- 本地仅存储加密后的密码（用于自动填充）
实现示例 (Python):
import keyring
import hashlib
import base64
def save_password(email: str, password: str):
"""保存密码到系统密钥库"""
service_name = "MBE Desktop"
keyring.set_password(service_name, email, password)
def get_password(email: str) -> str:
"""从系统密钥库获取密码"""
service_name = "MBE Desktop"
return keyring.get_password(service_name, email)
2. Token 管理
Token 存储:
- Access Token: 内存中（不持久化）
- Refresh Token: 加密存储在配置文件
- Token 过期时间: 30分钟（Access Token）
自动刷新:
- Token 过期前5分钟自动刷新
- 刷新失败时提示重新登录
3. 配置文件安全
文件权限:
- Windows: 仅当前用户可读
- macOS/Linux: 权限 600 (rw-------)
加密字段:
- 密码（加密存储）
- API Key（加密存储）
- Refresh Token（加密存储）
📋 配置文件格式
完整配置示例
{
"version": "1.0.0",
"user": {
"email": "user@example.com",
"remember_password": true,
"password_key": "keyring_service_key"
},
"server": {
"url": "https://mbe.hi-maker.com",
"api_key": "mbe_encrypted_key_xxx..."
},
"session": {
"access_token": "jwt_token_xxx...",
"refresh_token": "refresh_token_xxx...",
"expires_at": "2026-02-07T10:30:00Z",
"user_id": "user_123"
},
"app": {
"theme": "light",
"language": "zh-CN",
"window_size": [1200, 800],
"window_position": [100, 100],
"sidebar_collapsed": false
},
"last_login": "2026-02-06T10:30:00Z"
}
🔄 错误处理
1. 登录失败
错误类型:
- 邮箱或密码错误
- 网络连接失败
- 服务器不可用
- Token 无效
处理方式:
- 显示友好的错误提示
- 提供重试按钮
- 提供"忘记密码"链接
- 记录错误日志
2. 连接失败
处理流程:
- 显示连接状态为"❌ 未连接"
- 提示用户检查网络
- 提供"重试连接"按钮
- 自动重试（每30秒，最多3次）
3. Token 过期
处理流程:
- 检测到 Token 过期
- 使用 Refresh Token 自动刷新
- 刷新成功：继续使用
- 刷新失败：提示重新登录
🎯 用户体验优化
1. 加载状态
登录过程:
- 显示加载动画
- 禁用登录按钮
- 显示"正在登录..."文字
连接过程:
- 状态栏显示"连接中..."
- 显示进度指示器
2. 自动填充优化
密码字段:
- 自动填充时显示为圆点
- 用户点击后可切换显示/隐藏
- 提供"清除"按钮
邮箱字段:
- 自动填充后高亮显示
- 用户可以修改
- 提供下拉历史记录（可选）
3. 记住密码选项
行为:
- 默认勾选
- 取消勾选时：清除保存的密码
- 重新勾选时：提示输入密码并保存
📝 实施检查清单
认证流程
- 启动检测逻辑
- 注册页面 UI
- 登录页面 UI
- 自动填充功能
- 密码加密存储
- Token 管理
- 自动刷新 Token
- 错误处理
用户后台（开发者控制台）
- 角色检测和路由
- 专家创建者工作台
- 应用开发者控制台
- API 用户控制台
- 用户信息显示（含角色标识）
- 连接状态管理
- 自动重连机制
- API Key 管理界面
配置文件
- 配置文件读写
- 加密/解密功能
- 文件权限设置
- 配置迁移（版本升级）
文档创建日期：2026-02-06
最后更新：2026-02-06