Web_BLS_ProjectConsole/openspec/specs/command/spec.md

Command Capability Specification

Overview

This specification defines the command capability for the BLS Project Console, which allows users to send console commands to Redis queues for other programs to read and execute.

Requirements

Requirement: Command Sending to Redis

The system SHALL send commands to a Redis queue.

Scenario: Sending a command to Redis queue

• WHEN the user enters a command in the console
• AND clicks the "Send" button
• THEN the command SHALL be sent to the Redis queue
• AND the user SHALL receive a success confirmation

Requirement: Command Validation

The system SHALL validate commands before sending them to Redis.

Scenario: Validating an empty command

• WHEN the user tries to send an empty command
• THEN the system SHALL display an error message
• AND the command SHALL NOT be sent to Redis

Scenario: Validating a command with invalid characters

• WHEN the user tries to send a command with invalid characters
• THEN the system SHALL display an error message
• AND the command SHALL NOT be sent to Redis

Requirement: Command History

The system SHALL maintain a history of sent commands.

Scenario: Viewing command history

• WHEN the user opens the command history
• THEN the system SHALL display a list of previously sent commands
• AND the user SHALL be able to select a command from the history to resend

Requirement: Command Response Handling

The system SHALL handle responses from commands sent to Redis.

Scenario: Receiving a command response

• WHEN a command response is received from Redis
• THEN the system SHALL display the response in the console
• AND the response SHALL be associated with the original command

Data Model

Command

{
  "id": "string",
  "content": "string",
  "timestamp": "ISO-8601 string",
  "status": "string" // e.g., sent, processing, completed, failed
}

Command Response

{
  "id": "string",
  "commandId": "string",
  "timestamp": "ISO-8601 string",
  "status": "string", // e.g., success, failure
  "result": "string" // command execution result
}

API Endpoints

POST /api/commands

• Description: Send a command to a project's API endpoint
• Request Body:

  {
    "targetProjectName": "string",
    "command": "string"
  }
  

• Response:

  {
    "success": true,
    "message": "已调用目标项目 API",
    "commandId": "string",
    "targetUrl": "string",
    "upstreamStatus": 200,
    "upstreamData": "object"
  }
  

GET /api/projects

• Description: Get list of all projects with their heartbeat status
• 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
  }
  

GET /api/commands/history

• Description: Get command history (deprecated - use project logs instead)
• Query Parameters:
  • limit: Maximum number of commands to return (default: 50)
  • offset: Offset for pagination (default: 0)
• Response: Array of command objects

GET /api/commands/:id/response

• Description: Get response for a specific command (deprecated - use project logs instead)
• Response: Command response object