feat: 重构项目心跳数据结构并实现项目列表API

- 新增统一项目列表Redis键和迁移工具
- 实现GET /api/projects端点获取项目列表
- 实现POST /api/projects/migrate端点支持数据迁移
- 更新前端ProjectSelector组件使用真实项目数据
- 扩展projectStore状态管理
- 更新相关文档和OpenSpec规范
- 添加测试用例验证新功能
This commit is contained in:
2026-01-13 19:45:05 +08:00
parent 19e65d78dc
commit 282f7268ed
66 changed files with 4378 additions and 456 deletions

View File

@@ -1,9 +1,11 @@
# Change: Add Console UI
## Why
需要为BLS Project Console添加一个现代化的控制台界面支持项目选择、命令输入、日志显示和调试信息展示等功能。
## What Changes
- 添加了项目选择组件,支持项目搜索和筛选
- 添加了控制台组件,支持命令输入和日志显示
- 添加了调试区域组件,支持调试信息的展示和筛选
@@ -11,5 +13,6 @@
- 实现了控制台日志管理限制最多1000条记录
## Impact
- Affected specs: specs/logging/spec.md, specs/command/spec.md
- Affected code: src/frontend/components/, src/frontend/views/, src/frontend/router/
- Affected code: src/frontend/components/, src/frontend/views/, src/frontend/router/

View File

@@ -1,4 +1,5 @@
## 1. Implementation
- [x] 1.1 Create ProjectSelector component for project selection
- [x] 1.2 Create Console component for command input and log display
- [x] 1.3 Create DebugArea component for debugging information display
@@ -10,6 +11,7 @@
- [x] 1.9 Implement console log management with 1000 record limit
## 2. Urgent Fixes
- [x] 2.1 Update openspec documentation with all changes
- [x] 2.2 Fix scrolling issues in the page
- [x] 2.3 Optimize ProjectSelector by removing filter section

View File

@@ -0,0 +1,64 @@
# Change: Refactor Project Heartbeat Data Structure
## Why
当前项目心跳数据使用分散的Redis键结构`{projectName}_项目心跳`),导致以下问题:
1. 难以统一管理和查询所有项目
2. 前端项目选择功能需要硬编码测试数据
3. 无法高效获取项目列表和状态
4. 数据迁移和维护成本高
## What Changes
- **新增**统一的项目列表Redis键`项目心跳`
- **新增**数据迁移工具,支持从旧结构迁移到新结构
- **新增**项目列表API端点`GET /api/projects`
- **新增**数据迁移API端点`POST /api/projects/migrate`
- **修改**前端ProjectSelector组件移除硬编码测试数据从API获取真实项目
- **修改**后端logs.js和commands.js支持新旧数据结构的向后兼容
- **更新**OpenSpec规范文档反映新的API和数据结构
## Impact
- Affected specs:
- `specs/logging/spec.md` - 更新日志API响应格式
- `specs/command/spec.md` - 新增项目列表和迁移API
- `specs/redis-connection/spec.md` - 新增项目列表相关API
- Affected code:
- `src/backend/services/redisKeys.js` - 新增项目列表键函数
- `src/backend/services/migrateHeartbeatData.js` - 新增数据迁移工具
- `src/backend/routes/projects.js` - 新增项目列表路由
- `src/backend/routes/logs.js` - 更新心跳读取逻辑
- `src/backend/routes/commands.js` - 更新心跳读取逻辑
- `src/backend/server.js` - 注册项目列表路由
- `src/frontend/components/ProjectSelector.vue` - 移除假数据连接API
- `src/frontend/store/projectStore.js` - 扩展状态管理
- `src/frontend/views/LogView.vue` - 连接真实API
- `src/frontend/views/CommandView.vue` - 连接真实API
- `src/frontend/views/MainView.vue` - 传递项目名称
- `src/frontend/components/Console.vue` - 接受项目名称属性
- `src/frontend/App.vue` - 修正健康检查端点
## Migration Plan
1. 执行数据迁移:调用`POST /api/projects/migrate`
2. 验证迁移结果:检查`项目心跳`键包含所有项目
3. 测试项目选择功能:确认前端能正确显示项目列表
4. 测试日志和命令功能:确认功能正常
5. 清理旧键可选调用迁移API并设置`deleteOldKeys: true`
## Backward Compatibility
系统保持向后兼容:
- 优先读取新的项目列表结构
- 如果新结构中未找到项目,回退到旧结构
- 支持平滑过渡,无需立即删除旧键
## Benefits
- 统一的项目管理,提高可维护性
- 前端显示真实项目数据,移除测试假数据
- 提高查询效率减少Redis操作次数
- 支持未来功能扩展(如项目分组、搜索等)

View File

@@ -0,0 +1,50 @@
## 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

View File

@@ -0,0 +1,55 @@
## 1. Redis数据结构重构
- [x] 1.1 在redisKeys.js中添加projectsListKey()函数
- [x] 1.2 创建数据迁移工具migrateHeartbeatData.js
- [x] 1.3 实现从分散键到统一列表的迁移逻辑
- [x] 1.4 实现getProjectsList()函数
- [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端点
- [x] 2.4 更新logs.js兼容新数据结构
- [x] 2.5 更新commands.js兼容新数据结构
- [x] 2.6 在server.js中注册项目列表路由
## 3. 前端代码修改
- [x] 3.1 更新ProjectSelector.vue移除假数据
- [x] 3.2 实现从API获取项目列表
- [x] 3.3 实现项目状态显示
- [x] 3.4 实现自动刷新功能
- [x] 3.5 更新projectStore.js扩展状态管理
- [x] 3.6 更新LogView.vue连接真实API
- [x] 3.7 更新CommandView.vue连接真实API
- [x] 3.8 更新MainView.vue传递项目名称
- [x] 3.9 更新Console.vue接受项目名称属性
- [x] 3.10 修正App.vue健康检查端点
## 4. 文档更新
- [x] 4.1 创建Redis数据结构文档
- [x] 4.2 更新logging OpenSpec规范
- [x] 4.3 更新command OpenSpec规范
- [x] 4.4 更新redis-connection OpenSpec规范
- [x] 4.5 创建OpenSpec变更提案proposal.md
- [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 性能测试和优化

View File

@@ -0,0 +1,65 @@
## Context
命令下发从 Redis 队列模式迁移为 HTTP API 调用模式。
约束:
- 输入约定来自 UI用户输入一行文本按空格拆分。
- 需要通过 `targetProjectName` 将命令路由到目标项目的 `baseUrl`
## Goals / Non-Goals
- Goals
- 控制台通过后端统一出站调用目标项目 API避免浏览器跨域/鉴权差异)
- 统一请求格式,便于目标项目实现与观测
- 明确失败行为(目标项目不可达/超时/非 2xx
- Non-Goals
- 不定义目标项目内部如何执行命令
- 不在本次变更中引入鉴权体系(如需后续可另开 change
## Decision: baseUrl mapping via env JSON
改为由目标项目的 Redis 心跳模块提供 `apiBaseUrl`
### Heartbeat key
- Redis key: `${projectName}_项目心跳`
- Redis type: STRING
- Value: JSON string
示例:
```json
{
"apiBaseUrl": "http://127.0.0.1:4001",
"lastActiveAt": 1760000000000
}
```
### Liveness rule
- 目标项目应每 3 秒刷新一次 `lastActiveAt`(毫秒时间戳)
- 若后端检测到 `now - lastActiveAt > 10_000`,则视为离线并拒绝下发
## Decision: request shape
- UI 输入:`<apiName> <arg1> <arg2> ...`
- 后端对目标项目调用:默认 `POST ${baseUrl}/${apiName}`
- bodyJSON
```json
{
"commandId": "cmd-...",
"timestamp": "ISO-8601",
"source": "BLS Project Console",
"apiName": "reload",
"args": ["a", "b"],
"argsText": "a b"
}
```
## Timeouts / retries
- 单次请求设置合理超时(例如 5s
- 默认不重试(避免重复执行产生副作用);如需重试需目标项目提供幂等语义。

View File

@@ -0,0 +1,28 @@
# Change: Command control via HTTP API (remove Redis control queue)
## Why
当前命令下发使用 Redis LIST `${targetProjectName}_控制` 作为控制队列;现需改为通过 HTTP API 直接调用目标项目,从而简化接入与减少 Redis 在“控制通道”上的耦合。
## What Changes
- **BREAKING**:命令下发不再写入 Redis `${projectName}_控制` 队列;目标项目不再需要读取控制指令 Key。
- 控制台输入规则调整:发送前按空格拆分,首个 token 为 `apiName`(接口名/路径片段),其余为参数。
- 后端 `/api/commands` 改为:通过 Redis 心跳信息解析目标项目 `apiBaseUrl`,再调用 `${apiBaseUrl}/${apiName}`(默认 POST
- 目标项目需在 Redis 写入心跳:包含 `apiBaseUrl` 与活跃时间戳(建议 3 秒刷新);后端若连续 10 秒未更新则视为离线。
- 更新对接文档:`docs/redis-integration-protocol.md` 去除“读取控制指令队列”的要求,仅保留“写状态+写控制台日志”两类 Key并新增“目标项目需暴露 HTTP 控制 API”的约定。
- 调整对接文档:使用“心跳”(包含在线判定与 API 地址)作为唯一在线来源。
## Impact
- Affected specs: command
- Affected code:
- src/backend/routes/commands.js
- src/frontend/components/Console.vue
- .env.example新增 API 调用相关可选变量)
- docs/redis-integration-protocol.md
## Migration
- 目标项目:停止读取 `${projectName}_控制`;改为提供 HTTP 接口(由 `apiName` 路由到对应动作)。
- 控制台:发送命令格式从“整行命令”迁移到“接口名 + 参数”。

View File

@@ -0,0 +1,66 @@
## MODIFIED Requirements
### Requirement: Command Sending
The system SHALL send console commands to a target project via HTTP API calls (not via Redis control queues).
#### Scenario: Sending a command to a target project API
- **WHEN** the user enters a command line in the console
- **AND** the command line contains at least one token
- **THEN** the system SHALL treat the first token as `apiName`
- **AND** the system SHALL treat remaining tokens as arguments
- **AND** the backend SHALL invoke the target project's HTTP endpoint derived from `apiName`
- **AND** the user SHALL receive a success confirmation if the target project returns a successful response
#### Scenario: Rejecting an empty command
- **WHEN** the user tries to send an empty command line
- **THEN** the system SHALL display an error message
- **AND** the backend SHALL NOT attempt any outbound call
### Requirement: Target Routing
The system SHALL route outbound calls by `targetProjectName` using the target project's Redis heartbeat info.
#### Scenario: Target project is not configured
- **WHEN** the user sends a command to a target project
- **AND** the backend cannot resolve `apiBaseUrl` from the target project's heartbeat
- **THEN** the backend SHALL return an error response
- **AND** the outbound call SHALL NOT be attempted
#### Scenario: Target project is offline
- **WHEN** the user sends a command to a target project
- **AND** the last heartbeat update is older than 10 seconds
- **THEN** the backend SHALL treat the target project as offline
- **AND** the outbound call SHALL NOT be attempted
### Requirement: Error Handling
The system SHALL handle target API failures gracefully.
#### Scenario: Target API is unreachable or times out
- **WHEN** the backend invokes the target project API
- **AND** the target project cannot be reached or times out
- **THEN** the backend SHALL return a failure response to the frontend
#### Scenario: Target API returns a non-success status
- **WHEN** the target project returns a non-2xx HTTP status
- **THEN** the backend SHALL return a failure response
- **AND** it SHOULD include the upstream status and message for debugging
## REMOVED Requirements
### Requirement: Command Sending to Redis
**Reason**: Command control channel is migrated to HTTP API calls.
**Migration**: Target projects must expose HTTP endpoints; they no longer consume `${projectName}_控制`.
### Requirement: Command Response Handling from Redis
**Reason**: Responses are returned directly via HTTP responses.
**Migration**: Any additional async responses should be written to the project's console/log channel (e.g., Redis console log LIST) if needed.

View File

@@ -0,0 +1,27 @@
## 1. OpenSpec
- [ ] 1.1 Add command spec delta for HTTP control (remove Redis control queue)
- [ ] 1.2 Add design notes for baseUrl mapping + request format
- [ ] 1.3 Run `openspec validate update-command-control-api --strict`
## 2. Backend
- [ ] 2.1 Add Redis heartbeat parsing (apiBaseUrl + lastActiveAt) and offline detection (10s)
- [ ] 2.2 Update POST `/api/commands` to parse `apiName` + args and call target HTTP API using heartbeat apiBaseUrl
- [ ] 2.3 Return structured result to frontend (success/failed + upstream status/body)
## 3. Frontend
- [ ] 3.1 Update Console send behavior + UI copy to reflect API control
- [ ] 3.2 Validate input format (needs at least apiName)
## 4. Docs
- [ ] 4.1 Update docs/redis-integration-protocol.md: remove control queue; add HTTP control API section
- [ ] 4.2 Update .env.example with new optional variables (timeouts/offline threshold)
## 5. Verify
- [ ] 5.1 Run `npm run lint`
- [ ] 5.2 Run `npm run build`
- [ ] 5.3 Smoke test backend endpoints

View File

@@ -1,13 +1,16 @@
# Change: Update Redis Integration Protocol
## Why
需要为“BLS Project Console ↔ 其他业务项目”的 Redis 交互约定一个稳定、可机器生成的协议,明确每个接入项目必须写入的状态与控制台信息,以及必须读取的控制指令队列。
## What Changes
- 统一 Redis Key 命名规则:每个项目写 2 个 key、读 1 个 key
- 明确每个 key 的 Redis 数据类型STRING/LIST与 value 格式(枚举值/JSON
- 对齐 logging / command / redis-connection 三个 capability 的 requirements以便实现端可依据 spec 开发)
## Impact
- Affected specs: specs/redis-connection/spec.md, specs/logging/spec.md, specs/command/spec.md
- Affected code (planned): src/backend/routes/, src/backend/services/, src/frontend/components/

View File

@@ -1,14 +1,17 @@
## MODIFIED Requirements
### Requirement: Command Sending to Redis
The system SHALL send commands to a per-target Redis key.
#### Scenario: Console enqueues a command for a target project
- **WHEN** the user sends a command from the console
- **THEN** the backend SHALL append a JSON message to Redis LIST key `${targetProjectName}_控制`
- **AND** the JSON message SHALL represent the command payload (an object)
#### Scenario: Target project consumes a command
- **WHEN** a target project listens for commands
- **THEN** it SHALL consume messages from `${projectName}_控制` as JSON objects
- **AND** it SHOULD use Redis LIST queue semantics (producer `RPUSH`, consumer `BLPOP`)

View File

@@ -1,14 +1,17 @@
## MODIFIED Requirements
### Requirement: Log Reading from Redis
The system SHALL read log records from per-project Redis keys.
#### Scenario: External project writes console logs
- **WHEN** an external project emits debug/error information
- **THEN** it SHALL append entries to a Redis LIST key named `${projectName}_项目控制台`
- **AND** each entry SHALL be a JSON string representing a log record
#### Scenario: Server reads project console logs
- **WHEN** the server is configured to show a given project
- **THEN** it SHALL read entries from `${projectName}_项目控制台`
- **AND** it SHALL present them in the console UI with timestamp, level and message

View File

@@ -1,9 +1,11 @@
## ADDED Requirements
### Requirement: Per-Project Status Key
The system SHALL standardize a per-project Redis status key for connected projects.
### Requirement: Per-Project Heartbeat Key
The system SHALL standardize a per-project Redis heartbeat key for connected projects.
#### Scenario: External project writes heartbeat
#### Scenario: External project writes status
- **WHEN** an external project integrates with this console
- **THEN** it SHALL write a Redis STRING key named `${projectName}_项目状态`
- **AND** the value SHALL be one of: `在线`, `离线`, `故障`, `报错`
- **THEN** it SHALL write a Redis STRING key named `${projectName}_项目心跳`
- **AND** the value SHALL be a JSON string containing `apiBaseUrl` and `lastActiveAt`

View File

@@ -1,13 +1,16 @@
## 1. Documentation
- [x] 1.1 Add Redis integration protocol doc for external projects
- [ ] 1.2 Link doc location from README (optional)
## 2. Backend
- [x] 2.1 Add Redis client config + connection helper
- [x] 2.2 Implement command enqueue: write `${targetProjectName}_控制` LIST with JSON payload
- [x] 2.3 Implement log fetch/stream: read `${projectName}_项目控制台` LIST (and status `${projectName}_项目状态` STRING when needed)
- [x] 2.3 Implement log fetch/stream: read `${projectName}_项目控制台` LIST
## 3. Frontend
- [x] 3.1 Wire selected project name into Console (targetProjectName)
- [x] 3.2 Replace simulated command send with API call to backend
- [x] 3.3 Replace simulated logs with backend-provided logs (polling or SSE)