# 架构

VRSub 是"为视频生成 VR 双眼字幕"的单体应用（WOV AI Workflow Platform 的
单机实现）：FastAPI 后端、工作流调度器与全部节点（提音 / 转写 / 翻译 /
ASS）在**同一个进程**内运行，不再启动子进程、不再走节点 HTTP 协议。
由原分布式多仓库（wov-api / wov-web / wov-sdk / wov-node-*）合并而来。

## 目录结构

```
vrsub/
├── src/wov_sdk/       # 协议数据模型（NodeManifest/InvokeRequest/InvokeResponse/
│                      #   WorkflowDefinition 等），与分布式版保持一致
├── src/wov_app/       # 应用层：main/config/db/registry/scheduler/batch/seed/routers
│   └── routers/       #   apps.py（用户端）、workflows.py（管理端）、batch.py（批量处理）
├── nodes/             # 进程内节点实现：echo/ffmpeg/whisper/llm/ass
├── manifests/         # 各节点清单 JSON（echo.json/ffmpeg.json/...）
├── workflows/         # 默认工作流定义 JSON（模型/链路均为数据，改模型不改代码）
├── web/               # 静态前端（index/tasks/admin/workflow + assets）
├── model/             # 本地 whisper 权重（gitignored）
├── data/              # SQLite + 上传/产物存储（gitignored）
├── docs/              # 设计与运维文档（本目录）
└── tests/             # 单元/API/冒烟测试（覆盖核心路径，不强制 100%）
```

## 核心机制

- **节点注册表**（`src/wov_app/registry.py`）：启动时把 `manifests/*.json` 与
  `nodes/*.py` 的 `invoke` 处理器静态注册到进程内字典，调度器按
  `node_type` 直接调用。协议数据模型不变，为将来回退分布式保留兼容桥梁。
- **调度器**（`src/wov_app/scheduler.py`）：后台线程轮询 SQLite 中的 QUEUED
  任务，按工作流 DAG 拓扑顺序调用节点，产物按
  `data/storage/runs/<run_id>/steps/<node_id>/` 落盘并登记到 artifacts 表。
- **前端**：由 FastAPI 静态挂载 `web/`，节点注册/实例管理页面已移除，
  仅保留应用中心、任务管理、批量处理、管理后台（工作流）与工作流编排。
- **工作流编排页（web/workflow.html）**：支持新建工作流（空表单预填演示模板），
  从列表"编辑"加载任一工作流的最新定义（ID 锁定，保存即追加新版本）；"版本"
  查看全部历史版本并可"加载到编辑器"（对比/回滚后另存新版本）；管理后台
  （admin.html）无编辑器，点"编辑"自动跳转 `workflow.html?edit=<id>` 加载。
- **批量引擎**（`src/wov_app/batch.py`）：独立的单线程轮询线程处理
  `source=batch` 的运行，与主调度器互不抢占；详见
  [operations.md](./operations.md#文件夹批量处理)。

## 关键设计约束（北极星不变式）

- 节点之间不直接调用，只通过产物 URI 交换数据；中间产物落在共享存储
  （`data/storage`），不放在节点模块内部。
- 工作流必须是数据文件或数据库记录（workflow_versions 表存 DAG JSON），
  不允许把步骤顺序写死在应用代码里。
- 节点注册表是节点调用的唯一入口；API 与调度器不绕过 registry 直接执行
  节点逻辑。
- 协议数据模型（wov_sdk）要长期稳定，宁可先少做功能，也不轻易改协议。
- 存储、队列、调度器都要通过抽象边界隔离，方便从单机实现替换为分布式实现。
- 用户端永远只看到"输入 -> 进度 -> 结果"，不暴露工作流细节。
- 单体对分布式版的三处降级：无子进程隔离、无空闲 TTL 回收（模型常驻，
  仅懒加载）、非 OCR 慢任务无法强制中断（由节点自身超时兜底；OCR 节点支持
  暂停信号逐帧中断）。

## 单体化说明

- 由原 7 个独立仓库合并：wov-api、wov-web、wov-sdk、wov-node-echo、
  wov-node-ffmpeg、wov-node-whisper、wov-node-llm、wov-node-ass。
- 删除内容：`NodeManager`（子进程生命周期）、节点 HTTP 服务端
  （`wov_sdk.server`）、节点注册/实例管理 API 与页面、node_instances 表、
  各节点的 `__main__` 进程入口。
- 保留内容：协议数据模型、工作流 DAG 数据化、调度拓扑执行、上传/进度/下载/
  重试 API、静态前端、SQLite Repository 层、本地优先模型加载。

## 相关文档

- 节点输入输出协议、模型权重解析：[node-protocol.md](./node-protocol.md)
- 内置工作流与参数约定：[workflows.md](./workflows.md)
- 环境变量与启动：[configuration.md](./configuration.md)
- 批量处理、暂停/继续、孤儿清理：[operations.md](./operations.md)
- 设计决策与事故记录：[decisions.md](./decisions.md)