# 工单：KMC 审读页 v3 → KAP 无限画布 集成方案调研（只读分析）

## 0. 任务性质
**只读调研 + 方案设计。禁改任何代码、禁 build、禁 deploy。唯一允许写入 = 本工单指定的报告文件。**
产出：集成方案报告（含三选一论证 + 字段映射表 + 落地改动清单）。

## 1. 背景（实测锚点，直接采用勿重新推导）

### 1a. 被集成对象：KMC 审读页 v3（本仓 kais-hermes-skills，主干已合 fe48b3fd）
- 渲染器 `skills/kais-movie-pipeline/pipeline/preview_html.py`：纯函数
  `build_review_html(filmstrip, table_read, meta, frames=None) -> str`，零 JS/零外链单文件 HTML
- 设计三支柱：① 首尾帧明面（每镜 起|止 帧对缩略+角标，无交互可见）② 胶片×TableRead
  纵轴融合（左列时间 gutter 起止时刻+时长比例条 / 中列帧对 / 右列镜号+景别chip+台词情绪运镜）
  ③ 顶部全片节奏总览条（格宽∝时长、位置=真实累计时间）
- 数据契约（preview_html.py 模块 docstring）：filmstrip.shots[]（shot_id/duration_sec/shot_type/
  framing/pacing/scene/timeline/dialogue_len/camera_movement）+ aggregate（total/per_scene_cut_density/
  pacing_histogram/flags）+ table_read[]（seq/shot_id/cum_start_sec/duration_sec/text/emotion）+ frames{shot_id:{first_uri,last_uri}}
- CLI 数据生产者：`skills/kais-movie-pipeline/scripts/build_review_page.py`（读 P09/P10/P11 资产拼契约）
- 真实样例：http://100.124.72.88:8082/2026-09-27/xjh_review_v3.html（39/40 帧、1.58MB、40 镜）

### 1b. 集成宿主：KAP 无限画布（/data/workspace/kais-aigc-platform，React Flow + Zustand 单页 SPA）
- ViewMode 联合类型 `packages/infinite-canvas/src/store/canvasStore.ts:39`：
  `'canvas' | 'timeline' | 'assets' | 'pipeline' | 'storyboard_board' | 'scene_shots' | 'reverse'`，默认 'assets'（:1344）
- 顶部 segmented 导航 `src/components/FlowCanvas.tsx:1140-1175`（ViewModeButton 组，handleSetViewMode）
- 新增全屏视图的既定模式：store 加 viewMode → 导航加按钮 → 条件渲染（⚠️ false 分支须 <>Fragment 包裹）
  → 新视图组件直接消费 `useCanvasStore(s => s.graph)` + `s.rawDataByNodeId`
- V3 graph storyboard 节点字段：meta.stage='storyboard' 下有 shotId/shotType/cameraMovement/framing/
  pacing/durationS/promptMeta；node.media.thumbnail/original/durationS；V2 穿透字段走 rawDataByNodeId
- 旧版 `src/components/StoryboardTimeline.tsx` 已消费 firstFrameUrl/lastFrameUrl（首尾帧展示先例）
- 部署链：`packages/infinite-canvas` 内 `npm run build` → cp dist/* 到 `data/web/infinite-canvas/` → :10588 静态生效（无需重启）

## 2. 必须规避的历史教训
- **Kai 07-18 铁律：外部能力不做画布节点 iframe 嵌入**——平台级全屏视图 + 数据交互，非节点内嵌
- build ≠ deploy：dist 产物与 data/web/ 是独立拷贝，改完必须 cp，否则 Kai 在 :10588 看不到变化
- 条件渲染 Fragment 陷阱（viewMode 分支多兄弟元素必须包 Fragment，否则 tsc 语法错）
- V3 保存污染：canvasToFlowGraph 会序列化合成节点——若你的方案涉及新节点类型需评估此坑；纯视图方案应规避
- 大部分项目无 V2 relational 数据（load-v2 返回 null），验证数据假设时用有 storyboard 节点的项目
- 画布是 live 多项目 SPA，审读页是单集静态产物——两者数据供给方式根本不同，这是本调研核心矛盾

## 3. 任务

### C1 集成形态三选一论证（报告主轴）
- A. 画布内新增 ViewMode（如 'review_read' 审读视图），React 重写 v3 设计，数据从 graph/live API 来
- B. 独立子路径 SPA（/review-read），story-map 先例：静态构建 + ?data= 喂数据，画布内放入口链接
- C. 其他你论证中发现的更优形态（如 ViewMode 轻壳 + iframe 指向生成的单文件——评估是否触碰 07-18 铁律精神）
- 每方案给：数据供给方式 / 改动面 / 与 v3 静态产物（含人审页 8082 交付链）的关系 / 维护成本 / 推荐度

### C2 数据映射表（承重交付，逐字段）
审读页契约字段 ↔ 画布侧真实来源：V3 graph meta / rawDataByNodeId / 后端 API（routes/ 下 canvas 或
production 相关）/ KMC episode 资产文件。逐字段标：✅已有 / 🔶改名可得 / ❌画布侧不存在（缺口）。
重点钉死：台词 text+emotion（P10 table_read）、cum_start_sec 累计时间、首尾帧 URI（画布 iframe 节点
的 firstFrameUrl/lastFrameUrl 与 KMC iframe-manifest 的关系）、flags 数据在画布侧是否可推导。
结论要回答：纯 live 数据能否喂饱 v3 全契约，还是必须「KMC 生成 JSON → 画布拉取」混合供给。

### C3 推荐方案落地清单
文件级改动清单（新增/修改哪些文件、各自职责、估行数）、部署链、验证步骤（浏览器+DOM 断言）、
工作量 S/M/L、风险清单。不写代码，但要细到另一批司机可照单施工。

### C4 设计移植策略
preview_html.py 的视觉体系（时间 gutter/帧对角标/7 槽色板 stN/总览条/场景分组）在 React+Tailwind
环境下的移植方式：直接 JSX 重写 vs 抽共享设计 token；色板六检结论如何携带；零 JS 约束在 React 里
自然满足，但 hover 增强等 CSS-only 技法是否保留。

## 4. 硬性证据约束
- 结论引用 文件:行号 或 契约字段名；禁止无证据推断；不确定标「待验证」
- C2 映射表每个 🔶/❌ 必须给出你实际查过的证据位置（grep 命令+结果摘要）
- 只读红线：不 build、不 install、不写仓库内任何文件；报告写 /tmp/reviewpage-integration-report.md
- 允许 curl 只读 :10588 API、读 episode 资产目录取证

## 5. 输出契约
报告 /tmp/reviewpage-integration-report.md：三选一对比表 + 明确推荐 + C2 映射表（全文，勿省略）+
C3 施工清单 + 风险。结尾 ≤300 字摘要（推荐方案 + 最大缺口 + 工作量）。