> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据库字段与选项详解

> 详细说明 Core API V1 数据库中各表的字段定义、允许的选项（枚举值）以及入库时的填写规范。

## 📋 概述

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

```json theme={null}
{
  "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"`