docs/API.md

# InterConnect-Server API Documentation

本文档描述了 InterConnect-Server 的所有 API 接口（AI 相关接口请参考 [AI_API.md](./AI_API.md)）。

## 概述

InterConnect-Server 是一个 Minecraft WebSocket API 服务器，提供 API Key 管理、事件广播、服务器命令等功能。

**默认端口**: `8000`

---

## 认证

除健康检查接口外，所有 API 请求需要在 Header 中携带 API Key：

```
Authorization: Bearer <your_api_key>
```

### API Key 类型

| 类型 | 前缀 | 说明 |
|------|------|------|
| Admin Key | `mc_admin_` | 管理员密钥，拥有所有权限 |
| Regular Key | `mc_key_` | 普通密钥，可管理关联的 Server Key |
| Server Key | `mc_server_` | 服务器密钥，供 Minecraft 服务器使用 |

---

## 健康检查

### 获取服务器状态

获取服务器健康状态和统计信息，无需认证。

**请求**

```http
GET /health
```

**成功响应** `200 OK`

```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "active_ws": 5,
  "keys_total": 10,
  "admin_active": 2,
  "server_active": 4,
  "regular_active": 4
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | string | 服务器状态 (`healthy` / `unhealthy`) |
| `timestamp` | string | 当前时间戳 |
| `active_ws` | number | 活跃的 WebSocket 连接数 |
| `keys_total` | number | API Key 总数 |
| `admin_active` | number | 活跃的 Admin Key 数量 |
| `server_active` | number | 活跃的 Server Key 数量 |
| `regular_active` | number | 活跃的 Regular Key 数量 |

**错误响应** `500 Internal Server Error`

```json
{
  "status": "unhealthy",
  "error": "Database connection failed"
}
```

---

## API Key 管理

**基础路径**: `/manage/keys`

### 获取所有 API Key

获取所有 API Key 的信息列表。

**权限**: Admin Key

**请求**

```http
GET /manage/keys
Authorization: Bearer <admin_key>
```

**成功响应** `200 OK`

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Server Key",
    "description": "Production server",
    "keyPrefix": "mc_key_",
    "keyType": "regular",
    "serverId": "server-1",
    "regularKeyId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": "2024-01-15T12:00:00.000Z",
    "isActive": true
  }
]
```

---

### 创建 API Key

创建新的 API Key。创建 Regular Key 时会自动生成关联的 Server Key。

**权限**: Admin Key

**请求**

```http
POST /manage/keys
Authorization: Bearer <admin_key>
Content-Type: application/json
```

**请求体 - 创建 Regular Key（推荐）**

```json
{
  "name": "My Server",
  "description": "Production Minecraft server",
  "key_type": "regular",
  "server_id": "server-1"
}
```

**请求体 - 创建 Admin Key**

```json
{
  "name": "New Admin",
  "description": "Backup admin key",
  "key_type": "admin"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | ✅ | Key 名称 |
| `description` | string | ❌ | 描述信息 |
| `key_type` | string | ❌ | Key 类型：`regular`（默认）、`admin` |
| `server_id` | string | ❌ | 服务器 ID |

**成功响应 - Regular Key** `201 Created`

```json
{
  "regularKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Server",
    "description": "Production Minecraft server",
    "keyPrefix": "mc_key_",
    "keyType": "regular",
    "serverId": "server-1",
    "regularKeyId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": null,
    "isActive": true,
    "key": "mc_key_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  },
  "serverKey": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Server - Server Key",
    "description": "Server Key for My Server",
    "keyPrefix": "mc_server_",
    "keyType": "server",
    "serverId": "server-1",
    "regularKeyId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": null,
    "isActive": true,
    "key": "mc_server_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6"
  }
}
```

**成功响应 - Admin Key** `201 Created`

```json
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "name": "New Admin",
  "description": "Backup admin key",
  "keyPrefix": "mc_admin_",
  "keyType": "admin",
  "serverId": null,
  "regularKeyId": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": null,
  "isActive": true,
  "key": "mc_admin_p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5e6"
}
```

> ⚠️ **重要**: `key` 字段只在创建时返回一次，请妥善保存！

---

### 获取 API Key 详情

获取指定 API Key 的详细信息。

**权限**: Admin Key

**请求**

```http
GET /manage/keys/:key_id
Authorization: Bearer <admin_key>
```

**成功响应** `200 OK`

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Server Key",
  "description": "Production server",
  "keyPrefix": "mc_key_",
  "keyType": "regular",
  "serverId": "server-1",
  "regularKeyId": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": "2024-01-15T12:00:00.000Z",
  "isActive": true
}
```

**错误响应** `404 Not Found`

```json
{
  "detail": "API Key not found"
}
```

---

### 获取 Server Key 列表

获取当前用户可访问的 Server Key 列表。

**权限**: Regular Key 或 Admin Key

**请求**

```http
GET /manage/keys/server-keys
Authorization: Bearer <regular_key_or_admin_key>
```

**成功响应** `200 OK`

```json
[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Server - Server Key",
    "description": "Server Key for My Server",
    "keyPrefix": "mc_server_",
    "keyType": "server",
    "serverId": "server-1",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": "2024-01-15T12:00:00.000Z",
    "isActive": true
  }
]
```

- **Admin Key**: 返回所有 Server Key
- **Regular Key**: 只返回关联的 Server Key

---

### 创建 Server Key

为指定的 Regular Key 创建新的 Server Key。

**权限**: Admin Key（仅限管理员，Regular Key 不能为自己创建 Server Key）

**请求**

```http
POST /manage/keys/server-keys
Authorization: Bearer <admin_key>
Content-Type: application/json
```

**请求体**

```json
{
  "name": "Backup Server Key",
  "description": "Backup key for server-1",
  "server_id": "server-1",
  "regular_key_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | ✅ | Key 名称 |
| `description` | string | ❌ | 描述信息 |
| `server_id` | string | ❌ | 服务器 ID |
| `regular_key_id` | string | ✅ | 关联的 Regular Key ID |

**成功响应** `201 Created`

```json
{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "name": "Backup Server Key",
  "description": "Backup key for server-1",
  "keyPrefix": "mc_server_",
  "keyType": "server",
  "serverId": "server-1",
  "regularKeyId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": null,
  "isActive": true,
  "key": "mc_server_n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6"
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "Name is required"
}
```

```json
{
  "detail": "regular_key_id is required"
}
```

**错误响应** `404 Not Found`

```json
{
  "detail": "Invalid Regular Key ID"
}
```

> ⚠️ **重要**: 
> - 只有 Admin Key 可以为 Regular Key 创建额外的 Server Key
> - Regular Key 不能为自己创建或删除 Server Key
> - `key` 字段只在创建时返回一次，请妥善保存！

---

### 激活 API Key

激活指定的 API Key。

**权限**: 
- Admin Key: 可激活任意 Key
- Regular Key: 只能激活关联的 Server Key

**请求**

```http
PATCH /manage/keys/:key_id/activate
Authorization: Bearer <api_key>
```

**成功响应** `200 OK`

```json
{
  "message": "Key '550e8400-e29b-41d4-a716-446655440000' activated."
}
```

---

### 停用 API Key

停用指定的 API Key。

**权限**: 
- Admin Key: 可停用任意 Key（不能停用最后一个活跃的 Admin Key）
- Regular Key: 只能停用关联的 Server Key

**请求**

```http
PATCH /manage/keys/:key_id/deactivate
Authorization: Bearer <api_key>
```

**成功响应** `200 OK`

```json
{
  "message": "Key '550e8400-e29b-41d4-a716-446655440000' deactivated."
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "Cannot deactivate your own key."
}
```

```json
{
  "detail": "Cannot deactivate last active Admin Key."
}
```

---

### 删除 API Key

永久删除指定的 API Key。

**权限**: Admin Key

**请求**

```http
DELETE /manage/keys/:key_id
Authorization: Bearer <admin_key>
```

**成功响应** `204 No Content`

无响应体

**错误响应** `400 Bad Request`

```json
{
  "detail": "Cannot delete your own key."
}
```

```json
{
  "detail": "Cannot delete the last Admin Key"
}
```

---

## 事件接口

**基础路径**: `/api/events`

### 发送事件

发送 Minecraft 事件并广播给所有 WebSocket 连接。

**权限**: 任意有效 API Key

**请求**

```http
POST /api/events
Authorization: Bearer <api_key>
Content-Type: application/json
```

**请求体**

```json
{
  "event_type": "player_join",
  "server_name": "server-1",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "player_name": "Steve",
    "player_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `event_type` | string | ✅ | 事件类型 |
| `server_name` | string | ✅ | 服务器名称 |
| `timestamp` | string | ✅ | 事件时间戳 (ISO 8601) |
| `data` | object | ✅ | 事件数据 |

**支持的事件类型**

| 事件类型 | 说明 |
|----------|------|
| `player_join` | 玩家加入服务器 |
| `player_leave` | 玩家离开服务器 |
| `message` | 聊天消息 |
| `server_command` | 服务器命令 |
| `ai_chat` | AI 聊天 |

**成功响应** `200 OK`

```json
{
  "message": "Event received and broadcasted"
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "Missing required event fields"
}
```

```json
{
  "detail": "Invalid event_type: unknown_event"
}
```

---

## 服务器接口

**基础路径**: `/api/server`

### 获取服务器信息

获取 Minecraft 服务器信息。

**权限**: Regular Key 或 Admin Key

**请求**

```http
GET /api/server/info
Authorization: Bearer <api_key>
```

**查询参数**（仅 Admin Key）

| 参数 | 类型 | 说明 |
|------|------|------|
| `server_id` | string | 指定服务器 ID |

**成功响应** `200 OK`

```json
{
  "server_id": "server-1",
  "status": "running",
  "online_players": 5,
  "max_players": 20,
  "version": "1.20.1",
  "uptime": "2h 30m",
  "tps": 19.8
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "server_id is required for this key"
}
```

---

### 发送服务器命令

向 Minecraft 服务器发送命令。

**权限**: Regular Key 或 Admin Key

**请求**

```http
POST /api/server/command
Authorization: Bearer <api_key>
Content-Type: application/json
```

**请求体**

```json
{
  "command": "say Hello World",
  "server_id": "server-1"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `command` | string | ✅ | 要执行的命令 |
| `server_id` | string | ❌ | 服务器 ID（Admin Key 可指定） |

**成功响应** `200 OK`

```json
{
  "message": "Command sent successfully",
  "command": "say Hello World",
  "server_id": "server-1"
}
```

**错误响应** `400 Bad Request`

```json
{
  "detail": "Command is required"
}
```

**错误响应** `403 Forbidden`

```json
{
  "detail": "Command is not allowed for Admin Key"
}
```

**Admin Key 默认禁止的命令**

以下命令默认禁止 Admin Key 执行（可通过环境变量配置）：

- `stop`, `restart`, `reload`
- `op`, `deop`
- `ban`, `ban-ip`, `banlist`, `pardon`, `pardon-ip`
- `whitelist`, `kick`
- `save-all`, `save-on`, `save-off`

---

## WebSocket 接口

### 连接 WebSocket

建立 WebSocket 连接以接收实时事件。

**端点**

```
ws://<host>:<port>/ws?api_key=<your_api_key>
```

**示例**

```
ws://localhost:8000/ws?api_key=mc_server_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

**连接成功后**

服务器会推送 Minecraft 事件消息：

```json
{
  "type": "minecraft_event",
  "event": {
    "event_type": "player_join",
    "server_name": "server-1",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
      "player_name": "Steve"
    }
  },
  "source_key_id_prefix": "550e8400"
}
```

### 心跳检测

客户端可以发送 ping 消息保持连接：

**发送**

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

**响应**

```json
{
  "type": "pong"
}
```

---

## 根路径

### 获取服务器信息

**请求**

```http
GET /
```

**成功响应** `200 OK`

```json
{
  "message": "Minecraft WebSocket API Server (Node.js)",
  "dashboard": "/dashboard",
  "websocket": "ws://localhost:8000/ws",
  "version": "1.0.0"
}
```

---

## 错误码参考

| HTTP 状态码 | 说明 |
|-------------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无内容） |
| 400 | 请求参数错误 |
| 401 | 未认证或 API Key 无效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `SERVER_HOST` | `0.0.0.0` | 服务器监听地址 |
| `SERVER_PORT` | `8000` | 服务器端口 |
| `DATABASE_PATH` | `minecraft_ws.db` | 数据库文件路径 |
| `DASHBOARD_PORT` | `3000` | Dashboard 独立端口（可选） |
| `ADMIN_ALLOWED_COMMANDS` | - | Admin Key 允许的命令（逗号分隔） |
| `ADMIN_BLOCKED_COMMANDS` | - | Admin Key 禁止的命令（逗号分隔） |