# Design: postmessage-duplex 通信层重构

## Context

当前系统使用原生 `postMessage` API 实现 SW 与应用层通信：
- 应用层 → SW：直接 `controller.postMessage()`
- SW → 应用层：`broadcastToClients()` 广播所有窗口

这种模式在多标签页场景下存在问题：
1. 多个页面同时提交相同任务，SW 的去重检查存在时间窗口
2. 广播消息所有页面都会收到，无法区分请求来源
3. 请求-响应模式需要手动用 RxJS 实现

## Goals / Non-Goals

### Goals
- 使用 postmessage-duplex 实现双工通信
- 解决多标签页任务重复问题
- 简化请求-响应模式的实现
- 保持向后兼容（渐进式迁移）

### Non-Goals
- 不改变现有业务逻辑
- 不改变 IndexedDB 存储结构
- 不改变任务执行流程

## Decisions

### 1. 通信架构

```
┌─────────────────┐        ┌──────────────────────┐        ┌─────────────────┐
│   Tab 1 (Page)  │        │    Service Worker    │        │   Tab 2 (Page)  │
├─────────────────┤        ├──────────────────────┤        ├─────────────────┤
│ ServiceWorker   │◄──────►│ Per-client channels  │◄──────►│ ServiceWorker   │
│ Channel         │  RPC   │ Map<clientId,Channel>│  RPC   │ Channel         │
└─────────────────┘        └──────────────────────┘        └─────────────────┘
```

- 每个页面创建独立的 `ServiceWorkerChannel`
- SW 端维护 `Map<clientId, channel>` 管理所有连接
- 请求-响应使用 `call` 方法，事件通知使用 `subscribe`

### 2. 消息类型划分

| 操作 | 当前方式 | 改造后方式 |
|------|---------|-----------|
| 任务创建 | postMessage + 监听 | `call('task:create', params)` → `{taskId, status}` |
| 任务取消 | postMessage | `call('task:cancel', {taskId})` → `{success}` |
| 任务重试 | postMessage | `call('task:retry', {taskId})` → `{success}` |
| 获取任务列表 | postMessage + timeout | `call('task:list')` → `{tasks}` |
| 任务状态变更 | broadcast | `subscribe('task:status')` |
| 任务完成 | broadcast | `subscribe('task:completed')` |
| Chat 流式 | broadcast | `subscribe('chat:chunk')` |

### 3. 任务创建流程改造

**当前流程**：
```
1. 应用层生成 taskId
2. 本地创建任务（乐观更新）
3. postMessage 到 SW
4. SW 检查重复，可能拒绝
5. 广播 TASK_CREATED
```

**改造后流程**：
```
1. 应用层调用 channel.call('task:create', params)
2. SW 检查重复
   - 已存在：返回 {success: false, existingTaskId}
   - 新建：创建任务，返回 {success: true, task}
3. 应用层根据响应更新本地状态
4. SW 广播 task:created 给其他客户端（排除发起者）
```

### 4. 多页面同步

- SW 维护所有通道引用
- 当任务状态变更时，广播给所有订阅该事件的通道
- 每个通道独立订阅，避免重复处理

### 5. Service Worker 端集成

由于 SW 不支持直接 import npm 模块，有两种方案：

**方案 A（推荐）**：打包时内联
- 使用 Vite 的 `?inline` 或自定义打包将库代码内联到 SW

**方案 B**：复制核心代码
- 将 postmessage-duplex 的 SW 相关代码复制到项目中

选择 **方案 A**，在 SW 构建配置中处理。

## Risks / Trade-offs

| Risk | Mitigation |
|------|------------|
| SW 端集成复杂 | 使用打包工具处理，文档中有示例 |
| 迁移风险 | 渐进式迁移，保留旧消息类型兼容 |
| 库稳定性 | 库较新（v1.0.0），需关注 issues |

## Migration Plan

### Phase 1：基础设施
1. 安装 postmessage-duplex 依赖
2. 配置 SW 打包支持
3. 创建新的通信服务（与现有并存）

### Phase 2：核心功能迁移
1. 迁移任务创建为 call 模式
2. 迁移任务状态为 subscribe 模式
3. 迁移 Chat 流式为 subscribe 模式

### Phase 3：清理
1. 移除旧的 RxJS 订阅逻辑
2. 移除兼容代码
3. 更新文档

## Open Questions

1. SW 打包方式的具体实现细节？
   - 需要测试 Vite 对 SW 入口的打包行为
   
2. 是否需要支持消息压缩？
   - 当前任务数据量不大，暂不需要