XuqmGroup Web 前端文档

当前推荐阅读入口：/docs/web/README.md
仓库内联调文档：docs/ACCESS.md
该文档保留为仓库内说明，线上访问地址、初始化管理员账号与最新前端联调信息请以最新文档为准。

Vue 3.5 · TypeScript · Vite 6 · Element Plus 2.9 · Pinia 3

工程结构

XuqmGroup-Web/
├── package.json            # Yarn Workspace 根配置
├── tenant-platform/        # 租户开放平台   :5173
└── ops-platform/           # 运营管理平台   :5174

启动

cd XuqmGroup-Web
yarn install

# 分别启动（两个终端）
yarn workspace tenant-platform dev
yarn workspace ops-platform dev

---

租户开放平台（tenant-platform）:5173

用户自助注册、管理应用、配置功能服务的对外平台。

路由结构

路径	组件	说明
/login	LoginView	登录（图形验证码）
/register	RegisterView	注册（邮箱验证码 60s 倒计时）
/forgot-password	ForgotPasswordView	忘记密码
/dashboard	DashboardView	控制台首页（需登录）
/apps	AppListView	应用列表（需登录）
/apps/:id	AppDetailView	应用详情（需登录）
/security	SecurityCenterView	安全中心（需登录）
/docs	DocsCenterView	接入文档（需登录）
/accounts	SubAccountView	子账号管理（需登录）

认证流程

登录 → POST /api/auth/login → 获得 JWT
↓
Pinia authStore.setToken(jwt)
↓
localStorage 持久化
↓
axios 拦截器自动附加 Authorization: Bearer <jwt>
↓
401 响应 → 清除 Token → 跳转 /login

API 模块（src/api/）

文件	接口	说明
auth.ts	authApi	验证码、注册、登录、找回密码
app.ts	appApi	应用 CRUD
account.ts	accountApi	子账号管理

Pinia Store

authStore（src/stores/auth.ts）

const auth = useAuthStore()

auth.token           // JWT 原始字符串
auth.payload.sub     // 租户 ID
auth.payload.username
auth.payload.nickname
auth.payload.type    // MAIN | SUB

auth.setToken(jwt)   // 登录后调用
auth.logout()        // 清除并跳转 /login

JWT Payload 由 atob(token.split('.')[1]) 解析，无需额外请求。

应用详情页（AppDetailView）

• 平台 Tab 切换：ANDROID / IOS / HARMONY
• 每个平台下显示 IM / 推送 / 版本管理 三个服务卡片
• 支持一键开关服务、复制 secretKey、重新生成 secretKey

安全中心 / 接入文档

• 安全中心提供 AppSecret 查看/重置入口，直接复用邮箱验证码流程
• 接入文档页提供 RN、Android / iOS 和服务端的最短接入示例

子账号管理（SubAccountView）

创建子账号两步流程：

1. 输入邮箱 → 发送验证码 → 验证通过（Redis 标记 24h 有效）
2. 填写账号信息 → 创建子账号

---

运营管理平台（ops-platform）:5174

内部使用，管理所有租户、查看统计数据。独立账号体系。

路由结构

路径	组件	说明
/login	LoginView	运营管理员登录
/tenants	TenantListView	租户列表（搜索/分页/启用禁用）
/tenants/:id	TenantDetailView	租户详情
/apps	AppListView	应用列表
/apps/:id	AppDetailView	应用详情
/statistics	StatisticsView	服务运营总览
/service-requests	ServiceRequestsView	服务开通审核
/operation-logs	OperationLogView	操作日志

认证

localStorage 存储 ops_token（与租户平台 token 隔离）。
API 请求通过 src/api/client.ts 中的 axios 实例统一附加，401 跳回 /login。

租户管理功能

• 关键词搜索（用户名/邮箱）
• 分页展示（每页 20 条）
• 类型标签：主账号（蓝色）/ 子账号（灰色）
• 状态标签：正常（绿色）/ 禁用（红色）
• 一键启用/禁用

统计卡片

指标	接口字段
总租户数	totalTenants
今日新增	todayNew
活跃应用	activeApps
在线用户	onlineUsers

---

环境变量

在各平台根目录创建 .env.local：

# tenant-platform
VITE_API_BASE_URL=https://api.xuqm.com/api

# ops-platform
VITE_API_BASE_URL=https://api.xuqm.com/api

未设置时默认代理到 http://localhost:8081（Vite dev server proxy）。

构建部署

# 构建
yarn workspace tenant-platform build
yarn workspace ops-platform build

# 产物在各平台的 dist/ 目录，部署至 Nginx 或 CDN

Nginx 配置示例（SPA history 模式）：

location / {
    try_files $uri $uri/ /index.html;
}

location /api/ {
    proxy_pass http://127.0.0.1:8081/api/;
}