199 lines
3.1 KiB
Markdown
199 lines
3.1 KiB
Markdown
# 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
|