2.3 KiB
后端枚举与字符串兼容契约
Planet 后端使用 backend/app/core/enums.py 统一维护有限、稳定、会参与协议判断的状态值。数据库和 API 仍保存、输出小写字符串；枚举用于代码内部的类型安全、校验和去重，不要求数据库迁移为 SQL Enum。
使用准则
适合枚举的值必须有限且稳定，非法值应被拒绝或安全回退，并且多个模块会比较、排序或分支处理该值。典型示例包括任务状态、AI Playground 消息角色和状态、用户角色、告警状态、日志级别、新闻重要度和 Breaking 状态。
以下值必须保持可配置字符串：
- 新闻分类与标签。
- Provider、模型、数据源、collector、新闻源和 Feed 标识。
- 可扩展的 incident/anomaly 类型。
- 用户输入和自由文本。
边界转换
服务内部优先使用 StrEnum。写入数据库或输出外部协议时使用 .value，继续得到现有字符串，例如 JobStatus.RUNNING.value == "running"。
读取历史数据库、JSON 或外部输入时使用：
status = parse_enum(JobStatus, raw_status, JobStatus.FAILED)
合法历史字符串会归一为枚举；空值使用明确默认值；未知值记录 warning 并安全回退，不阻断历史数据读取。Pydantic 请求字段可以直接使用枚举，让非法协议值返回 422。普通 String/JSON 数据库列不改成 SQLAlchemy Enum。
Earth 新闻判定
Earth 新闻判定集中在 backend/app/services/earth_news_classification.py：
- 分类回答“新闻是什么”，分类 key 仍是可配置字符串。
- 重要度回答“长期是否值得关注”。
- Breaking 回答“短时间内是否必须插队”。
重要度等级固定为：
| 等级 | 分数 |
|---|---|
low |
0–34 |
medium |
35–59 |
high |
60–79 |
critical |
80–100 |
Breaking 规则使用带类型的 BreakingRule；等级、范围、来源和 TTL 由公开分类模块统一管理。earth_news.py 只负责抓取、解析、编排与序列化。
防回退检查
新增或修改协议状态时，先检查 app/core/enums.py，不要在业务模块重复定义 Literal、状态集合或 normalize helper。枚举值与边界行为应补充到 tests/test_enum_contracts.py，并保证 API 字符串和数据库表示不变。