> ## 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.

# POST 创建信号

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

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

## 核心特性

<CardGroup cols={2}>
  <Card title="字段验证" icon="check-circle">
    验证所有必填字段，确保数据完整性
  </Card>

  <Card title="过期检查" icon="clock">
    `expire_at` 必须未来时间，拒绝已过期信号
  </Card>

  <Card title="幂等性保证" icon="shield-check">
    `signal_id` UNIQUE，重复提交返回已有记录
  </Card>

  <Card title="自动生成 Outbox" icon="send">
    为每个信号生成 2 条 outbox（ghost + rocketchat）
  </Card>
</CardGroup>

***

## 认证

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

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

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

***

## 请求参数

### Headers

| 参数             | 类型     | 必填 | 说明                 |
| -------------- | ------ | -- | ------------------ |
| `X-API-Key`    | string | ✅  | API 认证密钥           |
| `Content-Type` | string | ✅  | `application/json` |

### Body 参数

| 字段          | 类型       | 必填 | 说明                            | 示例                                     |
| ----------- | -------- | -- | ----------------------------- | -------------------------------------- |
| `signal_id` | UUID     | ✅  | 信号唯一标识（用于幂等性）                 | `550e8400-e29b-41d4-a716-446655440000` |
| `timestamp` | datetime | ✅  | 信号发生时间（ISO 8601，UTC）          | `2026-02-02T10:00:00Z`                 |
| `priority`  | string   | ✅  | 优先级：`high` / `medium` / `low` | `high`                                 |
| `title`     | string   | ✅  | 信号标题（最大 100 字符）               | `AI 板块出现集中放量`                          |
| `summary`   | string   | ✅  | 信号摘要                          | `多个AI相关代币在5分钟内成交量激增`                   |
| `evidence`  | object   | ✅  | 证据数据（JSON 对象）                 | `{"market": {...}, "twitter": {...}}`  |
| `expire_at` | datetime | ✅  | 过期时间（ISO 8601，UTC，必须未来时间）     | `2026-02-02T11:00:00Z`                 |

***

## 响应

### 成功响应（201 Created）

信号已创建，并生成了 outbox 记录。

<ResponseExample>
  ```json theme={null}
  {
    "id": 1,
    "signal_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-02T10:00:00Z",
    "priority": "high",
    "title": "AI 板块出现集中放量",
    "summary": "多个AI相关代币在5分钟内成交量激增",
    "evidence": {
      "market": {
        "symbols": ["AI1", "AI2", "AI3"],
        "volume_increase": "320%"
      },
      "twitter": {
        "topic": "AI Meme",
        "tweet_growth": 500
      }
    },
    "expire_at": "2026-02-02T11:00:00Z",
    "status": "dispatching",
    "received_at": "2026-02-02T10:00:05.123456Z",
    "created_at": "2026-02-02T10:00:05.123456Z",
    "updated_at": "2026-02-02T10:00:05.123456Z"
  }
  ```
</ResponseExample>

<Info>
  **状态说明**：`dispatching` 表示已创建 outbox，正在分发中。
</Info>

### 幂等性响应（200 OK）

使用相同的 `signal_id` 再次提交，返回已有记录。

<ResponseExample>
  ```json theme={null}
  {
    "id": 1,
    "signal_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-02T10:00:00Z",
    "priority": "high",
    "title": "AI 板块出现集中放量",
    "summary": "多个AI相关代币在5分钟内成交量激增",
    "evidence": {...},
    "expire_at": "2026-02-02T11:00:00Z",
    "status": "dispatching",
    "received_at": "2026-02-02T10:00:05.123456Z",
    "created_at": "2026-02-02T10:00:05.123456Z",
    "updated_at": "2026-02-02T10:00:05.123456Z"
  }
  ```
</ResponseExample>

### 错误响应

<AccordionGroup>
  <Accordion title="400 Bad Request - 验证失败">
    <ResponseExample>
      ```json theme={null}
      {
        "detail": "expire_at must be in the future"
      }
      ```
    </ResponseExample>

    **常见错误**：

    * `expire_at must be in the future`: 过期时间已过
    * `Signal has already expired`: 信号已过期
    * `Field required`: 缺少必填字段
    * `priority must be one of: high, medium, low`: 优先级无效
    * `Database integrity error: ...`: 数据库约束错误（如重复的 signal\_id）
  </Accordion>

  <Accordion title="500 Internal Server Error - 服务器错误">
    <ResponseExample>
      ```json theme={null}
      {
        "detail": "Internal server error"
      }
      ```
    </ResponseExample>

    **说明**：

    * 生产环境：返回通用错误信息 `"Internal server error"`
    * 开发环境（DEBUG 模式）：返回详细错误信息，格式为 `"{ErrorType}: {error_message}"`

    <Warning>
      生产环境不会返回详细的错误堆栈，这是出于安全考虑。如需调试，请查看服务器日志。
    </Warning>
  </Accordion>

  <Accordion title="401 Unauthorized - 认证失败">
    <ResponseExample>
      ```json theme={null}
      {
        "detail": "Invalid API Key"
      }
      ```
    </ResponseExample>

    <Warning>
      如果 API Key 错误或缺失，会返回 `401 Unauthorized`。请检查请求头中的 `X-API-Key` 是否正确。
    </Warning>
  </Accordion>
</AccordionGroup>

***

## 使用示例

<CodeGroup>
  ```bash cURL 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-here" \
    -d '{
      "signal_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-02-02T10:00:00Z",
      "priority": "high",
      "title": "AI 板块出现集中放量",
      "summary": "多个AI相关代币在5分钟内成交量激增，同时Twitter上相关话题提及量增长230%",
      "evidence": {
        "market": {
          "symbols": ["AI1", "AI2", "AI3"],
          "volume_increase": "320%",
          "price_change_range": "5-12%"
        },
        "twitter": {
          "topic": "AI Meme",
          "tweet_growth": 500,
          "key_accounts": ["@influencer1", "@influencer2"]
        }
      },
      "expire_at": "2026-02-02T11:00:00Z"
    }'
  ```

  ```python Python theme={null}
  import requests
  import uuid
  from datetime import datetime, timezone, timedelta

  url = "https://api.dev.akria.net/api/v1/signals"
  headers = {
      "Content-Type": "application/json",
      "X-API-Key": "your-api-key-here"
  }
  data = {
      "signal_id": str(uuid.uuid4()),
      "timestamp": datetime.now(timezone.utc).isoformat(),
      "priority": "high",
      "title": "AI 板块出现集中放量",
      "summary": "多个AI相关代币在5分钟内成交量激增",
      "evidence": {
          "market": {
              "symbols": ["AI1", "AI2"],
              "volume_increase": "320%"
          }
      },
      "expire_at": (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat()
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
  const { v4: uuidv4 } = require('uuid');

  const url = 'https://api.dev.akria.net/api/v1/signals';
  const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key-here'
  };
  const data = {
    signal_id: uuidv4(),
    timestamp: new Date().toISOString(),
    priority: 'high',
    title: 'AI 板块出现集中放量',
    summary: '多个AI相关代币在5分钟内成交量激增',
    evidence: {
      market: {
        symbols: ['AI1', 'AI2'],
        volume_increase: '320%'
      }
    },
    expire_at: new Date(Date.now() + 3600000).toISOString()
  };

  axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error.response.data));
  ```
</CodeGroup>

***

## 注意事项

<CardGroup cols={2}>
  <Card title="signal_id 必须唯一" icon="key">
    使用 UUID v4 生成，确保全局唯一性
  </Card>

  <Card title="expire_at 必须未来时间" icon="clock">
    建议至少 1 小时后，避免立即过期
  </Card>

  <Card title="幂等性保证" icon="shield-check">
    相同 `signal_id` 不会重复创建 outbox
  </Card>

  <Card title="时区要求" icon="globe">
    所有时间字段使用 UTC（ISO 8601 格式，带 Z）
  </Card>
</CardGroup>

***

## 相关文档

<CardGroup cols={2}>
  <Card title="团队使用手册" icon="book" href="../../../services/core-api-v1/docs/API_USAGE_GUIDE.md">
    手把手教程，适合团队使用
  </Card>

  <Card title="拉取 Outbox" icon="download" href="/technical/api-reference/core-api-outbox-pull">
    下游服务拉取待投递内容
  </Card>

  <Card title="ACK 确认" icon="check-circle" href="/technical/api-reference/core-api-outbox-ack">
    下游服务投递完成后发送 ACK 确认
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /api/v1/signals
openapi: 3.1.0
info:
  title: Core API V1
  description: Core API V1 - Pull 模式核心网关服务，用于接收信号并管理 Outbox
  version: 1.0.0
servers:
  - url: https://api.dev.akria.net
    description: Dev 环境
security:
  - apiKey: []
paths:
  /api/v1/signals:
    post:
      tags:
        - signals
      summary: 创建信号
      description: 接收来自分析层的已审计信号，验证并创建 outbox 记录。支持幂等性（相同 signal_id 返回已有记录）。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignalCreate'
            example:
              signal_id: 550e8400-e29b-41d4-a716-446655440000
              timestamp: '2026-02-02T10:00:00Z'
              priority: high
              title: AI 板块出现集中放量
              summary: 多个AI相关代币在5分钟内成交量激增，同时Twitter上相关话题提及量增长230%
              evidence:
                market:
                  symbols:
                    - AI1
                    - AI2
                    - AI3
                  volume_increase: 320%
                  price_change_range: 5-12%
                twitter:
                  topic: AI Meme
                  tweet_growth: 500
                  key_accounts:
                    - '@influencer1'
                    - '@influencer2'
              expire_at: '2026-02-02T11:00:00Z'
      responses:
        '200':
          description: 幂等性响应：信号已存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalResponse'
        '201':
          description: 信号已创建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalResponse'
        '400':
          description: 验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: expire_at must be in the future
        '401':
          description: 认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid API Key
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Internal server error
      security:
        - apiKey: []
components:
  schemas:
    SignalCreate:
      type: object
      required:
        - signal_id
        - timestamp
        - priority
        - title
        - summary
        - evidence
        - expire_at
      properties:
        signal_id:
          type: string
          format: uuid
          description: 信号唯一标识（用于幂等性）
        timestamp:
          type: string
          format: date-time
          description: 信号发生时间（ISO 8601，UTC）
        priority:
          type: string
          enum:
            - high
            - medium
            - low
          description: 优先级
        title:
          type: string
          maxLength: 100
          description: 信号标题
        summary:
          type: string
          description: 信号摘要
        evidence:
          type: object
          description: 证据数据（JSON 对象）
          additionalProperties: true
        expire_at:
          type: string
          format: date-time
          description: 过期时间（ISO 8601，UTC，必须未来时间）
    SignalResponse:
      type: object
      properties:
        id:
          type: integer
          description: 信号 ID
        signal_id:
          type: string
          format: uuid
          description: 信号唯一标识
        timestamp:
          type: string
          format: date-time
          description: 信号发生时间
        priority:
          type: string
          enum:
            - high
            - medium
            - low
          description: 优先级
        title:
          type: string
          description: 信号标题
        summary:
          type: string
          description: 信号摘要
        evidence:
          type: object
          description: 证据数据
          additionalProperties: true
        expire_at:
          type: string
          format: date-time
          description: 过期时间
        status:
          type: string
          enum:
            - accepted
            - dispatching
            - sent
            - partial_sent
            - failed
            - archived
          description: 信号状态
        received_at:
          type: string
          format: date-time
          description: 接收时间
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: 错误详情
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API 认证密钥

````