## Context

桌面 StudyDeck（Tauri）已有资料库、playlist/combo、分屏 Study。儿童端需与家长端解耦：PC 组课并 Publish；iPad 只下载与学习。进度仅 iPad 本地。

约束：

- iPad 无组课、无资料库管理、无上传服务器主路径。
- 局域网、无鉴权、信任网络。
- 发布/下载 MVP 仅 `Album.mode === "combo"`。

## Goals / Non-Goals

**Goals:**

- PC Publish：清单 + zip 打包 + URL/QR。
- Course Pack 格式与 iPad 落盘。
- iPad HomeDeck → Download（粘贴/扫码）→ Study。
- PC Explorer 组课结果可进入发布清单。
- Study：方向自适应分屏、分割线拖拽、图标工具条、自动进度。

**Non-Goals:**

- 进度回传 / 云同步 / 账号。
- 首页未下载占位。
- playlist 发布、封面产品化、Bonjour 必选。
- `dual_*` StudyMode 产品化。
- 牛津树 frontend/backend 集成。

## Decisions

### D1. LAN 方向：PC 服务，iPad 拉取

桌面起只读 HTTP；iPad 粘贴或扫码 base URL 后拉清单与 pack。否决 iPad 作上传服务器。

### D2. 发布内容 = 已保存 combo album

- `GET /api/courses` 仅 `albums.json` 中 `mode === "combo"`。
- Explorer **Start**（可配对 combo）或课程草稿 **Start/Save** 时写入 album。
- 仅 Study Session、未保存草稿 **不**进入清单。
- 打开 Lesson 列表或拉发布清单时，可将「无 album 绑定的 combo Session」提升为 album（按 mode+资源去重），避免历史开课不可分享。

### D3. Course Pack

```
course-pack/
  manifest.json
  media/<id>.<ext>
```

- `GET /api/courses/:id/pack` → `application/zip`。
- 媒体条目优先 **Stored**（不 Deflate）：大视频已压缩，避免客户端轻量解压失败、并加快打包。
- `manifest.json` 可用 Deflate。缺媒体文件则 4xx。

### D4. Publish HTTP API

| Method | Path | 行为 |
|--------|------|------|
| GET | `/` | 简易 HTML 清单 |
| GET | `/api/health` | `{ ok, name: "studydeck-publish" }` |
| GET | `/api/courses` | combo 摘要数组 |
| GET | `/api/courses/:id` | 元数据 |
| GET | `/api/courses/:id/pack` | zip |

- 默认端口 `8787`，占用则递增重试；UI 显示 URL + QR；开关启停，退出停止。

### D5. iPad 信息架构

```
Root NavigationStack
├── HomeDeck
├── DownloadBrowser   # 菜单 → 添加课程
└── Study             # 全屏学习舞台
```

模型：`LocalCourse` + `StudySession`（progress）+ `AppSettings`（含上次 publish URL）。

### D6. HomeDeck

- 上：仅已下载课程横滑；空态 CTA → DownloadBrowser。
- 点课：开/续 Study，并置顶最近学习。
- 下：最近学习大卡横滑；封面 MVP 默认图。

### D7. 下载与扫码

1. 粘贴 `http://host:port` **或** 相机扫描 PC QR（内容为 base URL）。
2. `GET /api/courses`；失败提示开启电脑分享。
3. 勾选 → 下 pack → 解压 `Documents/courses/<id>/` → 登记 `LocalCourse`。
4. 同 id 且远端 `updatedAt` 更新则覆盖。
5. 需相机与本地网络权限；允许局域网明文 HTTP（ATS `NSAllowsLocalNetworking`）。

### D8. Study UX

- **方向**：由舞台宽高决定——宽≥高 → 左右分屏；否则上下分屏。不提供手动「左右/上下」切换。
- **比例**：拖拽舞台分割条调整 `splitRatio`；无 Slider。
- **右侧舞台**：工具条图标收起/展开第二屏（视频+PDF / PDF+音频等）。
- **PDF**：右上角上一页 / 下一页图标。
- **导航**：系统返回改为仅 chevron 图标；不展示 mode 文案条（如 `video + pdf`）；无「保存进度」按钮。
- **进度**：任意舞台交互（含翻页、拖分割线等）触发保存（短节流）；另 **每 60 秒**强制保存；离开页/进后台强制保存。字段含 mediaTime、pdfPage、splitRatio、orientation。

### D9. PC Explorer / Lesson（组课侧）

- Explorer 顶栏：路径在标题下；新建文件夹 / 导入文件 / 导入文件夹为图标按钮。
- `+` 新建专辑/课程：新 Tab **空草稿**；已选文件留在 inactive 的 selection Tab，切回可恢复高亮。
- 课程草稿：左侧勾选至可配对时 **自动追加** 一条 combo item。
- Lesson 卡片：Mac 双指点按/右键、Win 右键/长按 → 菜单（开始/继续、删除）。

### D10. 与 studydeck-ipad

产品上取代其对等四栏与上传服务器主路径；播放技术可复用。归档本 change 时再同步主 specs。

## Risks / Trade-offs

- 大课 zip 体积与磁盘 → 显示 byteSize；失败清理半包；媒体 Stored 降低解压风险。
- 无鉴权 LAN → UI 强提示信任网络。
- 货架无未下载占位 → 发现新课须进下载页。

## Migration Plan

1. PC：Publish 默认关；组课与分享同库。
2. iPad：儿童模型；旧库可迁移清空后重下课程。
3. 回滚：关 Publish；iPad 需重装旧包（BREAKING UI）。

## Resolved (former open questions)

- 多 item 课程：P0 可先列表再 Study；单 item 直开。
- QR：已支持相机扫码 + 粘贴。
- 端口冲突：8787 起递增并刷新 URL/QR。