gamegroup2/docs/superpowers/specs/2026-06-18-mobile-frontend-redo-design.md

# 手机端前端（uat 重做）设计文档

> 日期：2026-06-18
> 仓库：gamegroup2
> 分支：`uat`（基于 `origin/uat`）
> 状态：已确认，待实施
> 背景：master 上已有 8 个移动端 commit（基于 6-15 设计），但基于**旧 master**，不知 uat 后续新增的 PC 端功能。本次在 uat 上**重新做**移动端：迁移 master 已写好的实现 + 适配 uat 的 PC 端变化 + 补全 uat 新增功能的移动端页面。

## 1. 目标与范围

**目标**：在 uat 分支上产出完整、可用的手机端前端，覆盖 uat PC 端的全部功能（含信息公示板、事件/活动、游戏库增强、邀请落地页等 uat 独有功能），手机浏览器访问自动进入移动版。

**做法**（用户已定）：
- **选项 A**：在 uat 上重新做整套移动端（不是直接 cherry-pick 8 个 commit）
- **"重新做"含义**：迁移 master 上已写好的 22 个移动端文件 + 基础设施，然后适配 uat 的 API/stores/types/router 变化，并补全 uat 独有功能的移动端页面。不从零写。
- **新功能覆盖**：全部覆盖（公示板浏览+发帖、事件浏览+创建、游戏库详情+评论+收藏+添加+导入、邀请落地页 2 个）
- **设备分流**：路由层分流（沿用 master 方案）
- **实施节奏**：分阶段提交，每阶段可验证

## 2. 与 master 移动端的差异（迁移适配点）

### 2.1 uat 相对 master 新增的 PC 端功能域（移动端需补）

| 功能域 | PC 端位置 | 移动端处理 |
|---|---|---|
| 信息公示板 (bulletin) | `components/bulletin/*` (4) + `api/bulletins.ts` | 新增 `components-mobile/bulletin/*` + 群组详情新增"公示板" tab |
| 事件/活动 (event) | `components/event/*` (3) + `api/events.ts` | 新增 `components-mobile/event/*` + 群组详情新增"活动" tab + 首页接入事件板 |
| 游戏库增强 | `components/game/*` (AddGame/GameDetail/GameForm/ImportGames) | GamesLibraryMobile 增加添加/导入入口；游戏详情面板增加评论+收藏 |
| 邀请落地页 | `views/JoinGroupPage.vue`、`JoinTeamPage.vue` | 新增 `views-mobile/JoinGroupPageMobile.vue`、`JoinTeamPageMobile.vue`，路由层分流 |

### 2.2 uat 相对 master 的基础设施变化（迁移要适配）

| 项 | master 移动端写法 | uat 现状 | 适配方式 |
|---|---|---|---|
| router/index.ts | 旧结构（无 JoinGroup/JoinTeam 路由） | 有 `JoinGroup`/`JoinTeam` 顶层路由 + Layout children 嵌套 | **在 uat router 基础上叠加**：每个路由 component 用 `isMobile()` 三元分流，保留 JoinGroup/JoinTeam |
| package.json deps | 仅 vant | uat 已有 `livekit-client`、`tailwindcss`、`vue-tsc` 等 | 迁移时仅追加 `vant@^4` + `@vant/auto-import-resolver`，不动其他 |
| vite.config.ts | master 已加 auto-import-resolver + 手动分包 | uat 是基础配置 | 迁移 master 的 vant 插件配置 + 在 uat 基础上追加 manualChunks（保留 uat 现有 proxy/alias） |
| index.html viewport | master 改为含 `maximum-scale=1, viewport-fit=cover` | uat 基础版 | 采用 master 版本（适配键盘弹起、刘海屏） |
| types/index.ts | 移动端引用的 Event/Bulletin 等类型 | uat 已新增这些类型 | 迁移代码直接复用 uat 的 types，无需改动 |

### 2.3 pocketbase 导出兼容性（已确认）

uat 的 `api/pocketbase.ts` 同时提供 **命名导出 `{ pb }`** 和 **默认导出 `pb`**。master 移动端代码用默认导入 `import pb from './pocketbase'` 兼容；bulletins.ts 用命名导入也兼容。**无需改动**。

## 3. 目录结构（uat 上最终形态）

```
frontend/src/
├─ api/                # 共享（uat 已有 events.ts/bulletins.ts/invitations.ts）
├─ stores/             # 共享
├─ types/              # 共享（uat 已含 Event/BulletinPost 等类型）
├─ composables/        # 共享
├─ assets/
│  ├─ design.css       # 共享
│  └─ mobile.css       # 迁移：Vant 主题映射
├─ views/              # uat PC 端（不动）
├─ components/         # uat PC 端（不动）
├─ views-mobile/       # 迁移 + 新增
│  ├─ LoginMobile.vue / RegisterMobile.vue / HomeMobile.vue / GroupsMobile.vue
│  ├─ GroupViewMobile.vue / VoiceRoomMobile.vue
│  ├─ GamesLibraryMobile.vue（增强：添加/导入入口）
│  ├─ LedgerMobile.vue / AssetMobile.vue / BlacklistMobile.vue
│  ├─ NotificationsMobile.vue / ProfileMobile.vue / SettingsMobile.vue / ChangelogMobile.vue
│  ├─ Placeholder.vue
│  └─ JoinGroupPageMobile.vue / JoinTeamPageMobile.vue  # 新增
├─ components-mobile/  # 迁移 + 新增
│  ├─ bet/BetListMobile.vue
│  ├─ poll/PollListMobile.vue
│  ├─ memory/MemoryGridMobile.vue
│  ├─ stats/StatsPanelMobile.vue
│  ├─ group/ActivityFeedMobile.vue / MemberListMobile.vue
│  ├─ game/GameDetailSheetMobile.vue  # 新增（详情底部面板）
│  ├─ game/AddGameSheetMobile.vue      # 新增（添加游戏）
│  ├─ game/ImportGamesSheetMobile.vue  # 新增（导入游戏）
│  ├─ bulletin/BulletinListMobile.vue   # 新增（公示板列表）
│  ├─ bulletin/BulletinPostSheetMobile.vue # 新增（发帖/详情）
│  ├─ event/EventListMobile.vue         # 新增（事件列表）
│  └─ event/CreateEventSheetMobile.vue  # 新增（创建事件）
├─ mobile/
│  ├─ MobileLayout.vue    # 迁移
│  ├─ useDevice.ts        # 迁移
│  └─ DeviceGuard.ts      # 迁移（若 master 有）
├─ router/index.ts        # 在 uat 基础上叠加 isMobile() 分流
└─ main.ts                # 追加 vant 按需注册 + mobile.css 引入
```

## 4. 实施阶段（11 个阶段，每阶段一次提交，可验证）

每个阶段完成后在 uat 提交，提交信息前缀 `feat(mobile): `。每阶段验证标准见各阶段说明。

### 阶段 1：基础设施迁移
**迁移内容**：
- `package.json`：追加 `vant@^4` + `@vant/auto-import-resolver`
- `vite.config.ts`：在 uat 配置基础上追加 Vant 自动导入 resolver + manualChunks 分包
- `src/assets/mobile.css`：迁移（Vant 主题变量映射到 `--gg-*`）
- `src/mobile/useDevice.ts`：迁移
- `src/mobile/MobileLayout.vue`：迁移（已去除 logout handler 的版本）
- `index.html`：viewport 改为含 `maximum-scale=1, viewport-fit=cover`
- `src/main.ts`：追加 `import 'vant/lib/index.css'` + `import './assets/mobile.css'` + vant 按需注册
- `src/router/index.ts`：在 uat 现有 router 上叠加——每个业务路由 component 改为 `isMobile() ? mobile : desktop`，保留 JoinGroup/JoinTeam 路由（也加分流）
- `src/views-mobile/Placeholder.vue`：迁移（占位页，让分流能跑起来）

**验证**：`npm install` + `npm run build` 通过；PC 浏览器访问仍是桌面版；移动 UA 访问看到 Placeholder。

### 阶段 2：认证
迁移 `LoginMobile.vue` + `RegisterMobile.vue`，适配 uat 的 user store / pocketbase API（已确认兼容）。
**验证**：手机 UA 访问 `/login`、`/register` 正常，登录注册全流程通。

### 阶段 3：首页 + 群组列表
迁移 `HomeMobile.vue` + `GroupsMobile.vue`。
**适配**：首页接入事件板（listEvents 调用 + 事件卡片展示），适配 uat 的 group store 字段变化。
**验证**：首页显示状态/群组/热门游戏/事件板；群组列表创建/加入正常。

### 阶段 4：群组详情核心
迁移 `GroupViewMobile.vue` + `components-mobile/group/ActivityFeedMobile.vue` + `MemberListMobile.vue`。
**适配**：标签栏结构对照 uat PC GroupView 的 tab 列表，预留"活动"和"公示板"两个新 tab 位置（阶段 10/11 填充）。
**验证**：群组详情 9 个原有标签可访问。

### 阶段 5：组队 + 语音房
迁移 `VoiceRoomMobile.vue` + 适配 uat 的 team store / TeamSessionPanel 相关逻辑（GameSelectDialog/InviteButton 等的移动端交互通过 ActionSheet 实现）。
**验证**：发起组队/邀请/接受/状态切换正常；语音房 UI 显示占位提示。

### 阶段 6：投票 + 竞猜
迁移 `components-mobile/poll/PollListMobile.vue` + `bet/BetListMobile.vue`，适配 uat 的 poll/bet store。
**验证**：创建/参与/结算正常。

### 阶段 7：游戏库增强
迁移 `GamesLibraryMobile.vue` + 新增 `components-mobile/game/GameDetailSheetMobile.vue`（详情底部面板：封面/平台/标签/评论/收藏/发起组队）、`AddGameSheetMobile.vue`、`ImportGamesSheetMobile.vue`。
**适配**：GamesLibraryMobile 增加添加/导入入口按钮，接 `api/games.ts` 的 create/import。
**验证**：浏览/搜索/详情/评论/收藏/添加/导入正常。

### 阶段 8：账本 + 资产 + 黑名单
迁移 `LedgerMobile.vue` + `AssetMobile.vue` + `BlacklistMobile.vue`。
**验证**：增删改查正常，资产转移正常。

### 阶段 9：回忆 + 统计 + 个人/设置/更新日志
迁移 `MemoryGridMobile.vue` + `StatsPanelMobile.vue` + `ProfileMobile.vue` + `SettingsMobile.vue` + `ChangelogMobile.vue`。
**适配**：Profile/Changelog 对照 uat v0.3.5/0.3.6 新数据。
**验证**：回忆上传/浏览正常；统计只读展示；个人/设置/日志正常。

### 阶段 10：信息公示板
新增 `components-mobile/bulletin/BulletinListMobile.vue`（置顶帖+普通列表）+ `BulletinPostSheetMobile.vue`（发帖/查看详情）。
集成：群组详情标签栏新增"公示板" tab（接 `api/bulletins.ts`）。
**验证**：群内发帖/置顶/浏览正常。

### 阶段 11：事件 + 邀请落地页
新增 `components-mobile/event/EventListMobile.vue` + `CreateEventSheetMobile.vue`；群组详情新增"活动" tab；首页事件板（阶段 3 已接）的事件卡片点击进事件详情。
新增 `views-mobile/JoinGroupPageMobile.vue` + `JoinTeamPageMobile.vue`，路由层 `JoinGroup`/`JoinTeam` 加 `isMobile()` 分流。
**验证**：事件创建/RSVP/浏览正常；邀请链接手机端访问显示移动版落地页。

## 5. 验收标准

- [ ] PC 浏览器访问 uat 仍是桌面版，行为不变
- [ ] 手机浏览器访问 uat 自动进入移动版
- [ ] 登录/注册/退出全流程正常
- [ ] 首页：状态切换、群组入口、热门游戏、事件板正常
- [ ] 群组详情：9 个原有标签 + 活动 + 公示板 = 11 个标签可访问
- [ ] 组队/语音房占位 UI 正常
- [ ] 投票/竞猜：创建/参与/结算正常
- [ ] 游戏库：浏览/搜索/详情/评论/收藏/添加/导入正常
- [ ] 账本/资产/黑名单：增删改查 + 资产转移正常
- [ ] 回忆上传/浏览、统计只读正常
- [ ] 信息公示板：发帖/置顶/浏览正常
- [ ] 事件：创建/RSVP/浏览正常
- [ ] 邀请落地页：手机端访问 `/join/group/:id` 和 `/join/team/:id` 显示移动版
- [ ] `npm run build` 通过，无 TS 错误

## 6. 风险与缓解

| 风险 | 缓解 |
|---|---|
| uat 的 stores/types 与 master 移动端代码假设不符 | 阶段 1-9 迁移时逐阶段核对 `git diff master..HEAD` 的 stores/types 改动，按报错适配 |
| Vant + Element Plus 样式冲突 | 路由分流隔离，不同时挂载；mobile.css 已映射主题变量 |
| 邀请落地页在未登录态下访问，移动版守卫逻辑 | JoinGroup/JoinTeam 路由 meta 不加 requiresAuth（沿用 uat），分流只换组件 |
| 构建体积 | Vant 按需引入 + manualChunks 分包（master 已验证） |

## 7. 不在本次范围内

- 语音 WebRTC 实际接入（移动端仅 UI + 占位）
- PWA / 离线支持
- 原生推送通知
- 桌面端代码改动