Web_BLS_ProjectConsole/.trae/documents/BLS Project Console 系统功能优化与修复.md

# BLS Project Console 系统功能优化与修复计划

## 📋 任务概述
完成界面显示修复、Redis数据结构重构、相关代码修改、文档更新和测试验证。

## 🔍 当前问题分析

### 1. 界面显示问题
- **ProjectSelector.vue** (第54-97行) 包含硬编码的6个测试假数据
- 没有从Redis读取真实项目心跳数据
- 界面展示的是静态测试数据，而非真实有效的项目

### 2. Redis数据结构问题
- 当前使用分散的键：`{projectName}_项目心跳`
- 每个项目的心跳数据独立存储，难以统一管理
- 缺少统一的项目列表查询机制

### 3. 后端API现状
- **logs.js** 和 **commands.js** 都从 `{projectName}_项目心跳` 读取数据
- **redisKeys.js** 定义了 `projectHeartbeatKey(projectName)` 函数
- 缺少获取所有项目列表的API端点

### 4. 测试缺失
- 项目中没有测试文件
- 缺少单元测试和集成测试

## 🎯 实施计划

### 阶段1：Redis数据结构重构

#### 1.1 新增Redis键定义
- 在 `redisKeys.js` 中添加 `projectsListKey()` 函数
- 定义统一的项目列表键：`项目心跳`

#### 1.2 创建数据迁移工具
- 创建 `src/backend/services/migrateHeartbeatData.js`
- 实现从分散键到统一列表的迁移逻辑
- 确保数据完整性和一致性

#### 1.3 更新心跳数据结构
- 新结构：`[{ "apiBaseUrl": "...", "lastActiveAt": 1234567890, "projectName": "..." }]`
- 每个对象包含：API地址、最新心跳时间、项目名称

### 阶段2：后端API开发

#### 2.1 创建项目列表API
- 在 `src/backend/routes/` 下创建 `projects.js`
- 实现 `GET /api/projects` 端点
- 从Redis读取项目列表并返回

#### 2.2 更新现有API
- 修改 `logs.js` 以兼容新的数据结构
- 修改 `commands.js` 以兼容新的数据结构
- 保持向后兼容性

#### 2.3 添加数据迁移端点
- 实现 `POST /api/projects/migrate` 端点
- 支持手动触发数据迁移

### 阶段3：前端代码修改

#### 3.1 更新ProjectSelector组件
- 移除硬编码的测试数据（第54-97行）
- 从 `/api/projects` 获取真实项目列表
- 实现数据加载状态和错误处理

#### 3.2 更新projectStore
- 扩展状态管理以支持项目列表
- 添加项目列表的响应式状态

#### 3.3 更新LogView和CommandView
- 连接到真实API端点
- 实现日志和命令的真实功能
- 添加错误处理和用户反馈

#### 3.4 更新App.vue
- 修正健康检查端点（从3000改为3001）
- 确保服务状态监控正常工作

### 阶段4：文档更新

#### 4.1 更新技术文档
- 创建或更新 `docs/redis-data-structure.md`
- 详细说明新的Redis数据结构设计
- 提供数据迁移指南

#### 4.2 更新OpenSpec规范
- 更新 `openspec/specs/logging/spec.md`
- 更新 `openspec/specs/command/spec.md`
- 更新 `openspec/specs/redis-connection/spec.md`
- 添加项目列表相关需求

#### 4.3 创建OpenSpec变更提案
- 创建 `openspec/changes/refactor-project-heartbeat/`
- 编写 `proposal.md`、`tasks.md` 和规范增量

### 阶段5：测试开发

#### 5.1 单元测试
- 创建 `src/backend/services/__tests__/migrateHeartbeatData.test.js`
- 测试数据迁移功能
- 测试Redis键操作

#### 5.2 集成测试
- 创建 `src/backend/routes/__tests__/projects.test.js`
- 测试项目列表API
- 测试数据迁移API

#### 5.3 前端测试
- 创建 `src/frontend/components/__tests__/ProjectSelector.test.js`
- 测试组件渲染和交互

#### 5.4 性能测试
- 测试不同项目数量下的性能
- 测试不同心跳频率下的性能

### 阶段6：代码质量与验证

#### 6.1 代码规范检查
- 运行 ESLint 检查
- 运行 Prettier 格式化
- 确保符合项目代码规范

#### 6.2 功能验证
- 验证项目选择功能正常
- 验证日志读取功能正常
- 验证命令发送功能正常

#### 6.3 性能验证
- 测试大量项目场景
- 测试高频心跳场景
- 优化性能瓶颈

## 📁 文件修改清单

### 新增文件
- `src/backend/services/migrateHeartbeatData.js` - 数据迁移工具
- `src/backend/routes/projects.js` - 项目列表API
- `src/backend/services/__tests__/migrateHeartbeatData.test.js` - 迁移测试
- `src/backend/routes/__tests__/projects.test.js` - API测试
- `src/frontend/components/__tests__/ProjectSelector.test.js` - 组件测试
- `docs/redis-data-structure.md` - 数据结构文档
- `openspec/changes/refactor-project-heartbeat/proposal.md` - 变更提案
- `openspec/changes/refactor-project-heartbeat/tasks.md` - 任务清单
- `openspec/changes/refactor-project-heartbeat/specs/` - 规范增量

### 修改文件
- `src/backend/services/redisKeys.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/App.vue` - 修正健康检查端点
- `openspec/specs/logging/spec.md` - 更新规范
- `openspec/specs/command/spec.md` - 更新规范
- `openspec/specs/redis-connection/spec.md` - 更新规范

## ⚠️ 风险与注意事项

1. **数据迁移风险**：确保迁移过程中数据不丢失
2. **向后兼容性**：保持现有API的兼容性
3. **性能影响**：大量项目时需要优化查询性能
4. **测试覆盖**：确保所有修改都有对应的测试

## ✅ 验收标准

1. ✅ 界面只展示真实有效的项目数据
2. ✅ Redis数据结构统一为项目列表
3. ✅ 所有相关代码与新数据结构兼容
4. ✅ 文档和规范已更新
5. ✅ 所有测试通过
6. ✅ 代码符合项目规范
7. ✅ 性能满足要求

## 📊 预期成果

- 修复界面显示问题，移除测试假数据
- 统一Redis数据结构，提高可维护性
- 完善测试覆盖，提高代码质量
- 更新文档和规范，保持一致性
- 提供完整的变更记录和测试报告