zcode
264 lines
16 KiB
Markdown
264 lines
16 KiB
Markdown
# 手机端前端设计文档
|
||
|
||
> 日期：2026-06-15
|
||
> 仓库：gamegroup2（http://jiulu-gameplay.com.cn:13001/congsh/gamegroup2.git）
|
||
> 状态：已确认，待实施
|
||
|
||
## 1. 目标
|
||
|
||
为现有 Game Group V2（游戏组队管理平台）增加完整的手机端前端，使移动设备用户通过手机浏览器即可使用全部功能。手机端与桌面端共存于同一项目、同一域名、同一后端，访问时根据设备自动分流。
|
||
|
||
**成功标准**：手机浏览器打开 `http://192.168.1.14:7033`（Dev）/ `7034`（UAT），自动进入手机版界面，可完成登录、群组管理、组队、投票、竞猜、账本、资产、黑名单、回忆、游戏库等全部现有功能，交互符合移动端操作习惯。
|
||
|
||
## 2. 技术决策
|
||
|
||
### 2.1 方案：单项目双视图层 + 路由分流
|
||
|
||
在现有 `frontend` 项目内新增手机端视图层，与桌面端共存：
|
||
|
||
- **共享层（零改动，手机端直接复用）**：`api/`（PocketBase 封装）、`stores/`（Pinia）、`types/`（接口定义）、`composables/`（useRealtime 等）、`assets/design.css`（设计系统变量）
|
||
- **桌面层（不动）**：现有 `views/`、`components/` 保持原样
|
||
- **手机层（全新）**：`views-mobile/`、`components-mobile/`、`mobile/`（布局与设备检测）
|
||
|
||
理由：业务逻辑全在前端、API 为标准 PocketBase SDK，共享层与 UI 无关；分成独立项目会导致 api/stores/types/composables 要么复制要么抽包，维护成本翻倍。单项目共享核心 + 双视图层是最低成本、最高复用的方案。
|
||
|
||
### 2.2 手机端组件库：Vant 4
|
||
|
||
引入 **Vant 4**（Vue 3 移动端组件库）作为手机端 UI 组件库。
|
||
|
||
- 现有 Element Plus 面向桌面（弹窗、表格、复杂表单），手机端的 Tabbar、ActionSheet、PullRefresh、Toast、SwipeCell、NavBar 等交互它不擅长
|
||
- Vant 专注移动端，与 Vite / Vue 3 / TypeScript 无缝集成
|
||
- 桌面端继续用 Element Plus，两套通过路由分流隔离，互不干扰
|
||
|
||
**新增依赖**：`vant@^4` + `@vant/auto-import-resolver`（Vant 按需引入插件，确保未使用的组件不打包进桌面端产物）
|
||
|
||
### 2.3 主题一致性
|
||
|
||
将 Vant 的 CSS 变量覆盖为现有 `design.css` 的 `--gg-*` 值，保证手机端与桌面端视觉统一：
|
||
- 主色 `--van-primary-color: var(--gg-primary)` (#059669)
|
||
- 背景色、文字色、圆角、阴影等全部映射到 `--gg-*` 对应变量
|
||
|
||
### 2.4 语音能力
|
||
|
||
手机端 VoiceRoom 做完整 UI（成员网格、控制条、房间布局），实际 WebRTC 连接与麦克风采集暂不接入。原因：非 HTTPS / 部分手机浏览器（如微信内置）限制 `mediaDevices`，桌面 Electron 端已遇到同类问题。
|
||
|
||
手机端语音房显示明确占位提示："语音功能请在 App 中使用"。完整语音能力待后续打包为原生 App（Capacitor / Tauri Mobile）时再接入。
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
frontend/src/
|
||
├─ api/ # 共享（PocketBase 封装，零改动）
|
||
├─ stores/ # 共享（Pinia，零改动）
|
||
├─ types/ # 共享（接口定义，零改动）
|
||
├─ composables/ # 共享（useRealtime 等，零改动）
|
||
├─ assets/
|
||
│ ├─ design.css # 共享设计系统（桌面+手机）
|
||
│ └─ mobile.css # 手机端主题覆盖（Vant 变量映射）
|
||
├─ views/ # 桌面端页面（现有，不动）
|
||
├─ components/ # 桌面端组件（现有，不动）
|
||
├─ views-mobile/ # 手机端页面（全新）
|
||
├─ components-mobile/ # 手机端组件（全新）
|
||
├─ mobile/ # 手机端专用
|
||
│ ├─ MobileLayout.vue # 底部 Tab + 顶部栏 主布局
|
||
│ ├─ useDevice.ts # 设备检测 composable
|
||
│ └─ DeviceGuard.ts # 路由级设备分流
|
||
├─ router/
|
||
│ └─ index.ts # 改造：设备检测 + 分流
|
||
└─ main.ts # 改造：按需注册 Vant
|
||
```
|
||
|
||
## 4. 设备检测与路由分流
|
||
|
||
### 4.1 检测策略
|
||
|
||
- **主判据**：`navigator.userAgent` 匹配移动设备关键字（iPhone/Android/Windows Phone 等）
|
||
- **辅助判据**：`window.innerWidth <= 768`（覆盖平板竖屏）
|
||
- 检测结果在应用启动时执行一次，存入 `localStorage`（`device_mode`）避免重复检测
|
||
- 提供手动切换入口（设置页："切换到桌面版"），少数平板/桌面用户可能需要
|
||
|
||
### 4.2 路由结构
|
||
|
||
每个业务路由定义 `desktop` 和 `mobile` 两个组件，路由守卫根据设备模式返回对应组件：
|
||
|
||
```ts
|
||
// 示例：路由记录
|
||
{
|
||
path: '/group/:id',
|
||
name: 'GroupView',
|
||
meta: { requiresAuth: true },
|
||
component: () => isMobile()
|
||
? import('@/views-mobile/GroupViewMobile.vue')
|
||
: import('@/views/GroupView.vue')
|
||
}
|
||
```
|
||
|
||
- 登录态校验（`requiresAuth` / `requiresGuest`）逻辑不变
|
||
- 所有路由 URL 与桌面端完全一致（同一 `/group/:id`），只是加载的视图不同
|
||
- 切换设备模式后整页刷新以重新走路由解析
|
||
|
||
## 5. 手机端布局与导航
|
||
|
||
### 5.1 整体框架
|
||
|
||
```
|
||
┌──────────────────────────┐
|
||
│ ← 群组名 🔔(3) │ 顶部栏：返回 / 标题 / 通知
|
||
├──────────────────────────┤
|
||
│ │
|
||
│ 页面内容区 │
|
||
│ （下拉刷新、滚动） │
|
||
│ │
|
||
├──────────────────────────┤
|
||
│🏠首页 👥群组 🎮游戏 🔔通知 👤我│ 底部 5 Tab
|
||
└──────────────────────────┘
|
||
```
|
||
|
||
- **顶部栏（NavBar）**：左侧返回按钮（次级页面显示）、中间页面标题、右侧通知铃铛（带未读数徽标）
|
||
- **底部 Tab（Tabbar）**：5 个固定入口，单手拇指可达
|
||
- **内容区**：占满中间空间，支持下拉刷新（列表页）、无限滚动加载
|
||
|
||
### 5.2 底部 Tab 定义
|
||
|
||
| Tab | 图标 | 页面 | 说明 |
|
||
|-----|------|------|------|
|
||
| 首页 | home-o | HomeMobile | 状态 + 当前组队 + 我的群组 + 热门游戏 |
|
||
| 群组 | friends-o | GroupsMobile | 群组列表 + 创建/加入入口 |
|
||
| 游戏 | game-o | GamesLibraryMobile | 游戏库浏览 + 搜索 |
|
||
| 通知 | bell | NotificationsMobile | 全部站内通知（邀请/组队/入群） |
|
||
| 我的 | user-o | ProfileMobile | 个人信息 + 状态 + 设置 |
|
||
|
||
**投票、竞猜、账本、资产、黑名单、回忆、统计** 不占底部位置，通过群组详情内的标签栏进入（见 5.3）。
|
||
|
||
### 5.3 群组详情的子页面组织
|
||
|
||
群组详情（`GroupViewMobile`）承载桌面端 GroupView 的全部 Tab 内容，手机端用**可横滑的顶部标签栏**组织：
|
||
|
||
```
|
||
┌──────────────────────────┐
|
||
│ ← 群组名 [12人] [⚙] │
|
||
├──────────────────────────┤
|
||
│ 动态 投票 竞猜 回忆 → │ 可横滑标签（横向滚动）
|
||
├──────────────────────────┤
|
||
│ │
|
||
│ [当前标签内容] │
|
||
│ │
|
||
└──────────────────────────┘
|
||
（其余标签：成员 账本 资产 黑名单 统计）
|
||
```
|
||
|
||
- 9 个标签：动态 / 投票 / 竞猜 / 回忆 / 成员 / 账本 / 资产 / 黑名单 / 统计
|
||
- 首次进入默认「动态」Tab
|
||
- 横向可滑动，超出屏幕的标签左右滑出
|
||
- 群组级独立页面（账本 `/group/:id/ledger`、资产 `/group/:id/assets`、黑名单 `/group/:id/blacklist`）也可从标签进入，URL 保持一致以支持直接跳转和返回
|
||
|
||
## 6. 全部页面设计
|
||
|
||
### 6.1 认证
|
||
|
||
| 页面 | 文件 | 设计要点 |
|
||
|------|------|---------|
|
||
| 登录 | `views-mobile/LoginMobile.vue` | 全屏卡片式，顶部 Logo + 标语，大号输入框（昵称/邮箱/用户名 + 密码），主按钮全宽，底部"去注册"链接。键盘弹出时内容上推不遮挡。 |
|
||
| 注册 | `views-mobile/RegisterMobile.vue` | 步骤化表单：昵称 → 密码 → 确认密码。复用桌面端自动生成 username 的逻辑（`'u' + Date.now().toString(36) + random`）。 |
|
||
|
||
### 6.2 主功能
|
||
|
||
| 页面 | 文件 | 设计要点 |
|
||
|------|------|---------|
|
||
| 首页 | `views-mobile/HomeMobile.vue` | 顶部：当前用户状态卡片（在线/忙碌/离开 + 一键切换 + 状态备注）。中部：当前临时小组卡片（如有，显示成员头像 + 进入语音房按钮）。下方：我的群组横滑卡片列表（点击进群组详情）。底部：热门游戏横滑封面。无群组时显示引导卡（创建/加入）。 |
|
||
| 群组列表 | `views-mobile/GroupsMobile.vue` | 群组卡片纵向列表（群名 + 成员数 + 简介 + 未读标记），顶部右侧浮动「+」按钮弹出 ActionSheet（创建群组 / 加入群组）。下拉刷新。 |
|
||
| 群组详情 | `views-mobile/GroupViewMobile.vue` | 顶部群信息条（群名 / 成员数 / 群主 / 容量）+ 快捷操作（账本/资产/黑名单图标入口）+ 可横滑标签栏（见 5.3）。 |
|
||
| 语音房 | `views-mobile/VoiceRoomMobile.vue` | 成员头像大网格（2-3 列，显示麦克风开关状态、说话动效）。底部固定控制条（麦克风开关 / 静音 / 退出）。顶部显示房间名和在线人数。WebRTC 未接入时显示占位提示。 |
|
||
|
||
### 6.3 群组内功能（标签栏子页面）
|
||
|
||
| 功能 | 组件 | 设计要点 |
|
||
|------|------|---------|
|
||
| 动态 | `components-mobile/group/ActivityFeed.vue` | 当前组队状态卡 + 空闲成员列表 + 所有成员按状态分组列表。 |
|
||
| 投票 | `components-mobile/poll/PollListMobile.vue` + `PollDetailMobile.vue` | 卡片列表（标题 / 选项数 / 截止时间 / 状态），下拉刷新，点击进详情投票。创建投票走底部弹出表单。 |
|
||
| 竞猜 | `components-mobile/bet/BetListMobile.vue` + `BetDetailMobile.vue` | 卡片列表（标题 / 下注范围 / 截止时间 / 我的下注），点击进详情下注。结算展示结果。 |
|
||
| 回忆 | `components-mobile/memory/MemoryGridMobile.vue` | 九宫格图片视频缩略图，点击全屏浏览（支持滑动切换、捏合缩放）。上传走底部弹出（拍照/相册选择）。 |
|
||
| 成员 | `components-mobile/group/MemberListMobile.vue` | 按状态分组列表（头像 + 昵称 + 状态备注），群主可管理（踢人/审核入群）。 |
|
||
| 账本 | `views-mobile/LedgerMobile.vue` | 顶部月度汇总卡片（总收入/支出/结余），下方账目列表，右下角浮动「+」添加（弹出表单：金额/类型/备注）。 |
|
||
| 资产 | `views-mobile/AssetMobile.vue` | 资产卡片列表（名称 / 类型 / 当前持有者），点击查看详情 / 转移。 |
|
||
| 黑名单 | `views-mobile/BlacklistMobile.vue` | 顶部 Tab 切换「游戏黑名单 / 玩家黑名单」。游戏：卡片列表（游戏名 + 标签 + 备注）。玩家：列表（昵称 + 标签 + 备注）。 |
|
||
| 统计 | `components-mobile/stats/StatsPanelMobile.vue` | 桌面 GroupStatsPanel 的简化只读版，展示群组活跃度、游戏偏好等核心数据（图表用简化柱状/环形，避免手机端图表过密）。 |
|
||
|
||
### 6.4 全局页面
|
||
|
||
| 页面 | 文件 | 设计要点 |
|
||
|------|------|---------|
|
||
| 游戏库 | `views-mobile/GamesLibraryMobile.vue` | 顶部搜索栏，下方游戏封面瀑布流（2 列），点击弹出详情底部面板（封面 / 平台 / 标签 / 评论 / 收藏 / 发起组队）。 |
|
||
| 通知 | `views-mobile/NotificationsMobile.vue` | 全部通知列表（类型图标 + 内容 + 时间），按时间倒序，支持标记已读 / 接受 / 拒绝操作。下拉刷新。 |
|
||
| 个人中心 | `views-mobile/ProfileMobile.vue` | 头像 + 昵称 + 用户名，状态切换，积分余额，我的群组数 / 组队次数等数据，设置 / 更新日志 / 退出登录入口。 |
|
||
| 设置 | `views-mobile/SettingsMobile.vue` | 列表式设置项：通知开关、主题（预留）、切换到桌面版、关于。 |
|
||
| 更新日志 | `views-mobile/ChangelogMobile.vue` | 时间线列表展示版本更新记录。 |
|
||
|
||
## 7. 共享层改动说明
|
||
|
||
手机端零改动地复用以下现有代码：
|
||
|
||
| 层 | 内容 | 说明 |
|
||
|----|------|------|
|
||
| `api/pocketbase.ts` | PocketBase 单例、`getCurrentUser()`、`isAuthenticated()`、`logout()` | 手机端直接 import 使用 |
|
||
| `api/*` | users / groups / sessions / invitations / games / polls / bets / points / ledgers / assets / memories / notifications / gameBlacklist / playerBlacklist | 全部领域 API 封装，手机端复用 |
|
||
| `stores/*` | user / group / team / notification / poll / ledger / asset / memory | Pinia stores，组合式 API，手机端复用（UI 状态可按需扩展） |
|
||
| `composables/useRealtime.ts` | PocketBase 实时订阅管理 | 手机端复用，组件卸载自动清理 |
|
||
| `types/index.ts` | 全部接口定义 + `displayName()` + 状态映射常量 | 手机端复用 |
|
||
|
||
**桌面端代码零改动**：现有 `views/`、`components/` 保持原样，不影响桌面用户。
|
||
|
||
## 8. 构建与部署
|
||
|
||
- **Vite 构建合并**：手机端和桌面端在同一份构建产物中，路由层负责分流。Vant 按需引入（`@vant/auto-import-resolver`），不使用的组件不打包，避免桌面端访问时加载手机端组件库。
|
||
- **部署不变**：现有 `deploy-dev.sh` / `deploy-uat.sh` 流程不变，nginx 配置不变，同一端口同一域名同时服务两端。
|
||
- **环境变量**：`.env` 的 `VITE_PB_URL`、`VITE_PORT` 对两端同样生效。
|
||
|
||
## 9. 实施顺序
|
||
|
||
分 9 个阶段，每阶段产出可验证的成果（可在手机浏览器实测）：
|
||
|
||
1. **基础设施**：安装 Vant、设备检测（`useDevice`）、路由分流改造、`MobileLayout`（底部 Tab + 顶部栏）、`mobile.css` 主题覆盖
|
||
2. **认证**：LoginMobile + RegisterMobile（打通登录注册全流程）
|
||
3. **首页 + 群组列表**：HomeMobile + GroupsMobile（含创建/加入群组弹层）
|
||
4. **群组详情核心**：GroupViewMobile + 动态标签（组队状态 + 成员列表）+ 成员管理
|
||
5. **组队 + 语音房 UI**：发起组队、邀请、接受邀请、状态切换、VoiceRoomMobile（占位）
|
||
6. **投票 + 竞猜**：列表 + 详情 + 创建/下注 + 结算
|
||
7. **游戏库**：GamesLibraryMobile + 详情弹层 + 搜索
|
||
8. **账本 + 资产 + 黑名单**：三个管理类页面（列表 + 增删改 + 资产转移）
|
||
9. **回忆 + 统计 + 个人/设置/更新日志**：收尾页面
|
||
|
||
## 10. 不在本次范围内
|
||
|
||
以下事项明确排除，待后续迭代：
|
||
|
||
- **语音 WebRTC 实际接入**：手机端语音房仅做 UI 和占位提示，实际通话能力待打包为原生 App（Capacitor / Tauri Mobile）时实现
|
||
- **PWA / 离线支持**：本次不做离线缓存和可安装 Web App
|
||
- **推送通知（原生）**：本次仅做站内通知，App 级推送待后续
|
||
- **桌面端改动**：现有桌面端代码不做任何修改
|
||
|
||
## 11. 风险与缓解
|
||
|
||
| 风险 | 缓解 |
|
||
|------|------|
|
||
| Vant 与 Element Plus 样式冲突 | 两套组件库通过路由分流隔离，不同时挂载；Vant 主题变量全部覆盖为 `--gg-*` 值 |
|
||
| 手机端浏览器实时订阅稳定性 | 复用现有 `useRealtime`，组件卸载自动清理；移动端切后台时 PocketBase SSE 断连，回前台后自动重连（现有机制） |
|
||
| 构建体积增长 | Vant 按需引入，仅打包手机端实际用到的组件 |
|
||
| 微信内置浏览器限制 | 语音功能已有占位；如遇其他 API 限制（如某些路由 history 模式），预留 hash 模式降级方案 |
|
||
|
||
## 12. 验收标准
|
||
|
||
- [ ] 手机浏览器访问 Dev/UAT 自动进入手机版界面
|
||
- [ ] 桌面浏览器访问仍是原桌面版，行为不变
|
||
- [ ] 登录 / 注册 / 退出全流程正常
|
||
- [ ] 首页：状态切换、群组入口、当前组队卡片显示正常
|
||
- [ ] 群组详情：9 个标签全部可访问，数据正确
|
||
- [ ] 组队流程：发起 / 邀请 / 接受 / 状态流转正常
|
||
- [ ] 投票 / 竞猜：创建 / 参与 / 结算正常
|
||
- [ ] 账本 / 资产 / 黑名单：增删改查正常，资产转移正常
|
||
- [ ] 回忆：浏览 + 上传正常
|
||
- [ ] 游戏库：浏览 + 搜索 + 详情正常
|
||
- [ ] 通知：接收 / 标记已读 / 接受拒绝正常
|
||
- [ ] 个人中心 / 设置：状态切换、切换桌面版正常
|
||
- [ ] 语音房界面完整，占位提示明确
|