init biliup-next

docs/config-system.md

@@ -0,0 +1,193 @@
+# 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
+
+- `min_duration_seconds`
+- `allowed_extensions`
+
+### transcribe
+
+- `provider`
+- `groq_api_key`
+- `max_file_size_mb`
+- `ffmpeg_bin`
+
+### song_detect
+
+- `provider`
+- `codex_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 和代码维护两套不同的字段定义