# XuqmGroup Web 前端文档

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

## 工程结构

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

## 启动

```bash
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 | 应用详情（需登录） |
| `/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`）

```typescript
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

### 子账号管理（SubAccountView）

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

---

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

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

### 路由结构

| 路径 | 组件 | 说明 |
|------|------|------|
| `/login` | LoginView | 运营管理员登录 |
| `/tenants` | TenantListView | 租户列表（搜索/分页/启用禁用） |
| `/statistics` | StatisticsView | 数据统计 |

### 认证

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

### 租户管理功能

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

### 统计卡片

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

---

## 环境变量

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

```env
# 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）。

## 构建部署

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

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

Nginx 配置示例（SPA history 模式）：
```nginx
location / {
    try_files $uri $uri/ /index.html;
}

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