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 target project HTTP APIs.

## Requirements

### Requirement: Command Sending to Redis
The system SHALL send commands to a target project's HTTP API.

#### Scenario: Sending a command to target project API
- **WHEN** the user enters a command in the console
- **AND** clicks the "Send" button
- **THEN** the backend SHALL resolve `apiBaseUrl` from the project's heartbeat
- **AND** it SHALL call `POST {apiBaseUrl}/{apiName}` with a structured payload
- **AND** the user SHALL receive a success confirmation if upstream returns 2xx

### Requirement: Command Validation
The system SHALL validate commands before sending them to target project API.

#### 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

#### 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

### Requirement: Command History
The system SHALL maintain a history of sent commands in the console UI.

#### 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 target project API.

#### Scenario: Receiving a command response
- **WHEN** the target project API responds
- **THEN** the system SHALL display the response status in the console

## Data Model

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

### Command Response
```json
{
  "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**:
  ```json
  {
    "targetProjectName": "string",
    "command": "string"
  }
  ```
- **Response**:
  ```json
  {
    "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**:
  ```json
  {
    "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**:
  ```json
  {
    "deleteOldKeys": false,
    "dryRun": false
  }
  ```
- **Response**:
  ```json
  {
    "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