📋 概述
本文档详细说明 Core API V1 数据库中各表的字段定义、允许的选项（枚举值）以及入库时的填写规范。1. 信号表 (signals)
存储从分析层接收到的原始信号数据。
| 字段名 | 类型 | 约束 | 默认值 | 允许的选项 (Options) | 说明 |
|---|---|---|---|---|---|
id | BigInteger | PK | - | - | 数据库自增主键 |
signal_id | UUID | Unique | - | - | 业务唯一 ID，用于幂等性检查 |
priority | String(10) | Not Null | - | high, medium, low | 信号优先级 |
title | String(100) | Not Null | - | - | 信号标题 |
summary | Text | Not Null | - | - | 信号摘要/内容 |
evidence | JSONB | Not Null | - | - | 结构化证据数据 |
status | String(20) | Not Null | accepted | 见下文 [信号状态选项] | 信号处理生命周期状态 |
timestamp | DateTime | Not Null | - | - | 信号发生时间（带时区） |
expire_at | DateTime | Not Null | - | - | 信号过期时间（带时区） |
received_at | DateTime | Not Null | now() | - | 系统接收时间 |
🟢 信号状态选项 (status)
| 选项 | 说明 | 填写建议 |
|---|---|---|
accepted | 已接收，等待处理 | 入库默认值。通常由系统自动设置。 |
dispatching | 正在分发，Outbox 已创建 | 系统自动更新。表示信号已进入待投递队列。 |
sent | 已发送，所有渠道均已成功投递 | 系统自动更新。表示流程完整结束。 |
partial_sent | 部分发送，仅部分渠道投递成功 | 系统自动更新。 |
failed | 发送失败，所有渠道均投递失败 | 系统自动更新。 |
archived | 已归档，信号已过期 | 系统自动更新。 |
2. 待投递表 (outbox)
存储待发送到下游服务（如 Ghost, Rocket.Chat）的任务。
| 字段名 | 类型 | 约束 | 默认值 | 允许的选项 (Options) | 说明 |
|---|---|---|---|---|---|
id | BigInteger | PK | - | - | 数据库自增主键 |
channel | String(20) | Not Null | - | ghost, rocketchat | 投递目标渠道 |
status | String(20) | Not Null | pending | 见下文 [投递状态选项] | 任务执行状态 |
payload | JSONB | Not Null | - | - | 针对渠道格式化后的数据 |
attempts | Integer | Not Null | 0 | - | 已尝试推送次数（最大 3 次） |
lease_owner | String(64) | Nullable | - | - | 当前持有该任务的 worker ID |
lease_until | DateTime | Nullable | - | - | 任务锁定过期时间 |
🔵 投递状态选项 (status)
| 选项 | 说明 |
|---|---|
pending | 初始状态。等待 worker 拉取。 |
leased | 已锁定。已被 worker 领取，正在处理中。 |
delivered | 已送达。下游服务已确认接收（收到 ACK）。 |
failed | 重试中。推送失败，但未达到最大重试次数。 |
dead | 已失效。超过最大重试次数，需人工介入。 |
3. 管道日志表 (pipeline_log)
用于追踪信号在系统内部流转的审计日志。
| 字段名 | 类型 | 允许的选项 (Options) | 说明 |
|---|---|---|---|
stage | String(20) | ingest, outbox_create, lease, ack | 处理阶段 |
status | String(20) | start, success, fail | 阶段执行结果 |
4. API 密钥表 (api_keys)
管理访问权限和使用统计。
| 字段名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
is_active | Boolean | true | 是否激活（true/false） |
group_name | String | - | 所属团队名（如 dev-team-1） |
💡 入库填写指南
1. 如何确保“命中”选项？
在进行数据库入库（通过 API 或 SQL）时，请遵循以下规则：- 大小写敏感：所有选项必须使用 小写 英文字母（例如：填写
high而不是High）。 - 严格匹配：不能包含空格或特殊字符。
- Pydantic 校验：如果你使用 Python SDK 或直接调用 API，系统会通过 Pydantic 模型进行预校验。如果值不匹配，会直接返回
422 Unprocessable Entity。
2. 必填项示例 (JSON)
当你作为分析层向 Core API 发送数据时，最关键的“命中”字段是priority：
3. 数据库层面的保护
即使绕过了 API 校验，数据库层面也设置了CheckConstraint。
如果尝试插入非法值，PostgreSQL 会抛出约束错误：
violates check constraint "check_priority"