# Pawcast Implementation Roadmap

> **Plan type:** ROADMAP（总览，按 phase 拆分）
> **Detail plans:** 每个 Phase 单独一份 `2026-XX-XX-pawcast-phase-N-<name>.md`
> **Spec source:** `https://pawcast.catclaw.cat/pawcast-spec` + 9 份设计稿
> **Architecture doc:** `2026-05-02-pawcast-architecture.md`
> **Project root:** `/Users/luzhipeng/projects/pawcast`

**Goal:** 把 9 份设计稿落地成可在 macOS 上跑通的 Pawcast 应用——TikTok 团播工作台核心 4 大模块（计票 / 探索 / 私信 / 监控）+ 4 个直播挂件。

**Scope（v0.1 dev）：**
- ✅ 仅做**功能**，能在 macOS 开发机上完整跑通
- ✅ 数据 100% 本地（SQLite）
- ❌ **不做** license / 设备绑定 / 试用期 / 支付集成
- ❌ **不做** 多语言（写死中文）
- ❌ **不做** Windows 打包 / 自动更新 / CF 后端
- ❌ **不做** Stripe / 设备迁移流程

**Strategy:** 6 个 phase 顺序推进。每个 phase 独立可工作可测试。Phase 3 完成 = MVP 计票器可在 OBS demo。Phase 6 完成 = 全功能可用。

**Tech Stack 全栈定案：**
- **桌面壳**：Electron 30+，仅 macOS dev mode（`bun run dev`）
- **运行时**：Bun 1.2+（主进程 + 工具脚本）
- **前端**：React 19 + Vite 6 + Tailwind CSS 4 + Zustand + TanStack Query
- **数据库**：bun:sqlite（WAL 模式）
- **TikTok 采集**：tiktok-live-connector + Playwright 1.50+
- **AI**：Anthropic / OpenAI / Qwen-compatible SDK（用户填 API Key）
- **挂件 server**：Hono on Bun（主进程内嵌，监听 127.0.0.1:17777）
- **测试**：Vitest（单元 + 集成）
- **代码质量**：TypeScript strict + Biome（fmt + lint）

---

## Phase 依赖图

```
Phase 1 Foundation （Mac dev 跑空架子）
    └── Phase 2 采集层（TikTok WebCast + Playwright）
            ├── Phase 3 计票器（核心 MVP，可发 demo）
            │       └── Phase 4 Extras 挂件
            ├── Phase 5 探索主播
            │       └── Phase 6 私信中心（探索发现 → 邀约链路）
            └── Phase 7 直播监控
```

注：Phase 编号已重排，原 roadmap 的 Phase 8（发版）暂不做。

---

## Phase 1 · Foundation（基础架构）· 估 4-6 天

**准入条件**：本 roadmap 已被合伙人批准 + ARCHITECTURE.md 已落地。

**产物**：
- Electron + Bun + React 工程骨架，`bun run dev` 能开窗 + hot reload
- bun:sqlite 数据库初始化 + migrations 系统 + 初始 schema（10 张核心表）
- 主↔渲染 IPC（contextBridge 安全封装）+ 类型化 RPC
- Hono on Bun 起本地 17777，能 serve 一个 placeholder 挂件 HTML
- 5 Tab 主导航壳 + 设置中心壳（每个 tab 显示"开发中"）
- AI Key 配置可写入数据库（最小 settings 闭环）
- Vitest 测试基础设施 + 第一个 IPC 单元测试 + 第一个 DB 单元测试
- 本地启动脚本 `bun dev` 一键启动主进程 + Vite + 挂件 server

**准出条件**：
- ✅ `bun dev` 启动，Mac 上开窗，5 Tab + 设置 6 分区可切换
- ✅ `bun test` 跑过 ≥10 个基础测试
- ✅ AI Key 配置面板可保存，重启 App 能读出
- ✅ 浏览器访问 `http://127.0.0.1:17777/widget/hello` 能看到 placeholder HTML

**Phase 1 详细 plan**：`2026-05-02-pawcast-phase-1-foundation.md`

---

## Phase 2 · TikTok 采集层（协议封装）· 估 4-5 天

**准入条件**：Phase 1 已 merge。

**产物**：
- `tiktok-live-connector` 包封装 → 类型化 RoomConnection 类
- 多直播间并发管理器（最多 16 房并发）
- 30s 巡检 OFFLINE/LIVE 状态切换
- WebCast 事件流 → 内部 ND-JSON 协议 → IPC 推送到渲染层
- Playwright 启动器（弹窗 vs 静默两条线路）
- Cookie 加密存储（macOS Keychain）
- 录制器（所有 WebCast 事件 → JSONL，可回放）
- `gift_events / chat_events / like_events / pk_battles` 4 张表写入

**准出条件**：
- ✅ 输入一个真实 @username（用 testing 账号 @link8_kr），实时收到 gift / chat / like 事件
- ✅ 同时连接 8 个直播间不卡顿（CPU < 30%, RAM < 500MB）
- ✅ Playwright 弹窗模式能加载 TikTok 网页 + 保存 cookie 到 macOS Keychain
- ✅ 录制 1 小时事件流，能用回放工具复演

---

## Phase 3 · 计票器（5 玩法 + 共通挂件）· 估 8-12 天

**准入条件**：Phase 2 已 merge。

**产物**（v0.1 灵魂）：
- 玩法引擎抽象 + 5 实现：StickerDance / DuelDance / MultiPK / SoloStage / Freedom
- 礼物绑定引擎：单礼物绑定 + 多礼物绑定 + 手动分配
- 互动投票引擎：评论 + 点赞 → 票
- 12 预设系统（CRUD + 切换无重启）
- 团员库：跨预设共享主播
- Cast Setting / Workstation / Effects 配置面板
- 5 玩法运行态 UI（IDLE → COLLECTING → READY → RUNNING → SETTLING → DONE）
- 挂件输出页（5 玩法 widget HTML + 共通榜单 widget + 单轮榜 widget）
- WebSocket 推送增量到挂件页面
- .xlsx 导出（exceljs）
- Score Decay / A/B Carousel / Fever Time / 全屏特效

**准出条件**：
- ✅ 配置 Sticker Dance 6×3 预设，4 主播，4 礼物绑定
- ✅ 启动采集 + 开始 → OBS 浏览器源加载挂件 URL，看到实时礼物贴纸 + 数字跳动
- ✅ Duel Dance 1v1 跑通完整一轮
- ✅ 一场结束后导出 .xlsx，包含主播榜 + 用户榜 + 礼物明细
- ✅ 切换预设挂件无缝切换

---

## Phase 4 · Extras 挂件 · 估 3-4 天

**准入条件**：Phase 3 已 merge。

**产物**：
- Profile Border 头像框（20+ skins + 横/竖布局 + 多实例）
- Voting Tool 评论投票（2-10 选项 + 关键词匹配）
- Lucky Game 转盘（2-18 选项 + 4 skins + 10 套 config）
- Lucky Fans 观众抽奖（1-5 人/次 + 名单管理 + 中奖记录导出）

**准出条件**：
- ✅ 4 挂件都能 Copy URL → OBS 加载 → 直播画面看到
- ✅ Voting Tool 接到评论实时计票
- ✅ Lucky Fans 抽完导出 .xlsx 中奖名单

---

## Phase 5 · 探索主播 · 估 5-7 天

**准入条件**：Phase 2 已 merge。

**产物**：
- TikTok 关键词 / 话题搜索（Playwright 抓）
- 主播档案抓取
- 视频抽帧（ffmpeg）+ AI 视频内容理解（GPT-4o Vision）
- 7 维度评分
- 主播池存储 + 状态机
- 探索主页瀑布流 + 详情抽屉（雷达图 + 4 Tab）
- 启动扫描弹窗 + 进度推送

**准出条件**：
- ✅ 输入关键词扫描 50 位主播
- ✅ 30 分钟内完成所有评分
- ✅ 高潜卡片打开抽屉，看到雷达图 + AI 评语 + 视频列表

---

## Phase 6 · 私信中心 · 估 5-7 天

**准入条件**：Phase 2 + Phase 5 已 merge。

**产物**：
- DM 发送队列（in-memory + persisted） + 速率限制器
- 风控规避：cookie 健康检测 + captcha 检测 + 自动暂停
- AI 起草引擎（3 Provider 切换）
- 模板库 CRUD + 变量插槽 + A/B 变体
- 三栏对话 UI + AI 起草 banner
- 自动跟进策略
- 漏斗分析
- 批量发送（从 Explorer 跳过来）

**准出条件**：
- ✅ 选 1 主播 → 选模板 → AI 起草 → 采纳 → 进队列 → 3-7 分钟后实际发出
- ✅ 队列发完触发自动暂停
- ✅ 漏斗页正确计算转化率

---

## Phase 7 · 直播监控 · 估 4-6 天

**准入条件**：Phase 2 已 merge。

**产物**：
- 多房间网格 / 列表 / 紧凑视图
- 单房间详情（缩略图 + 实时数据 + 4 Tab）
- PK 战役识别 + 跟踪 + 比分时间线 + AI 胜率预测
- PK 复盘报告
- 跨房间 Heatmap + 观众迁移分析
- 告警规则引擎 + 系统通知 + Toast 队列
- 历史会话回放

**准出条件**：
- ✅ 同时盯 8 房间网格视图 60fps 流畅
- ✅ 进入 PK 自动弹通知 + 比分时间线实时跳
- ✅ 礼物速率破阈值弹告警

---

## 全程贯穿事项

| 项 | 说明 |
|---|---|
| **TDD 纪律** | 每个 task 先写测试，再写实现，再 commit。Vitest watch 模式 |
| **DRY** | 4 大模块共享 `tiktok-engine`、`ai-orchestrator`、`widget-server` 三个底层包（见 ARCHITECTURE.md） |
| **YAGNI** | 不做 license / 多语言 / Windows 打包 / 自动更新。功能优先 |
| **频繁 commit** | 每个 task 完成立即 commit，conventional commits 格式 |
| **Branch 策略** | 每个 phase 一个 feature branch，phase 完成开 PR 合并 |

---

## 工期估算（乐观 / 实际 / 悲观）

| Phase | 名称 | 乐观 | 实际 | 悲观 |
|---|---|---|---|---|
| 1 | Foundation | 4 | 6 | 8 |
| 2 | 采集层 | 4 | 5 | 7 |
| 3 | 计票器 | 8 | 12 | 18 |
| 4 | Extras | 3 | 4 | 6 |
| 5 | 探索主播 | 5 | 7 | 10 |
| 6 | 私信中心 | 5 | 7 | 10 |
| 7 | 直播监控 | 4 | 6 | 9 |
| **总** | | **33** | **47** | **68** |

约 **1.5-2 个月**到 v0.1 dev 全功能。Phase 1+2+3 跑通 = 3-4 周做 demo。

---

## 准出后（v0.2 之后再考虑）

发版 v0.1 dev 完成后，再回头考虑：
- v0.2: Windows 打包 / 自动更新
- v0.3: license / 试用期 / Stripe 支付 / 设备迁移
- v0.5: macOS 正式版（带签名公证） / 多语言扩展 / MCA 配置导入
- v1.0: 挂件市场 / 多平台支持