> ## 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 介绍

> Core API V1 - Pull 模式核心网关服务

## 🎯 什么是 Core API？

Core API 是 Situation Monitor 系统的**核心网关服务**，采用 **Pull 模式（拉取模式）** 架构。

<CardGroup cols={2}>
  <Card title="信号接收与存储" icon="signal">
    接收并验证来自分析层的信号，持久化存储到 PostgreSQL。
  </Card>

  <Card title="Outbox 模式" icon="box-archive">
    为每个信号生成预格式化的 Outbox 记录，确保投递可靠性。
  </Card>

  <Card title="Pull 模式" icon="arrows-down-to-line">
    下游服务（Ghost / Rocket.Chat）按需主动拉取待投递内容。
  </Card>

  <Card title="ACK 确认机制" icon="check-double">
    下游投递完成后通过 ACK 确认，实现投递状态的闭环追踪。
  </Card>
</CardGroup>

<Note>
  **状态聚合**：系统会自动维护信号的整体投递状态（`sent` / `partial_sent` / `failed`），方便全局监控。
</Note>

### 📐 设计原则

<Steps>
  <Step title="不做主动推送" icon="xmark">
    不集成任何推送 SDK（Telegram、WhatsApp 等），保持核心轻量和解耦。
  </Step>

  <Step title="专注于存储和拉取" icon="database">
    只做信号存储和 Outbox 管理，提供标准的 RESTful 接口。
  </Step>

  <Step title="幂等性保证" icon="fingerprint">
    `signal_id` 唯一约束，确保重复提交不会产生重复的投递任务。
  </Step>

  <Step title="并发安全" icon="shield-check">
    使用 `SELECT ... FOR UPDATE SKIP LOCKED` 机制，确保多实例环境下任务不被重复领取。
  </Step>
</Steps>

***

## 🔐 认证方式 | Authentication

所有 API 端点（除健康检查外）都需要在请求头中包含 API Key：

```bash theme={null}
X-API-Key: your-api-key-here
```

### 多组 API Key 管理

Core API 支持多组 API Key 管理，可以为不同的团队、项目或环境设置独立的 API Key。

**获取 API Key**：

* 联系管理员获取你所在组的 API Key
* 每个组有独立的 API Key，便于管理和追踪

**组命名规范**：

* 按环境：`dev-team-1`, `dev-team-2`, `prod-team-1`
* 按项目：`project-a-team`, `project-b-team`
* 按角色：`analyzers`, `notifiers`, `monitors`

**认证失败**：如果 API Key 错误或缺失，会返回 `401 Unauthorized`。

**Key 管理**：

* Key 存储在数据库中，支持动态添加、禁用、删除
* 支持设置过期时间
* 自动记录使用统计（使用次数、最后使用时间）

<Tip>
  详细的管理文档请参考：[API Key 管理文档](../../../services/core-api-v1/docs/API_KEY_MANAGEMENT.md)
</Tip>

***

## 🚀 核心端点 | Core Endpoints

### 1. POST /api/v1/signals - 创建信号

接收来自分析层的已审计信号，验证并创建 outbox 记录。

**特性**：

* ✅ 字段验证（signal\_id, timestamp, priority, title, summary, evidence, expire\_at）
* ✅ 过期检查（expire\_at 必须未来时间）
* ✅ 幂等性保证（signal\_id UNIQUE）
* ✅ 自动生成 outbox（ghost + rocketchat）

[查看详细文档 →](/technical/api-reference/core-api-signals)

### 2. GET /api/v1/outbox/{channel} - 拉取 Outbox

下游服务拉取待投递内容。

**特性**：

* ✅ 支持 channel: `ghost`, `rocketchat`
* ✅ 租约机制（防止重复领取）
* ✅ 并发安全（SELECT ... FOR UPDATE SKIP LOCKED）
* ✅ 自动标记为 leased

[查看详细文档 →](/technical/api-reference/core-api-outbox-pull)

### 3. POST /api/v1/outbox/{channel}/ack - ACK 确认

下游服务投递完成后发送 ACK 确认。

**特性**：

* ✅ 成功/失败确认
* ✅ 自动重试机制（最多 3 次）
* ✅ 状态聚合（sent / partial\_sent / failed）

[查看详细文档 →](/technical/api-reference/core-api-outbox-ack)

### 4. GET /api/v1/health - 健康检查

检查 API 和数据库连接状态。

**特性**：

* ✅ 无需认证
* ✅ 返回服务状态和数据库连接状态

[查看详细文档 →](/technical/api-reference/core-api-health)

***

## 📋 工作流程 | Workflow

### 完整流程示例

1. **创建信号**：分析层发送信号到 Core API
   ```
   POST /api/v1/signals
   → 201 Created
   → 自动生成 2 条 outbox（ghost + rocketchat）
   ```

2. **拉取 Outbox**：Ghost 服务拉取待投递内容
   ```
   GET /api/v1/outbox/ghost?limit=10&lease_seconds=60
   → 返回待投递项，自动标记为 leased
   ```

3. **投递内容**：Ghost 服务使用 payload 投递到 Ghost API

4. **ACK 确认**：Ghost 服务发送 ACK
   ```
   POST /api/v1/outbox/ghost/ack
   → 更新 outbox 状态为 delivered
   → 更新信号状态（如果两个渠道都成功，状态为 sent）
   ```

5. **Rocket.Chat 服务**：重复步骤 2-4

***

## 📚 快速开始 | Quick Start

### 1. 健康检查

```bash theme={null}
curl https://api.dev.akria.net/api/v1/health
```

### 2. 创建信号

```bash theme={null}
curl -X POST https://api.dev.akria.net/api/v1/signals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "signal_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-02T10:00:00Z",
    "priority": "high",
    "title": "测试信号",
    "summary": "这是一个测试信号",
    "evidence": {"test": "data"},
    "expire_at": "2026-02-02T11:00:00Z"
  }'
```

### 3. 拉取 Outbox

```bash theme={null}
curl "https://api.dev.akria.net/api/v1/outbox/ghost?limit=10&lease_seconds=60"
```

### 4. ACK 确认

```bash theme={null}
curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
  -H "Content-Type: application/json" \
  -d '{"outbox_id": 1, "ok": true}'
```

***

## 📖 详细文档 | Documentation

* **[团队使用手册](../../../services/core-api-v1/docs/API_USAGE_GUIDE.md)** - 手把手教程，适合团队使用
* **[API 示例](../../../services/core-api-v1/docs/EXAMPLES.md)** - 更多使用示例
* **[部署手册](../../../services/core-api-v1/docs/DEPLOYMENT_MANUAL.md)** - Dev 环境部署指南

***

<Tip>
  建议先阅读 [团队使用手册](../../../services/core-api-v1/docs/API_USAGE_GUIDE.md)，里面有详细的步骤说明和常见问题解答。
</Tip>