docs/protocol.md

# 协议规范

本文档定义了 InterConnect-Server 使用的 REST 和 WebSocket 协议格式。所有负载均为 JSON 格式。

## 认证 (Authentication)

- REST: 在请求头中发送 `Authorization: Bearer <API_KEY>`。
- WebSocket: 连接到 `ws://<host>/ws?api_key=<API_KEY>`（HTTPS 下使用 `wss`）。

## 事件对象 (Event Object)

事件通过 REST 发送到服务器，并广播给 WebSocket 客户端。
服务器仅验证必填字段和 `event_type` 值。
`data` 负载会原样传递。

必填字段：
- `event_type` (字符串)
- `server_name` (字符串)
- `timestamp` (字符串, ISO 8601)
- `data` (对象)

有效的 `event_type` 值：
- `player_join`
- `player_leave`
- `message`
- `server_command`

事件示例：
```json
{
  "event_type": "player_join",
  "server_name": "survival-01",
  "timestamp": "2024-01-21T12:34:56.789Z",
  "data": {
    "player": "Steve"
  }
}
```

## REST 端点 (REST Endpoints)

### POST /api/events

提交一个事件以进行存储和广播。

请求：
- 认证：任意有效密钥
- `Content-Type: application/json`
- Body: 事件对象

响应：
```json
{
  "message": "Event received and broadcasted"
}
```

错误：
- `400` 如果缺少必填字段或 `event_type` 无效
- `401` 如果 API 密钥丢失/无效

### POST /api/server/command

发送服务器命令。这也将广播一个 `server_command` 事件。

请求：
- 认证：Regular 或 Admin 密钥
- `Content-Type: application/json`
- Body:
```json
{
  "command": "say Hello from API",
  "server_id": "survival-01"
}
```

注意：
- 当 Admin 密钥未绑定到服务器时，必须提供 `server_id`。
- 服务器对 Admin 命令强制执行允许/阻止列表。

响应：
```json
{
  "message": "Command sent successfully",
  "command": "say Hello from API",
  "server_id": "survival-01"
}
```

## WebSocket 消息 (WebSocket Messages)

### 客户端到服务器

Ping:
```json
{ "type": "ping" }
```

Pong 响应:
```json
{ "type": "pong" }
```

### 服务器到客户端

广播事件：
```json
{
  "type": "minecraft_event",
  "event": {
    "event_type": "message",
    "server_name": "survival-01",
    "timestamp": "2024-01-21T12:34:56.789Z",
    "data": {
      "player": "Alex",
      "message": "Hello world"
    }
  },
  "source_key_id_prefix": "a1b2c3d4"
}
```

`source_key_id_prefix` 是提交事件或命令的 API 密钥 ID 的前 8 个字符。它不是 API 密钥本身。