# Module Contracts

## Goal

定义各模块的职责边界、输入输出和契约，避免旧系统中“脚本互相读目录、互相猜状态”的耦合方式。

## Contract Principles

- 每个模块只处理一类能力
- 模块只接收明确输入，不扫描全世界
- 模块输出必须结构化
- 模块不直接操控其他模块的内部实现
- 模块不直接依赖具体 provider

## Shared Concepts

所有模块统一围绕这些对象协作：

- `Task`
- `TaskStep`
- `Artifact`
- `Settings`
- `ProviderRef`

## Ingest Module

### Responsibility

- 接收文件输入
- 校验最小处理条件
- 创建任务

### Input

- 本地文件路径
- 当前配置

### Output

- `Task`
- `source_video` artifact

### Must Not Do

- 不直接转录
- 不写上传状态

## Transcribe Module

### Responsibility

- 调用转录 provider
- 生成字幕产物

### Input

- `Task`
- `source_video` artifact
- `transcribe` settings

### Output

- `subtitle_srt` artifact

### Must Not Do

- 不识别歌曲
- 不决定切歌策略

## Song Detect Module

### Responsibility

- 根据字幕识别歌曲
- 生成歌曲结构化结果

### Input

- `Task`
- `subtitle_srt` artifact
- `song_detect` settings

### Output

- `songs_json` artifact
- `songs_txt` artifact

### Must Not Do

- 不切歌
- 不上传

## Split Module

### Responsibility

- 根据歌曲列表切割纯享版片段

### Input

- `Task`
- `songs_json` artifact
- `source_video` artifact
- `split` settings

### Output

- 多个 `clip_video` artifact

## Publish Module

### Responsibility

- 上传纯享版视频
- 记录发布结果

### Input

- `Task`
- `clip_video[]`
- `publish` settings

### Output

- `PublishRecord`
- `publish_bvid` artifact

### Must Not Do

- 不负责评论文案生成
- 不负责合集匹配策略

## Comment Module

### Responsibility

- 发布并置顶评论

### Input

- `Task`
- `PublishRecord`
- `songs_txt` artifact
- `comment` settings

### Output

- `comment_record` artifact

## Collection Module

### Responsibility

- 根据策略同步合集 A / B

### Input

- `Task`
- `PublishRecord` 或外部 `full_video_bvid`
- `collection` settings
- `collection strategy`

### Output

- `CollectionBinding`

### Internal Sub-Strategies

- `full_video_collection_strategy`
- `song_collection_strategy`

## Provider Contracts

### TranscribeProvider

```text
transcribe(task, source_video, settings) -> subtitle_srt
```

### SongDetector

```text
detect(task, subtitle_srt, settings) -> songs_json, songs_txt
```

### PublishProvider

```text
publish(task, clip_videos, settings) -> PublishRecord
```

### CommentStrategy

```text
sync_comment(task, publish_record, songs_txt, settings) -> comment_record
```

### CollectionStrategy

```text
sync_collection(task, context, settings) -> CollectionBinding[]
```

## Orchestration Rules

模块本身不负责全局编排。

全局编排由任务引擎或 worker 负责：

- 判断下一步该跑什么
- 决定是否重试
- 写入状态
- 调度具体模块

## Error Contract

所有模块失败时应返回统一错误结构：

- `code`
- `message`
- `retryable`
- `details`

不得只返回原始字符串日志作为唯一错误结果。

## Non-Goals

- 模块之间不共享私有目录扫描逻辑
- 模块契约不直接暴露 shell 命令细节