# Config System

## Design Goal

配置系统不是辅助功能，而是新系统的控制面基础设施。

目标：

- 所有运行参数有统一来源
- 配置可被严格校验
- 配置可被 UI、CLI、文件三种方式修改
- 配置变更可审计
- 无效配置不得直接污染运行态

## Design Principles

借鉴 OpenClaw 的做法，配置系统采用 `schema-first` 设计。

核心原则：

- 所有配置项必须先声明在 schema 中
- 所有模块只能通过配置服务读取配置
- UI 表单由 schema 驱动渲染
- 保存前必须校验
- 校验失败不允许生效
- 配置有版本和变更记录

## Config Sources

### 1. Default Config

系统默认值，由代码内置或默认配置文件提供。

### 2. Active Config

当前生效的正式配置。

建议位置：

- `biliup-next/config/settings.json`

### 3. Staged Config

用户在 UI 或 CLI 中提交、但尚未生效的待校验配置。

建议位置：

- `biliup-next/config/settings.staged.json`

### 4. Schema

定义配置结构、类型、默认值、枚举范围、校验规则和 UI 元信息。

建议位置：

- `biliup-next/config/settings.schema.json`

## Config Flow

```text
User edits config
  -> Write staged config
  -> Validate against schema
  -> Run dependency checks
  -> If valid: promote to active
  -> If invalid: keep current active config
```

## Validation Layers

### 1. Schema Validation

检查：

- 类型
- 必填字段
- 枚举值
- 数值范围
- 字段格式

### 2. Semantic Validation

检查：

- 路径是否存在
- 可执行文件是否可用
- season id 是否合法
- 依赖组合是否冲突

### 3. Runtime Validation

检查：

- provider 是否可初始化
- 凭证是否存在
- 外部连接是否可用

## Suggested Config Groups

### runtime

- `workspace_dir`
- `database_path`
- `log_level`
- `scan_interval_seconds`

### paths

- `stage_dir`
- `backup_dir`
- `session_dir`
- `cookies_file`
- `upload_config_file`

### ingest

- `provider`
- `min_duration_seconds`
- `ffprobe_bin`
- `yt_dlp_cmd`
- `allowed_extensions`

### transcribe

- `provider`
- `groq_api_key`
- `max_file_size_mb`
- `ffmpeg_bin`

### song_detect

- `provider`
- `codex_cmd`
- `qwen_cmd`
- `poll_interval_seconds`

### split

- `ffmpeg_bin`
- `poll_interval_seconds`

### publish

- `provider`
- `biliup_path`
- `cookie_file`
- `retry_count`
- `retry_schedule_minutes`
- `retry_backoff_seconds`

### comment

- `enabled`
- `max_retries`
- `base_delay_seconds`
- `poll_interval_seconds`

### collection

- `enabled`
- `season_id_a`
- `season_id_b`
- `allow_fuzzy_full_video_match`
- `append_collection_a_new_to_end`
- `append_collection_b_new_to_end`

## UI Strategy

管理台不手写业务表单，而是由 schema 驱动生成配置界面。

每个配置项除了类型信息，还应有：

- `title`
- `description`
- `group`
- `ui:widget`
- `ui:secret`
- `ui:order`

这样可以让配置页面和底层配置保持同源。

## Audit Trail

每次配置变更都应记录：

- 修改人
- 修改时间
- 修改前值
- 修改后值
- 校验结果
- 是否已生效

## Non-Goals

- 不追求兼容任意格式的配置文件
- 不允许模块私自定义一份独立配置入口
- 不允许 UI 和代码维护两套不同的字段定义