feat: 重构项目心跳数据结构并实现相关功能

- 重构Redis心跳数据结构，使用统一的项目列表键 - 新增数据迁移工具和API端点 - 更新前端以使用真实项目数据 - 添加系统部署配置和文档 - 修复代码格式和样式问题
2026-01-15 14:14:10 +08:00
parent 282f7268ed
commit a8faa7dcaa
24 changed files with 307 additions and 560 deletions
--- a/openspec/changes/refactor-project-heartbeat/proposal.md
+++ b/openspec/changes/refactor-project-heartbeat/proposal.md
@@ -1,16 +1,13 @@
 # Change: Refactor Project Heartbeat Data Structure

 ## Why
-
 当前项目心跳数据使用分散的Redis键结构（`{projectName}_项目心跳`），导致以下问题：
-
 1. 难以统一管理和查询所有项目
 2. 前端项目选择功能需要硬编码测试数据
 3. 无法高效获取项目列表和状态
 4. 数据迁移和维护成本高

 ## What Changes
-
 - **新增**统一的项目列表Redis键：`项目心跳`
 - **新增**数据迁移工具，支持从旧结构迁移到新结构
 - **新增**项目列表API端点：`GET /api/projects`
@@ -20,8 +17,7 @@
 - **更新**OpenSpec规范文档，反映新的API和数据结构

 ## Impact
-
- Affected specs:
+- Affected specs: 
  - `specs/logging/spec.md` - 更新日志API响应格式
  - `specs/command/spec.md` - 新增项目列表和迁移API
  - `specs/redis-connection/spec.md` - 新增项目列表相关API
@@ -41,7 +37,6 @@
  - `src/frontend/App.vue` - 修正健康检查端点

 ## Migration Plan
-
 1. 执行数据迁移：调用`POST /api/projects/migrate`
 2. 验证迁移结果：检查`项目心跳`键包含所有项目
 3. 测试项目选择功能：确认前端能正确显示项目列表
@@ -49,16 +44,13 @@
 5. 清理旧键（可选）：调用迁移API并设置`deleteOldKeys: true`

 ## Backward Compatibility
-
 系统保持向后兼容：
-
 - 优先读取新的项目列表结构
 - 如果新结构中未找到项目，回退到旧结构
 - 支持平滑过渡，无需立即删除旧键

 ## Benefits
-
 - 统一的项目管理，提高可维护性
 - 前端显示真实项目数据，移除测试假数据
 - 提高查询效率，减少Redis操作次数
- 支持未来功能扩展（如项目分组、搜索等）
+- 支持未来功能扩展（如项目分组、搜索等）
--- a/openspec/changes/refactor-project-heartbeat/specs/redis-connection/spec.md
+++ b/openspec/changes/refactor-project-heartbeat/specs/redis-connection/spec.md
@@ -1,50 +1,41 @@
 ## ADDED Requirements

 ### Requirement: Project List Management
-
 The system SHALL provide a unified project list structure in Redis to manage all project heartbeats.

 #### Scenario: Getting all projects
-
 - **WHEN** the user requests the project list
 - **THEN** the system SHALL return all projects with their heartbeat status
 - **AND** each project SHALL include: project name, API base URL, last active time, and online status

 #### Scenario: Project status calculation
-
 - **WHEN** calculating project status
 - **THEN** the system SHALL determine online/offline based on last active time and offline threshold
 - **AND** the system SHALL return the age in milliseconds

 ### Requirement: Data Migration Support
-
 The system SHALL support migrating heartbeat data from old structure to new unified structure.

 #### Scenario: Migrating heartbeat data
-
 - **WHEN** the migration process is triggered
 - **THEN** the system SHALL read all old heartbeat keys
 - **AND** convert them to the new unified list structure
 - **AND** optionally delete old keys after successful migration

 #### Scenario: Dry run migration
-
 - **WHEN** migration is executed with dryRun flag
 - **THEN** the system SHALL validate data without writing
 - **AND** return the migration result for review

 ### Requirement: Backward Compatibility
-
 The system SHALL maintain backward compatibility with old heartbeat data structure.

 #### Scenario: Reading from new structure
-
 - **WHEN** reading project heartbeat
 - **THEN** the system SHALL first try to read from the new unified list
 - **AND** fall back to old structure if not found

 #### Scenario: Gradual migration
-
 - **WHEN** old structure data is detected
 - **THEN** the system SHALL continue to work with old data
- **AND** allow migration at a later time
+- **AND** allow migration at a later time
--- a/openspec/changes/refactor-project-heartbeat/tasks.md
+++ b/openspec/changes/refactor-project-heartbeat/tasks.md
@@ -1,5 +1,4 @@
 ## 1. Redis数据结构重构
-
 - [x] 1.1 在redisKeys.js中添加projectsListKey()函数
 - [x] 1.2 创建数据迁移工具migrateHeartbeatData.js
 - [x] 1.3 实现从分散键到统一列表的迁移逻辑
@@ -7,7 +6,6 @@
 - [x] 1.5 实现updateProjectHeartbeat()函数

 ## 2. 后端API开发
-
 - [x] 2.1 创建项目列表API routes/projects.js
 - [x] 2.2 实现GET /api/projects端点
 - [x] 2.3 实现POST /api/projects/migrate端点
@@ -16,7 +14,6 @@
 - [x] 2.6 在server.js中注册项目列表路由

 ## 3. 前端代码修改
-
 - [x] 3.1 更新ProjectSelector.vue移除假数据
 - [x] 3.2 实现从API获取项目列表
 - [x] 3.3 实现项目状态显示
@@ -29,7 +26,6 @@
 - [x] 3.10 修正App.vue健康检查端点

 ## 4. 文档更新
-
 - [x] 4.1 创建Redis数据结构文档
 - [x] 4.2 更新logging OpenSpec规范
 - [x] 4.3 更新command OpenSpec规范
@@ -38,18 +34,16 @@
 - [x] 4.6 创建OpenSpec变更提案tasks.md

 ## 5. 测试开发
-
 - [ ] 5.1 编写数据迁移单元测试
 - [ ] 5.2 编写项目列表API集成测试
 - [ ] 5.3 编写ProjectSelector组件测试
 - [ ] 5.4 编写性能测试

 ## 6. 代码质量与验证
-
 - [ ] 6.1 运行ESLint检查
 - [ ] 6.2 运行Prettier格式化
 - [ ] 6.3 验证项目选择功能
 - [ ] 6.4 验证日志读取功能
 - [ ] 6.5 验证命令发送功能
 - [ ] 6.6 验证数据迁移功能
- [ ] 6.7 性能测试和优化
+- [ ] 6.7 性能测试和优化
--- a/openspec/specs/command/spec.md
+++ b/openspec/specs/command/spec.md
@@ -1,54 +1,44 @@
 # 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
@@ -56,7 +46,6 @@ The system SHALL handle responses from commands sent to Redis.
 ## Data Model

 ### Command
-
 ```json
 {
  "id": "string",
@@ -67,7 +56,6 @@ The system SHALL handle responses from commands sent to Redis.
 ```

 ### Command Response
-
 ```json
 {
  "id": "string",
@@ -81,7 +69,6 @@ The system SHALL handle responses from commands sent to Redis.
 ## API Endpoints

 ### POST /api/commands
-
 - **Description**: Send a command to a project's API endpoint
 - **Request Body**:
  ```json
@@ -103,7 +90,6 @@ The system SHALL handle responses from commands sent to Redis.
  ```

 ### GET /api/projects
-
 - **Description**: Get list of all projects with their heartbeat status
 - **Response**:
  ```json
@@ -125,7 +111,6 @@ The system SHALL handle responses from commands sent to Redis.
  ```

 ### POST /api/projects/migrate
-
 - **Description**: Migrate heartbeat data from old structure to new unified structure
 - **Request Body**:
  ```json
@@ -147,7 +132,6 @@ The system SHALL handle responses from commands sent to Redis.
  ```

 ### GET /api/commands/history
-
 - **Description**: Get command history (deprecated - use project logs instead)
 - **Query Parameters**:
  - `limit`: Maximum number of commands to return (default: 50)
@@ -155,6 +139,5 @@ The system SHALL handle responses from commands sent to Redis.
 - **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
--- a/openspec/specs/logging/spec.md
+++ b/openspec/specs/logging/spec.md
@@ -1,53 +1,43 @@
 # 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
@@ -55,7 +45,6 @@ The system SHALL automatically refresh logs in real-time.
 ## Data Model

 ### Log Record
-
 ```json
 {
  "id": "string",
@@ -69,7 +58,6 @@ The system SHALL automatically refresh logs in real-time.
 ## API Endpoints

 ### GET /api/logs
-
 - **Description**: Get log records for a specific project
 - **Query Parameters**:
  - `projectName`: Project name (required)
@@ -97,6 +85,5 @@ The system SHALL automatically refresh logs in real-time.
  ```

 ### GET /api/logs/live
-
 - **Description**: Establish a WebSocket connection for real-time log updates
 - **Response**: Continuous stream of log records
--- a/openspec/specs/redis-connection/spec.md
+++ b/openspec/specs/redis-connection/spec.md
@@ -1,59 +1,48 @@
 # 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 sending commands.

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

 ### 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
@@ -61,7 +50,6 @@ The system SHALL monitor the Redis connection status.
 ## Data Model

 ### Redis Connection Configuration
-
 ```json
 {
  "host": "string",
@@ -77,7 +65,6 @@ The system SHALL monitor the Redis connection status.
 ```

 ### Redis Connection Status
-
 ```json
 {
  "status": "string", // e.g., connecting, connected, disconnected, error
@@ -90,7 +77,6 @@ The system SHALL monitor the Redis connection status.
 ## API Endpoints

 ### GET /api/redis/status
-
 - **Description**: Get Redis connection status
 - **Response**:
  ```json
@@ -103,7 +89,6 @@ The system SHALL monitor the Redis connection status.
  ```

 ### POST /api/redis/reconnect
-
 - **Description**: Manually reconnect to Redis
 - **Response**:
  ```json
@@ -114,7 +99,6 @@ The system SHALL monitor the Redis connection status.
  ```

 ### GET /api/projects
-
 - **Description**: Get list of all projects from Redis
 - **Response**:
  ```json
@@ -136,7 +120,6 @@ The system SHALL monitor the Redis connection status.
  ```

 ### POST /api/projects/migrate
-
 - **Description**: Migrate heartbeat data from old structure to new unified structure
 - **Request Body**:
  ```json