congsh/gamegroup2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0b999eebb0926d7f3785b14362a11e71299551c6
gamegroup2/docs/superpowers/specs/2026-06-18-mobile-frontend-redo-design.md
T

11 KiB
Raw Blame History

手机端前端（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 / 离线支持
  • 原生推送通知
  • 桌面端代码改动
Reference in New Issue View Git Blame Copy Permalink