Web_BLS_ProjectConsole/openspec/specs/redis-connection/spec.md

Redis Connection Capability Specification

Overview

This specification defines the Redis connection capability for the BLS Project Console, which manages the connection between the system and the Redis server for reading logs and retrieving project heartbeats.

Requirements

Requirement: Redis Connection Establishment

The system SHALL establish a connection to the Redis server.

Scenario: Establishing Redis connection on server start

• WHEN the server starts
• THEN it SHALL attempt to connect to the Redis server
• AND it SHALL log the connection status

Requirement: Redis Connection Configuration

The system SHALL allow configuration of Redis connection parameters.

Scenario: Configuring Redis connection via environment variables

• WHEN the server starts with Redis environment variables set
• THEN it SHALL use those variables to configure the Redis connection
• AND it SHALL override default values
• AND it SHALL use Redis database 15

Requirement: Redis Connection Reconnection

The system SHALL automatically reconnect to Redis if the connection is lost.

Scenario: Reconnecting to Redis after connection loss

• WHEN the Redis connection is lost
• THEN the system SHALL attempt to reconnect with exponential backoff
• AND it SHALL log each reconnection attempt
• AND it SHALL notify the user when connection is restored

Requirement: Redis Connection Error Handling

The system SHALL handle Redis connection errors gracefully.

Scenario: Handling Redis connection failure

• WHEN the system fails to connect to Redis
• THEN it SHALL log the error
• AND it SHALL display an error message to the user
• AND it SHALL continue attempting to reconnect

Requirement: Redis Connection Monitoring

The system SHALL monitor the Redis connection status.

Scenario: Monitoring Redis connection status

• WHEN the Redis connection status changes
• THEN the system SHALL update the connection status in the UI
• AND it SHALL log the status change

Requirement: Project Heartbeat List Retrieval

The system SHALL read project heartbeats from Redis key 项目心跳 stored as a LIST.

Scenario: Reading projects list from Redis LIST

• WHEN the client requests the projects list
• THEN the system SHALL read LRANGE 项目心跳 0 -1
• AND it SHALL parse each list element as JSON heartbeat record
• AND it SHALL deduplicate by projectName and keep the latest lastActiveAt

Data Model

Redis Connection Configuration

{
  "host": "string",
  "port": "number",
  "password": "string",
  "db": "number",
  "socket": {
    "reconnectStrategy": "function",
    "connectTimeout": "number",
    "keepAlive": "number"
  }
}

Redis Connection Status

{
  "status": "string", // e.g., connecting, connected, disconnected, error
  "lastConnectedAt": "ISO-8601 string",
  "lastDisconnectedAt": "ISO-8601 string",
  "error": "string" // optional error message
}

API Endpoints

GET /api/redis/status

• Description: Get Redis connection status
• Response:

  {
    "status": "string",
    "lastConnectedAt": "ISO-8601 string",
    "lastDisconnectedAt": "ISO-8601 string",
    "error": "string"
  }
  

POST /api/redis/reconnect

• Description: Manually reconnect to Redis
• Response:

  {
    "success": true,
    "message": "Reconnection attempt initiated"
  }
  

GET /api/projects

• Description: Get list of all projects from Redis
• Response:

  {
    "success": true,
    "projects": [
      {
        "id": "string",
        "name": "string",
        "apiBaseUrl": "string",
        "lastActiveAt": "number",
        "status": "online|offline|unknown",
        "isOnline": "boolean",
        "ageMs": "number"
      }
    ],
    "count": 10
  }
  

POST /api/projects/migrate

• Description: Migrate heartbeat data from old structure to new unified structure
• Request Body:

  {
    "deleteOldKeys": false,
    "dryRun": false
  }
  

• Response:

  {
    "success": true,
    "message": "数据迁移完成",
    "migrated": 5,
    "projects": [...],
    "listKey": "项目心跳",
    "deleteOldKeys": false
  }
  

Redis Data Structures

Key: 项目心跳

• Type: LIST
• Element: JSON string {"projectName":"...","apiBaseUrl":"...","lastActiveAt":1768566165572}