biliup-next/docs/architecture.md

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

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

created
  -> running
  -> transcribed
  -> running
  -> songs_detected
  -> running
  -> split_done
  -> running
  -> published
  -> running
  -> commented
  -> running
  -> collection_synced

失败状态不结束任务，而是转入：

• failed_retryable
• failed_manual

Data Ownership

• SQLite：任务、步骤、产物索引、配置、审计记录
• 文件系统：视频、字幕、切片、AI 输出、日志
• 外部平台：B 站稿件、评论、合集

Key Design Rules

• 所有状态变更必须落库
• 模块间只通过领域对象和事件通信
• 外部依赖不可直接在业务模块中调用 shell 或 HTTP
• 配置统一由 core.config 读取
• 管理端展示的数据优先来自数据库，不直接从日志推断
• 工作区 flag 只表达交付副作用和产物标记，不作为 task 主状态事实源
• 配置系统必须 schema-first
• 插件系统必须 manifest-first