thebet365/docs/主题分支功能同步任务.md

主题分支功能同步任务

基于 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 功能数据流

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 分支）

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）