# Redis 对接协议（供外部项目 AI 生成代码使用）

本文档定义“外部项目 ↔ BLS Project Console”之间通过 Redis 交互的 **Key 命名、数据类型、写入方式、读取方式与数据格式**。

> 约束：每个需要关联本控制台的外部项目，必须在本项目使用的同一个 Redis 实例中：
> - 写入 2 个 Key（状态 + 控制台信息）
> - 读取 1 个 Key（控制指令队列）

## 1. 命名约定

令：
- `projectName`：外部项目名称（建议只用字母数字下划线 `A-Za-z0-9_`；如使用中文也可，但需保证统一且 UTF-8）。

固定后缀：
- 状态：`${projectName}_项目状态`
- 控制台：`${projectName}_项目控制台`
- 控制：`${projectName}_控制`

示例（projectName = `订单系统`）：
- `订单系统_项目状态`
- `订单系统_项目控制台`
- `订单系统_控制`

## 2. 外部项目需要写入的 2 个 Key

### 2.1 `${projectName}_项目状态`

- Redis 数据类型：**STRING**
- 写入方式：`SET ${projectName}_项目状态 <status>`
- value：状态枚举（必须为以下之一）
  - `在线`
  - `离线`
  - `故障`
  - `报错`

建议（非强制）：
- 定期刷新（如 5~30 秒）
- 可设置 TTL 防止僵尸在线（如 `SET key value EX 60`）

### 2.2 `${projectName}_项目控制台`

- Redis 数据类型：**LIST**（作为项目向控制台追加的“消息队列/日志队列”）
- 写入方式（推荐 FIFO）：`RPUSH ${projectName}_项目控制台 <json>`

value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息”或日志记录。

推荐 JSON Schema（字段尽量保持稳定，便于控制台解析）：
```json
{
  "timestamp": "2026-01-12T12:34:56.789Z",
  "level": "info",
  "message": "连接成功",
  "metadata": {
    "module": "redis",
    "host": "127.0.0.1"
  }
}
```

字段说明：
- `timestamp`：ISO-8601 时间字符串
- `level`：建议取值 `info|warn|error|debug`（小写）
- `message`：日志文本
- `metadata`：可选对象（附加信息）

## 3. 外部项目需要读取的 1 个 Key（控制指令）

### 3.1 `${projectName}_控制`

- Redis 数据类型：**LIST**（控制台向目标项目下发的“命令队列”）
- 队列模式（必须）：**Redis List 队列**（生产 `RPUSH`，消费 `BLPOP`；必要时配合 `LTRIM`）
- 控制台写入方式（FIFO）：`RPUSH ${targetProjectName}_控制 <json>`
- 外部项目读取方式（阻塞消费，推荐）：`BLPOP ${projectName}_控制 0`

> 说明：`BLPOP` 本身会原子性地“取出并移除”队列头元素，通常不需要额外 `LTRIM`。
> 如果你的运行环境/客户端库无法可靠使用 `BLPOP`，或你希望采用“读取 + 修剪（LTRIM）”的显式确认方式，可使用兼容模式：
> 1) `LRANGE ${projectName}_控制 0 0` 读取 1 条
> 2) 处理成功后执行 `LTRIM ${projectName}_控制 1 -1` 修剪已消费元素

value：**JSON 对象**（在 Redis 中以 JSON 字符串形式存储）。

推荐 JSON Schema：
```json
{
  "id": "cmd-1700000000000-abc123",
  "timestamp": "2026-01-12T12:35:00.000Z",
  "source": "BLS Project Console",
  "command": "reload",
  "args": {
    "force": true
  }
}
```

字段说明：
- `id`：命令唯一 ID（用于追踪）
- `timestamp`：命令下发时间
- `source`：固定可写 `BLS Project Console`
- `command`：命令名称或命令文本
- `args`：可选对象参数

## 4. 兼容与错误处理建议

- JSON 解析失败：外部项目应记录错误，并丢弃该条消息（避免死循环阻塞消费）。
- 消息过长：建议控制单条消息大小（例如 < 64KB）。
- 字符编码：统一 UTF-8。

## 5. 与本项目代码的对应关系（实现中）

后端通过 `/api/commands` 将命令写入 `${targetProjectName}_控制`；通过 `/api/logs` 读取 `${projectName}_项目控制台`（以仓库当前实现为准）。