# 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
  -> 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