docs(spec): 导出会话聊天HTML(③,前端接线;后端 export.py 已就绪)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/superpowers/specs/2026-08-08-yunke-export-chat-html-design.md

@@ -0,0 +1,100 @@
+# 导出会话聊天为 HTML（③，前端接线）设计
+
+> 日期：2026-08-08｜分支：`feat/yunke-data-mirror`｜路线图 ③
+> 前置（已就绪）：后端 `GET /api/export/chat-html`（`app/api/routers/export.py`）已实现、已注册、有测试——按 (channel, owner_account_id, talker_id|room_id, start?, end?) 拉消息 → 渲染**自包含 HTML 气泡页**（is_send 左右、带时间/文本）→ `text/html` attachment 下载。
+> 数据/交互：全本地（运行时不碰云客）。云客「导出聊天记录」**2026-08-08 真机核实**：异步任务 → 下载中心（`POST /wechatweb/msg/exportChatData2Html`，参数 startdate/enddate/wechatId/friendId）。
+> 用户决策（2026-08-08）：**按我们的内部逻辑做**——不复刻云客的异步下载中心；HTML 渲染沿用已有 export.py（即"我们的逻辑"）。
+
+## 1. 目标与范围
+
+**目标**：在 3 处加「导出」入口，触发已有的 `/api/export/chat-html`，让用户把一段会话（员工×客户/群，可带日期窗）下载成 HTML 文件。
+
+**在本 plan（纯前端，后端不动）**：
+1. **ChatTimeline 头部「导出」按钮**：用当前会话（channel/owner/talkerId 或 roomId）+ 当前 dateRange（start/end）→ 下载该窗内聊天 HTML。仅在 `hasActive` 时可用。
+2. **CustomerList 操作列「导出HTML」**（在「查看聊天记录」旁）：该 owner×friend_id，**全量消息**（列表无日期选择器）。
+3. **GroupList 操作列「导出HTML」**：该 owner×room_id，全量消息。
+
+**机制（我们的内部逻辑）**：直接浏览器下载——构造 `/api/export/chat-html?...` URL，`window.open(url, '_blank')` 触发后端返回的 attachment 下载。**同步、无下载中心**（本地小工具；后端 attachment `Content-Disposition` 强制下载）。
+
+**不在本 plan**：
+- 云客的异步任务 / 下载中心（不需要）。
+- 导出多个会话 / 批量导出（云客也是单个会话导出）。
+- HTML 排版改版（沿用 export.py 现有渲染）。
+- 媒体字节内嵌（HTML 里媒体保持链接，不内嵌；export.py 现状）。
+
+## 2. 后端契约（已就绪，引用）
+
+`GET /api/export/chat-html`：
+- query：`channel`（wechat/whatsapp）、`owner_account_id`（必填）、`talker_id?`、`room_id?`（二选一）、`start?`、`end?`（ms-epoch，可省=全量）。
+- 返回：`text/html; charset=utf-8`，`Content-Disposition: attachment; filename="chat-...html"`。
+- 逻辑：DM 限定 `room_id` 空；按 timestamp asc；渲染气泡（is_send 右、否则左）。
+- 本 plan **不改后端**。
+
+## 3. 前端
+
+### 3.1 共用 URL 构造（`yunkes/src/api/index.ts`）
+```typescript
+/** 构造 /api/export/chat-html 下载 URL（浏览器直接下载，不走 getJson）。 */
+export function exportChatUrl(params: {
+  channel: Channel
+  owner_account_id: string
+  talker_id?: string
+  room_id?: string
+  start?: number
+  end?: number
+}): string {
+  const q = clean({
+    channel: params.channel,
+    owner_account_id: params.owner_account_id,
+    talker_id: params.talker_id,
+    room_id: params.room_id,
+    start: params.start,
+    end: params.end,
+  })
+  const usp = new URLSearchParams(q as Record<string, string>)
+  return `/api/export/chat-html?${usp.toString()}`
+}
+```
+> 触发下载：`window.open(exportChatUrl({...}), '_blank')`（attachment 强制下载；本地 viewer 无 api_token，window.open 可达）。
+
+### 3.2 ChatTimeline.vue
+- 头部 `.yk-chat__filters` 区（step 5 已建，含日期选择器/搜索）加「导出」`el-button`：`v-if="hasActive"`，`@click` → `window.open(exportChatUrl({channel: channelTyped, owner_account_id: props.ownerId, talker_id: props.talkerId, room_id: props.roomId, start: winStart, end: winEnd}))`。
+- 即「导出当前会话在当前日期窗内的聊天」。
+
+### 3.3 CustomerList.vue（操作列）
+- 在「查看聊天记录」按钮旁加 `<el-button link>导出HTML</el-button>`（wechat + WA 两 tab 的操作列）→ `window.open(exportChatUrl({channel: row.channel, owner_account_id: row.owner_account_id, talker_id: row.friend_id}))`（全量，无 start/end）。
+- plan 核实两 tab 操作列结构（Plan 2 已建「查看聊天记录」→ chat）。
+
+### 3.4 GroupList.vue（操作列）
+- 在「查看聊天记录」旁加「导出HTML」→ `exportChatUrl({channel: row.channel, owner_account_id: row.owner_account_id, room_id: row.room_id})`（全量）。
+
+## 4. 关键决策（已与用户确认 2026-08-08）
+
+1. **后端已就绪**（export.py），③ = 纯前端 3 处按钮接线。
+2. **同步直接下载**（`window.open` + attachment），不做云客异步下载中心。
+3. **HTML 渲染沿用 export.py**（我们的内部逻辑，不改）。
+4. **ChatTimeline 导出带 dateRange**；CustomerList/GroupList 导出**全量**（列表无日期选择器）。
+5. 媒体保持链接（export.py 现状）。
+
+## 5. 文件清单
+
+- 改 `yunkes/src/api/index.ts`（`exportChatUrl` helper）。
+- 改 `yunkes/src/views/ChatTimeline.vue`（头部「导出」按钮）。
+- 改 `yunkes/src/views/CustomerList.vue`（操作列「导出HTML」）。
+- 改 `yunkes/src/views/GroupList.vue`（操作列「导出HTML」）。
+- **无后端改动**；export.py 不动。
+
+## 6. 验收
+
+- `vue-tsc -b` exit 0。
+- **浏览器实测**（本地 smoke.db，无云客）：
+  - ChatTimeline：进一个会话 → 「导出」→ 下载 `chat-wechat-{owner}-{talker}.html`，打开含该窗内消息气泡（员工右/客户左、时间、文本）；改 dateRange 再导出 → 内容随窗变。
+  - CustomerList/GroupList：操作列「导出HTML」→ 下载该 owner×friend/room 的全量聊天 HTML。
+  - network：仅打 `/api/export/chat-html`（无云客）。
+
+## 7. 风险
+
+- **window.open 被拦截**：用户手势触发（button click）一般不拦；若拦可降级为隐藏 `<a download>` + `click()`。
+- **api_token 鉴权**：本地 viewer 默认无 token（require_auth no-op）→ window.open 可达；若启用 token 需改 fetch+blob（本 plan 不涉及，记录）。
+- **大对话导出耗时**：同步生成；超大对话可能慢，可接受（本地工具）；后续必要时再异步。
+- **CustomerList/GroupList 操作列结构**：plan 核实两 tab（wechat/WA）操作列「查看聊天记录」位置，照旁加按钮。