init biliup-next

2026-04-01 00:44:58 +08:00
commit d0cf1fd0df
127 changed files with 15582 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -0,0 +1,198 @@
+# Architecture
+
+## Architecture Style
+
+采用模块化单体架构。
+
+原因：
+
+- 当前规模不需要微服务
+- 需要统一配置、状态和任务模型
+- 需要较低部署复杂度
+- 需要明确模块边界和未来插件扩展能力
+
+## High-Level Layers
+
+### 1. Core
+
+核心领域层，不依赖具体外部服务。
+
+- 领域模型
+- 状态机
+- 任务编排接口
+- 事件定义
+- 配置模型
+
+### 2. Modules
+
+业务模块层，每个模块只关心自己的一步能力。
+
+- `ingest`
+- `transcribe`
+- `song_detect`
+- `split`
+- `publish`
+- `comment`
+- `collection`
+
+### 3. Infra
+
+基础设施层，对外部依赖做适配。
+
+- 文件系统
+- SQLite 存储
+- Groq adapter
+- Codex adapter
+- FFmpeg adapter
+- Bili API adapter
+- biliup adapter
+- 日志与审计
+
+### 4. App
+
+应用层，对外暴露统一运行入口。
+
+- API Server
+- Worker
+- Scheduler
+- CLI
+- Admin Web
+
+## Proposed Directory Layout
+
+```text
+biliup-next/
+  src/
+    app/
+      api/
+      worker/
+      scheduler/
+      cli/
+    core/
+      models/
+      services/
+      events/
+      state_machine/
+      config/
+    modules/
+      ingest/
+      transcribe/
+      song_detect/
+      split/
+      publish/
+      comment/
+      collection/
+    infra/
+      db/
+      fs/
+      adapters/
+        groq/
+        codex/
+        ffmpeg/
+        bili/
+        biliup/
+      logging/
+    plugins/
+  docs/
+  tests/
+```
+
+## Runtime Components
+
+### API Server
+
+负责：
+
+- 配置管理
+- 任务查询
+- 手动操作
+- 日志聚合查询
+- 模块与插件可见性展示
+
+### Worker
+
+负责：
+
+- 消费任务
+- 推进状态机
+- 执行模块步骤
+
+### Scheduler
+
+负责：
+
+- 定时扫描待补偿任务
+- 定时同步外部状态
+- 触发重试
+
+## Control Plane
+
+新系统应明确区分控制面和数据面。
+
+### Control Plane
+
+负责：
+
+- 配置管理
+- 模块/插件注册
+- 任务可视化
+- 手动操作入口
+- 日志与诊断
+
+### Data Plane
+
+负责：
+
+- 实际执行转录
+- 实际执行识歌
+- 实际执行切歌
+- 实际执行上传
+- 实际执行评论和合集归档
+
+## Registry
+
+系统内部建立统一 registry，用于注册和查找模块能力。
+
+例如：
+
+- 当前转录 provider
+- 当前识歌 provider
+- 当前上传 provider
+- 当前合集策略
+
+核心模块只依赖抽象接口和 registry，不直接依赖具体实现。
+
+## Task Lifecycle
+
+```text
+created
+  -> ingested
+  -> transcribed
+  -> songs_detected
+  -> split_done
+  -> published
+  -> commented
+  -> collection_synced
+  -> completed
+```
+
+失败状态不结束任务，而是转入：
+
+- `failed_retryable`
+- `failed_manual`
+
+## Data Ownership
+
+- SQLite：任务、步骤、产物索引、配置、审计记录
+- 文件系统：视频、字幕、切片、AI 输出、日志
+- 外部平台：B 站稿件、评论、合集
+
+## Key Design Rules
+
+- 所有状态变更必须落库
+- 模块间只通过领域对象和事件通信
+- 外部依赖不可直接在业务模块中调用 shell 或 HTTP
+- 配置统一由 `core.config` 读取
+- 管理端展示的数据优先来自数据库，不直接从日志推断
+- 配置系统必须 schema-first
+- 插件系统必须 manifest-first