# Web 版弹弹play（媒体中心）— 设计规格

- **日期**：2026-09-25
- **状态**：已获设计批准，待实现计划（writing-plans）
- **仓库**：`app-template`（按**产品仓**维护，业务进入现有分层）

## 1. 背景与调研结论

弹弹play 官方定位是**本地视频 + 在线弹幕**的全功能播放器（非音乐播放器），能力包括智能识别、媒体库、AI 字幕、远程访问（浏览器可连 PC 内嵌 API）、媒体库可挂 SMB/WebDAV/Emby 等。

本项目要做的是：**独立 Web 应用**（方案 A），提供类似的「挂载源 → 浏览 → 播放 + 弹幕 → 媒体库/进度」体验，**不依赖**本机运行的 PC 弹弹play。

| 能力 | 决策 |
|------|------|
| 范围 | A — 独立完整 Web 应用 |
| 播放器 | ArtPlayer |
| 弹幕 | 对接弹弹play **开放弹幕网络**（服务端中继）+ 本地 XML 导入兜底 |
| 存储源 | **仅通用 WebDAV**（OpenList 使用其 WebDAV 端点；不做 OpenList 原生 API） |
| 后端 | 挂载代理 + 弹幕中继 + 媒体库/进度 **全做** |
| 刮削 | **Bangumi**：扫描自动匹配 + 手动搜索改绑（C） |
| UI | 全页面：播放 / 文件浏览 / 媒体库 / 挂载管理 / 弹幕设置 |
| 账号 | **多用户**：注册登录；每人独立库与进度 |
| 架构方案 | **A — 紧凑垂直切片 `media`**（复制 `user` 切片模式） |
| 视觉 | **shadcn/ui Dashboard** 风格（侧栏 + 卡片 + 中性灰阶），不以模板深空工业 HUD 为产品主视觉 |
| 落点 | **B — 产品化本仓**：业务进入 `app/web`、`packages/*` |

### 调研来源（Browser Use 实读）

- https://www.dandanplay.com/ — 产品能力与远程访问/WebDAV 叙述
- https://doc.dandanplay.com/open/library-api.html — PC 远程访问 REST（本项目**不**对接；仅作产品对照）
- https://doc.dandanplay.com/function/media-library.html — 媒体库信息架构参考
- https://github.com/OpenListTeam/OpenList — AList fork；本项目只用 **WebDAV** 接入方式

> 说明：会话内 IAB 不可用，调研经 `cua_repl` + `managed-chromium` 完成 SERP 与正文阅读。

## 2. 系统架构（方案 A）

```
浏览器 @app/web（React islands，shadcn dashboard）
  ├─ 登录 / 媒体库 / 文件浏览 / 播放(ArtPlayer+弹幕) / 挂载 / 弹幕设置
  └─ 仅经 tRPC 与 /api/stream（Range）访问
           │
           ▼
服务层 trpc + service + dao（@app/trpc · dao）
  ├─ mount.*     WebDAV 列目录、凭据加密、测试连接
  ├─ stream      Range 拉流代理
  ├─ danmaku.*   开放弹幕网络中继 + 缓存
  ├─ scrape.*    Bangumi 搜索/绑定；扫描内自动刮削
  ├─ library.*   扫描入库、列表、海报
  └─ playback.*  进度节流写入
           │
     ┌─────┴──────┐
     ▼            ▼
 Drizzle/Turso   外部：WebDAV · 弹弹play 开放弹幕网络 · Bangumi API
```

**分层约束（沿用仓库 AGENTS）**

- Schema 源：`@app/models`；查询：`@app/dao`；连接：`@app/db`
- 业务逻辑：`@app/trpc` service（调 dao）；入参 Zod：`@app/types`
- UI：`@app/ui` + design tokens；页面在 `@app/web`
- **产品化本仓**：新增业务实体照 `user` 垂直切片扩展（本产品期间业务代码进入现有分层，视为对「模板不掺业务」的产品化豁免）

### 播放主路径

1. 登录 → 2. 配置 WebDAV 挂载 → 3. 浏览目录或扫描入库  
4. 打开视频 → stream 代理 → ArtPlayer  
5. 识别/拉弹幕（中继 + `danmaku_cache`）→ 弹幕层  
6. 节流上报 `playback_progress`

### 首版不做

OpenList 原生 API · 本机弹弹play 远程 API 对接 · BT/RSS · 多刮削源 · NFO 优先 · 公网多租户硬化（SSO/套餐限流）

## 3. 数据模型

### users（已有 auth）

沿用模板用户表与会话，不重复造账号。

### mounts

| 字段 | 说明 |
|------|------|
| id | PK |
| userId | → users，级联隔离 |
| name | 展示名 |
| type | 固定 `webdav`（预留枚举） |
| baseUrl | WebDAV 根 URL（含 OpenList WebDAV 地址） |
| username | 可选 |
| secretEnc | **服务端加密**密文；API 永不回传明文 |
| rootPath | 根路径前缀 |
| enabled | 启用 |

### media_items

| 字段 | 说明 |
|------|------|
| id | PK |
| userId | 所属用户 |
| mountId | 可空（扫描所得） |
| path | 挂载内路径；`userId+path` 唯一 |
| rawName | 原始文件名 |
| title | 展示标题（可被刮削覆盖） |
| size / mime | 文件元数据 |
| bangumiId? | 刮削绑定 |
| epNumber? | 集数启发式 |
| scrapeStatus | `pending` \| `ok` \| `failed` \| `unmatched` |
| scrapedAt? | 最近刮削时间 |
| posterUrl? | 海报（Bangumi CDN 或占位） |
| matchedHash? | 弹幕匹配指纹（预留） |
| scannedAt | 入库时间 |

### playback_progress

`id · userId · mediaItemId · positionMs · durationMs · updatedAt`  
唯一：`(userId, mediaItemId)`。

### danmaku_cache（全局，不绑 user）

`id · matchKey · payload/xml · source · expiresAt`

### bangumi_cache（可选，限流）

`bangumiId · payload JSON · expiresAt`

### Zod（@app/types）

- `mountCreateSchema` / `mountUpdateSchema`
- `scanMountSchema` · `playbackReportSchema`
- `danmakuQuerySchema` · `danmakuImportMetaSchema`
- `scrapeSearchSchema` · `scrapeBindSchema`

## 4. 页面与交互

### 路由（shadcn dashboard 侧栏）

| 路径 | 页面 |
|------|------|
| `/login` `/register` | 认证（登录前仅此可见） |
| `/library` | 媒体库（默认登录后）：海报卡、筛选全部/未匹配、继续播放、扫描入口 |
| `/browse` | 文件浏览：选挂载 → 面包屑目录 → 行内播放/加入库 |
| `/watch` | 播放：ArtPlayer + 弹幕层 + 同目录剧集（可选）+ 弹幕开关/导入 XML |
| `/mounts` | 挂载管理：CRUD、测试连接、按挂载扫描 |
| `/danmaku` | 弹幕设置：默认开关/透明度/密度；导入说明 |

### 主流程

1. 注册/登录  
2. 挂载管理添加 WebDAV → 测试 → 保存  
3. 文件浏览点选播放，或「扫描」→ 刮削管线 → 媒体库  
4. `/watch`：stream → 弹幕中继 → 进度保存  
5. 媒体库「继续播放」带 progress 打开 `/watch`  
6. 未匹配项手动 Bangumi 搜索绑定；详情可重新刮削  

### 刮削管线（扫描）

1. 列目录，视频入 `media_items`  
2. 文件名启发式 → Bangumi 搜索  
3. 命中 → 写元数据/海报/`bangumiId`  
4. 低置信 → `unmatched`，UI 手动搜绑  
5. 重复扫描按指纹/缓存，避免打爆 Bangumi；**刮削失败不阻断入库**

### 视觉

- shadcn 风格组件语义：侧栏 nav、卡片、primary 按钮、Sheet 挂载表单、Dialog 确认、Toast  
- 可基于 `@app/ui` 对齐 shadcn API，产品主题为中性暗色 dashboard（非工业信号黄主视觉）  
- 动效克制，尊重 `prefers-reduced-motion`

## 5. 错误处理

| 场景 | 策略 |
|------|------|
| WebDAV 401/超时 | 明确文案；浏览 skeleton + 重试；引导改凭据 |
| stream 失败 | 播放器错误 + Toast；不暴露栈 |
| 弹幕网络失败 | 降级无弹幕，可播；可仅本地 XML |
| Bangumi 失败 | `scrapeStatus=failed`，可重试；不回滚文件 |
| 进度失败 | 静默重试，不打断播放 |
| 权限 | 所有 library/mount/progress 查询强制 `userId` |

## 6. 测试与验证

- types：Zod 单测  
- dao/service：进度 upsert、刮削绑定、路径规范化（mock HTTP）  
- tRPC：跨用户越权  
- web：主路径冒烟（登录→列表→播放页）；无 CI 浏览器则手动清单  
- 命令：`yarn typecheck` · `yarn lint` · `yarn build:web`  
- 不做重型视觉回归

## 7. 实现范围（一个计划可覆盖）

**In scope**

- media 垂直切片全栈（mount/stream/danmaku/scrape/library/playback）  
- 六个 UI 面（含登录沿用）  
- ArtPlayer 集成与弹幕层（开放网络 + XML 导入）  
- Bangumi 自动/手动刮削  
- shadcn dashboard 信息架构与主题  

**Out of scope（本规格）**

见 §2「首版不做」及 §1 调研中未选路径。

## 8. 风险与开放问题（实现前可再核）

1. **弹弹play 开放弹幕网络** 端点、鉴权与条款：实现时以官方文档/实测为准，service 单点适配  
2. **Bangumi API** 限流与字段：实现时核对官方 API 文档  
3. **WebDAV 流**：Range、HTTPS 混合内容、大文件内存——stream 用流式管道，禁止整文件缓冲  
4. 艺术墙纸/版权：用户自备片源与挂载凭据  

## 9. 批准记录

| 节 | 结果 |
|----|------|
| 架构 + shadcn dashboard | OK |
| 数据模型 | OK |
| 页面与交互 + Bangumi 刮削 C | OK |
| 错误/测试/边界 | OK |
| 方案选型 | A |