Web_BLS_ProjectConsole/openspec/specs/logging/spec.md

# Logging Capability Specification

## Overview

This specification defines the logging capability for the BLS Project Console, which allows the system to read log records from Redis queues and display them in the console interface.

## Requirements

### Requirement: Log Reading from Redis

The system SHALL read log records from a Redis queue.

#### Scenario: Reading logs from Redis queue

- **WHEN** the server starts
- **THEN** it SHALL establish a connection to the Redis queue
- **AND** it SHALL begin listening for new log records
- **AND** it SHALL store log records in memory for display

### Requirement: Log Display in Console

The system SHALL display log records in a user-friendly format.

#### Scenario: Displaying logs in the console

- **WHEN** a log record is received from Redis
- **THEN** it SHALL be added to the log list in the console
- **AND** it SHALL display the log timestamp, level, and message
- **AND** it SHALL support scrolling through historical logs

### Requirement: Log Filtering

The system SHALL allow users to filter logs by level and time range.

#### Scenario: Filtering logs by level

- **WHEN** the user selects a log level filter
- **THEN** only logs with the selected level SHALL be displayed

#### Scenario: Filtering logs by time range

- **WHEN** the user selects a time range
- **THEN** only logs within the specified range SHALL be displayed

### Requirement: Log Auto-Refresh

The system SHALL automatically refresh logs in real-time.

#### Scenario: Real-time log updates

- **WHEN** a new log is added to the Redis queue
- **THEN** it SHALL be automatically displayed in the console
- **AND** the console SHALL scroll to the latest log if the user is viewing the end

## Data Model

### Log Record

```json
{
  "id": "string",
  "timestamp": "ISO-8601 string",
  "level": "string", // e.g., INFO, WARN, ERROR, DEBUG
  "message": "string",
  "metadata": "object" // optional additional data
}
```

## API Endpoints

### GET /api/logs

- **Description**: Get log records for a specific project
- **Query Parameters**:
  - `projectName`: Project name (required)
  - `limit`: Maximum number of logs to return (default: 200)
- **Response**:
  ```json
  {
    "logs": [
      {
        "id": "string",
        "timestamp": "ISO-8601 string",
        "level": "string",
        "message": "string",
        "metadata": "object"
      }
    ],
    "projectStatus": "在线|离线|null",
    "heartbeat": {
      "apiBaseUrl": "string",
      "lastActiveAt": "number",
      "isOnline": "boolean",
      "ageMs": "number"
    }
  }
  ```

### GET /api/logs/live

- **Description**: Establish a WebSocket connection for real-time log updates
- **Response**: Continuous stream of log records