架构与数据流
漫剧工作台的模块职责与数据流
来源：
oceanway-drama仓库docs/architecture/overview.md，提交45524ef，2026-10-01 迁入文档站，正文未改动。工作台写于架构重建之前，其中提到的oceanway-contracts、Core 等已冻结，接入时以平台文档为准。
产品行为以标准 1.7.0为准。 本文说明当前模块和数据归属；配置见本地运行。
模块
| 模块 | 职责 | 实现入口 |
|---|---|---|
| Web 应用 | 路由、页面、草稿、阅读位置、助手和可靠提交 | App、路由 |
| 文档内核 | 文档校验、规范化、文本序列化、范围与指纹 | manju-document |
| 领域服务 | 项目、正文、资产、分镜、视频、任务和持久化 | HTTP、领域服务 |
| 正式契约 | 从服务生成类型、OpenAPI、路由和覆盖清单 | manju-contracts |
| HTTP 客户端 | 类型化请求、原操作重放、媒体与 SSE | manju-http-client |
| 工具 | 启动、隔离验收、输入保护和恢复 | scripts |
页面实现位于各自工作包；页面索引 连接 manifest、设计依据和 QA。共享组件与领域客户端分别放在 components 和 app。
编辑与保存
原始上传 → 当前分集/剧本文档 → 单集资产关联 → 当前分镜文档 → 视频段及画面描述
WorkbenchDocumentEditor 使用 Tiptap/ProseMirror 维护编辑、格式、选区和撤销。父页面负责自动保存、主动保存、 输入法保护、离开保护与回执处理。生产准备和剧本页共用同一单集正文。 文档内核提供统一序列化偏移，辅助镜头索引可以重建，完整文档是正文依据。 连续剧本的各集编辑器独立维护撤销栈，当前编辑器将操作栏渲染到页面顶部的共用宿主。 导航滚动恢复在剧本数据就绪后执行；对照切换保留当前集和阅读进度。
ModalLayer与 useModalDialog 统一原生弹窗、键盘循环和关闭焦点；尺寸和操作区域由 浮层样式约束。
保存形成服务修订。原始上传、模型原始结果、历史修订和生产快照具有独立身份。 当前空稿也是有效内容；读取时尊重当前 head。完整内容指纹记录格式， 实际生成输入指纹记录生产所用内容，具体字段定义见技术接入。
生产与结果
生成命令读取已保存内容，固定输入快照后创建 Run/Task/Attempt。 执行器调用 Provider，持久化原始结果，再登记候选。 图片和视频结果由用户选择；下载使用经服务校验的媒体引用。 导出清单记录视频段顺序以及修订、候选和媒体引用，供外部剪辑工具整理素材。
本地 Provider 返回明确标记的测试媒体。生产 Provider、身份、预算、审计、 存储、队列及 Studio Host 通过现有适配端口接入。
状态归属
| 状态 | 权威位置 | 浏览器职责 |
|---|---|---|
| 项目、文档、资产、视频修订与候选 | 领域服务及存储 | 读取、编辑、呈现 |
| 生成任务与原始结果 | Run/Task/Attempt 及结果存储 | 订阅、查询、显示恢复动作 |
| 未确认回执的命令 | 服务幂等记录与客户端 journal | 保留原请求身份、版本和完整 payload |
| 尚未保存的输入 | 页面草稿与恢复缓存 | 保留输入，显式处理版本冲突 |
| 助手会话、批注与待发送引用 | 当前助手持久化层 | 锚点映射、跨页恢复与显式发送 |
| 助手开关、入口位置、阅读位置 | 独立 UI 偏好 | 按项目/页面范围恢复 |
服务回执验证成功后才更新“已保存”。网络断开或响应丢失时，恢复流程复用原命令； 已确认完成后的真正重执行使用新的 Attempt。权限在提交及结果登记时分别核验。
持久化与兼容
本地启动使用 File，默认数据根为 .local/reference-service/data/。
PostgreSQL 实现使用数据库适配器
与迁移，事务与幂等回执由同一服务维护。
持久化记录按各自 schemaVersion 读取，兼容读取保留原始指纹与历史身份。
迁移和恢复先清点来源、建立独立检查点，再校验输入与输出。
File、SQL mock、独立 PostgreSQL 和平台联调的验证边界分别记录在 验收状态。