这份文档用于记录 Rust 迁移过程中最早需要固化的输入输出契约。
这份文档最初用于在迁移早期提前固化契约类型。当前仓库的主要模块契约已经分别落到 docs/contracts/ 与 docs/implementation/，因此这里更适合作为总入口和抽象索引，而不是继续假设仓库仍处于“尚未实现”的阶段。
中型迁移最容易失控的地方，不是代码写不出来，而是行为边界没有提前固定：
- 输入长什么样
- 输出长什么样
- 出错时返回什么
- 哪些字段必须稳定
- 哪些字段后续允许扩展
没有这些基线，AI 只能按局部上下文猜测，后面会反复返工。
优先覆盖：
- 时区
- 热榜平台列表
- RSS 订阅列表
- 调度配置
- 输出开关和输出目标
最低要求：
- 明确每个字段的类型、默认值、是否必填
- 明确无效配置时的错误语义
优先覆盖：
- 每个数据源的最小输入参数
- 抓取成功后的统一内部模型
- 抓取失败后的错误分类
最低要求：
- 成功结果能映射到统一
domain模型 - 失败结果能区分配置问题、网络问题、解析问题和限流问题
优先覆盖：
- 过滤输入
- 排序规则输入
- 聚合结果结构
- 分数和统计字段
最低要求：
- 同一份 fixture 在同一版本逻辑下输出稳定
- 结果字段定义与排序规则可以被快照测试覆盖
优先覆盖：
- 写入记录的主键或去重策略
- 读取和查询最小接口
- 持久化失败的错误语义
优先覆盖：
- JSON 输出结构
- 报告元数据
- 运行上下文
- 错误输出格式
后续新增具体契约时，建议按下面模板填写：
## 契约名称
### 场景
这个契约用于什么环节。
### 输入
- 字段：
- 类型：
- 必填：
- 默认值：
- 说明：
### 输出
- 字段：
- 类型：
- 稳定性要求：
- 说明：
### 错误
- 错误类别：
- 触发条件：
- 是否可重试：
### 兼容要求
- 是否要求与旧系统保持兼容：
- 如果不兼容，替代方案是什么：
### 验证方式
- 对应 fixture：
- 对应测试：
- 对应快照：AppConfig的最小字段契约NewsItem/RssItem的序列化契约- 调度决策输入输出契约
- 聚合与排序结果契约
- 首版 JSON 输出契约
- 每新增一个对外可观察行为，就判断是否应写入本文件
- 如果某项行为已经由 fixture 和测试完全覆盖，也仍应在这里保留简明入口
- 本文件不追求一次写全，而是随着迁移推进逐步固化
进入实现阶段后，具体字段和行为边界应继续下沉到模块级契约文档：