# 主题分支功能同步任务

> 基于 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） |