docs: 添加 theme-2/3/4 功能同步任务说明

记录 main 相对各主题分支的缺口、可原样同步范围、Player 端合并策略与验证清单。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-17 18:00:25 +08:00
parent f9343b00af
commit 633ff7b559
1 changed files with 221 additions and 0 deletions
--- a/docs/主题分支功能同步任务.md
+++ b/docs/主题分支功能同步任务.md
@@ -0,0 +1,221 @@
+# 主题分支功能同步任务
+
+> 基于 main 分支 commit `f9343b0`（站内邮箱、在线状态、员工菜单权限与内容管理增强）及前后关联提交的分析。  
+> **原则**：API / Admin / Shared 可原样同步；Player 端只做逻辑合并 + 各主题样式适配，**禁止**整文件从 main checkout 覆盖已有 player 页面。
+
+---
+
+## 分支现状
+
+| 分支 | 相对 main 缺失 | 已有等价功能 | 主题特征 |
+|------|----------------|--------------|----------|
+| **theme-2** | `f9343b0` 全部 + `f34fe54`（赛事搜索） | `9f1d263` ≈ `e9a23de` 的 admin/API/投注逻辑 | Pinnacle 蓝白浅色 |
+| **theme-3** | 同 theme-2 | `7832257` ≈ `e9a23de` | 统一移动端视觉 |
+| **theme-4** | 仅 `f9343b0` | `d3ca849` 已含 `e9a23de` 的 admin/API + 单串关 | 海军蓝暗色极简 |
+
+**结论**：三个 theme 分支都需要同步 **f9343b0**；theme-2/3 额外需要 **f34fe54** 的赛事搜索。`e9a23de` 在 theme 分支已通过 cherry-pick 或 `d3ca849` 覆盖，admin/API 侧无缺口。
+
+---
+
+## 任务清单
+
+- [ ] **sync-api-admin**：三个 theme 分支从 main checkout `apps/api`、`apps/admin`、`packages/shared/src/api-errors.ts`、相关 docs
+- [ ] **player-new-files**：复制 player 新文件（composables / views / components），按各 theme CSS 变量改样式
+- [ ] **player-merge-existing**：手工合并 MainLayout、BetSlipDrawer、HomeView、router、i18n 增量
+- [ ] **theme23-football-search**：theme-2/3 额外合并 `f34fe54` FootballView 赛事搜索逻辑
+- [ ] **verify-per-theme**：按分支跑 build + 邮箱 / 充值 / 菜单 / 在线 / 搜索功能验证
+
+---
+
+## 一、可直接整目录同步（三个分支相同）
+
+与玩家主题无关，**建议从 main 原样 checkout**：
+
+### API 全量（含迁移）
+
+- `apps/api/prisma/schema.prisma` + 迁移：
+  - `20260617083520_add_visible_menus`
+  - `20260617120000_player_messages`
+- 新域：
+  - `apps/api/src/domains/player-messages/`
+  - `apps/api/src/domains/presence/`
+- 主要改动：`admin.controller.ts`、`player.controller.ts`、`deposit.service.ts`、`admin-staff.service.ts`、`users.service.ts`、`system-config.service.ts`、`matches.service.ts`（含 `listUpcomingPublished`、`getSelectionsOdds`）、`content.service.ts` 及对应 spec
+
+**功能清单**：
+
+- 玩家站内消息 CRUD + 充值审核自动通知
+- Redis 在线心跳 + 管理端在线人数
+- 员工 `visibleMenus` + 删除保护
+- Inbox 系统配置（开关、充值 / Banner / 公告通知）
+- 待审充值 count API、home 返回 `inboxEnabled` / `upcomingMatches`
+
+### Admin 全量
+
+Admin 在 repo 内**不随 theme 分支分化**，以下全部同步：
+
+- 新组件：`AdminPlayerStatusCell.vue`、`ContentImageField.vue`、`ContentRichEditor.vue`
+- 新 composable：`useDepositPendingCount.ts`
+- 核心页面：`StaffManage.vue`（可见菜单勾选）、`Contents.vue`（富文本 + INBOX_NOTIFY 配置）、`ManageLayout.vue`（菜单过滤 + 充值角标）
+- 其它：`DashboardPlayers.vue`、`Users.vue`、`auth.ts`、全套 i18n
+- `App.vue` 中 Element Plus 链接按钮 hover 修复（管理端 UI 修复，非玩家主题）
+
+### Shared + 文档
+
+- `packages/shared/src/api-errors.ts`（及 `.js`）：`CANNOT_DELETE_SELF`、`STAFF_NOT_FOUND`、`MESSAGE_NOT_FOUND` 等
+- `docs/玩家端缺失功能分析.md`
+
+### 可选
+
+- 删除 `.agents/skills/**` — 与功能无关，可随 main 清理或保留
+
+---
+
+## 二、明确不同步（主题专属）
+
+| 路径 | 原因 |
+|------|------|
+| `apps/player/src/styles.css` | 各 theme CSS 变量不同（main 暗金 / theme-2 蓝白 / theme-4 海军白强调） |
+| `apps/player/index.html` | theme-color、meta 随主题 |
+| `apps/player/src/assets/**` | banner、empty 图、vs.png 等 |
+| 各 theme 已有 player 组件/页面样式 diff | BetSlipDrawer、ProfileView、WalletView 等布局与配色 |
+| theme-4 独有：`VsBadge.vue`、`WalletBalanceCard.vue`、`walletStats.ts` | theme-4 钱包 UX；**不要**同步 main 对这些文件的删除 |
+| theme-2/3 独有：`ec51b67` / `0d43085` 赛事详情 8px 间距 | 保留 |
+| `packages/shared/public/favicon.svg`、`site.webmanifest` | 品牌 / 主题资源，按分支保留 |
+
+---
+
+## 三、Player 端：逻辑合并 + 样式适配
+
+**禁止**对已有 player 文件执行 `git checkout main -- <file>` 整文件覆盖。
+
+### 3.1 新增文件（复制后做样式 pass）
+
+| 文件 | 说明 | 样式注意 |
+|------|------|----------|
+| `ConfirmDialog.vue` | 通用确认弹窗 | main 写死暗金渐变；theme-2 用 `--primary`/`--bg-card`；theme-4 用白色强调变量 |
+| `CustomerServicePanel.vue` | 客服面板 | 依赖 theme panel 样式 |
+| `MessageListPanel.vue` | 消息列表 | 含 `#141414`、`var(--gold)`；theme-2 无 `--gold` |
+| `InboxHubView.vue` | 邮箱中心 | 同上 |
+| `MessageDetailView.vue` | 消息详情 | 配合 `utils/html.ts` |
+| `AnnouncementListView.vue` | 公告列表 | 按 theme 变量写 scoped CSS |
+| `AnnouncementDetailView.vue` | 公告详情 | 同上 |
+| `useDepositNotifications.ts` | 充值结果轮询 | 纯逻辑，可直接复制 |
+| `useInboxFeature.ts` | 邮箱开关路由 | 纯逻辑 |
+| `usePlayerMessages.ts` | 消息 API | 纯逻辑 |
+| `usePresencePing.ts` | 在线心跳 | 纯逻辑 |
+| `utils/html.ts` | HTML sanitize | 纯逻辑 |
+
+**删除**：`CustomerServiceModal.vue`（三个 theme 均需删）
+
+### 3.2 已有文件 — 只合并 script / 路由 / 模板结构
+
+| 文件 | 需合并的功能 |
+|------|-------------|
+| `router/index.ts` | 新增 `announcements`、`announcements/:id`、`messages`、`messages/:id` |
+| `usePlayerHome.ts` | `homeRaw`、`upcomingMatches`、`announcementItems`、inbox 字段 |
+| `MainLayout.vue` | inbox/deposit/presence composables；Hub 替代客服 Modal；路由可见性规则；**保留 theme CSS** |
+| `BetSlipDrawer.vue` | 赔率轮询、`ConfirmDialog` 清空确认、`oddsDeltas` 变更提示 |
+| `betSlip.ts` | `updateSelectionOdds()`（theme-4 已有，theme-2/3 需补） |
+| `AnnouncementMarquee.vue` | 点击跳转 `/announcements/:id` |
+| `BannerCarousel.vue` | 推广链接行为 |
+| `HomeView.vue` | 近期赛事 Tab（`upcoming` / `upcomingMatches`） |
+| `FootballView.vue` | theme-2/3：`f34fe54` 搜索、`?search=`、双视图 |
+| `ProfileView.vue` | 邮箱 / 消息入口 |
+| `RechargeHistoryView.vue` / `RechargeView.vue` | minor 逻辑 |
+| `constants/defaultBanner.ts` | 删除硬编码 fallback |
+| i18n 三语文件 | **只合并新增 key**，勿覆盖 theme 已有文案 |
+
+### 3.3 功能数据流
+
+```mermaid
+flowchart LR
+  subgraph admin [Admin]
+    StaffManage[StaffManage visibleMenus]
+    Contents[Contents INBOX_NOTIFY]
+    DepositReview[Deposit approve/reject]
+  end
+  subgraph api [API]
+    PlayerMessages[player-messages]
+    Presence[presence Redis]
+    SystemConfig[inbox settings]
+  end
+  subgraph player [Player per theme]
+    MainLayout[MainLayout Hub]
+    InboxHub[InboxHubView]
+    PresencePing[presence ping]
+  end
+  StaffManage --> api
+  Contents --> SystemConfig
+  DepositReview --> PlayerMessages
+  SystemConfig --> MainLayout
+  PlayerMessages --> InboxHub
+  Presence --> PresencePing
+```
+
+---
+
+## 四、各分支差异要点
+
+### theme-2 / theme-3
+
+- **必做**：第一节 API/Admin/Shared + 第三节 Player 合并
+- **额外**：`f34fe54` 的 `FootballView.vue` 赛事搜索
+- **已有**：单串关 / 盘口状态 cherry-pick；admin `match-form.ts` 与 main 无 diff
+- **保留**：8px 间距 commit、各自 Pinnacle / 移动端样式
+
+### theme-4
+
+- **必做**：第一节 + 第三节（以 theme-4 组件结构为基准，如 WalletView、VsBadge）
+- **跳过或按需**：`f34fe54`（对比 FootballView 是否已有搜索）
+- **已有**：`d3ca849` 含 e9a23de + `updateSelectionOdds`
+- **注意**：不要同步 main 对 `WalletBalanceCard` / `VsBadge` 的删除
+
+---
+
+## 五、推荐操作顺序（每个 theme 分支）
+
+```bash
+git checkout theme-X
+git checkout main -- apps/api apps/admin packages/shared/src/api-errors.ts docs/玩家端缺失功能分析.md
+pnpm db:migrate
+pnpm --filter @thebet365/api test
+pnpm --filter @thebet365/admin build
+```
+
+随后按顺序：
+
+1. Player 纯逻辑文件（composables、utils、router、i18n 增量、删 Modal）
+2. Player 新 UI 文件（复制 + 按 `styles.css` 变量改 scoped CSS）
+3. Player 已有文件手工 merge（MainLayout → BetSlipDrawer → HomeView → FootballView）
+
+### 验证清单
+
+- [ ] 员工登录后侧栏按 `visibleMenus` 过滤
+- [ ] 充值审核后玩家收到站内信（开关打开时）
+- [ ] Hub 未读角标、公告详情、inbox 关闭时客服 fallback
+- [ ] 管理端在线人数、充值待审角标
+- [ ] theme-2/3：首页「近期」Tab、赛事页搜索
+- [ ] 投注单：清空确认、赔率变更提示
+
+---
+
+## 六、工作量与风险
+
+| 类别 | 文件约数 | 方式 | 风险 |
+|------|----------|------|------|
+| API + Admin + Shared | ~62 | 原样 checkout | 低 |
+| Player 新文件 + composables | ~15 | 复制 + 样式 pass | 中 |
+| Player 已有文件 merge | ~12 | 手工 | 高 |
+| **每个 theme 分支** | | | **约 2～4h**（theme-4 略少） |
+
+**不建议**对 theme 分支使用 `git merge main` 或 `git cherry-pick f9343b0` 整 commit — 会把 main 暗金 player 样式大量带入，冲突面超过 50 个 player 文件。
+
+---
+
+## 参考 commit
+
+| Commit | 说明 |
+|--------|------|
+| `f9343b0` | 站内邮箱、在线状态、员工菜单、内容管理增强（**三 theme 必同步**） |
+| `f34fe54` | FootballView 赛事搜索（**theme-2/3 额外**） |
+| `e9a23de` | 单串关持久化、盘口状态（theme 分支已 cherry-pick 或含于 d3ca849） |