51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# 后端枚举与字符串兼容契约
|
||
|
||
Planet 后端使用 `backend/app/core/enums.py` 统一维护有限、稳定、会参与协议判断的状态值。数据库和 API 仍保存、输出小写字符串；枚举用于代码内部的类型安全、校验和去重，不要求数据库迁移为 SQL Enum。
|
||
|
||
## 使用准则
|
||
|
||
适合枚举的值必须有限且稳定，非法值应被拒绝或安全回退，并且多个模块会比较、排序或分支处理该值。典型示例包括任务状态、AI Playground 消息角色和状态、用户角色、告警状态、日志级别、新闻重要度和 Breaking 状态。
|
||
|
||
以下值必须保持可配置字符串：
|
||
|
||
- 新闻分类与标签。
|
||
- Provider、模型、数据源、collector、新闻源和 Feed 标识。
|
||
- 可扩展的 incident/anomaly 类型。
|
||
- 用户输入和自由文本。
|
||
|
||
## 边界转换
|
||
|
||
服务内部优先使用 `StrEnum`。写入数据库或输出外部协议时使用 `.value`，继续得到现有字符串，例如 `JobStatus.RUNNING.value == "running"`。
|
||
|
||
读取历史数据库、JSON 或外部输入时使用：
|
||
|
||
```python
|
||
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 字符串和数据库表示不变。
|
||
|