数据库字段与选项详解

📋 概述

本文档详细说明 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：

{
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "priority": "high",          // ✅ 命中: high, medium, low
  "title": "链上大额异动",
  "summary": "发现 1000 BTC 转入交易所",
  "evidence": { "amount": 1000, "token": "BTC" },
  "timestamp": "2026-02-02T10:00:00Z",
  "expire_at": "2026-02-02T11:00:00Z"
}

3. 数据库层面的保护

即使绕过了 API 校验，数据库层面也设置了 CheckConstraint。如果尝试插入非法值，PostgreSQL 会抛出约束错误： violates check constraint "check_priority"

网站概览 | Overview

项目愿景 | Project Vision

内部培训 | Internal Training

技术规范 | Protocols

基础设施 | Infrastructure

工作安排 | Work Plan

团队协作 | Team Collab

数据库字段与选项详解

📋 概述

1. 信号表 (`signals`)

🟢 信号状态选项 (`status`)

2. 待投递表 (`outbox`)

🔵 投递状态选项 (`status`)

3. 管道日志表 (`pipeline_log`)

4. API 密钥表 (`api_keys`)

💡 入库填写指南

1. 如何确保“命中”选项？

2. 必填项示例 (JSON)

3. 数据库层面的保护

​📋 概述

​1. 信号表 (signals)

​🟢 信号状态选项 (status)

​2. 待投递表 (outbox)

​🔵 投递状态选项 (status)

​3. 管道日志表 (pipeline_log)

​4. API 密钥表 (api_keys)

​💡 入库填写指南

​1. 如何确保“命中”选项？

​2. 必填项示例 (JSON)

​3. 数据库层面的保护

📋 概述

1. 信号表 (`signals`)

🟢 信号状态选项 (`status`)

2. 待投递表 (`outbox`)

🔵 投递状态选项 (`status`)

3. 管道日志表 (`pipeline_log`)

4. API 密钥表 (`api_keys`)

💡 入库填写指南

1. 如何确保“命中”选项？

2. 必填项示例 (JSON)

3. 数据库层面的保护