XuJiacheng
a8faa7dcaa
- 重构Redis心跳数据结构，使用统一的项目列表键 - 新增数据迁移工具和API端点 - 更新前端以使用真实项目数据 - 添加系统部署配置和文档 - 修复代码格式和样式问题
6.0 KiB
6.0 KiB
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- 项目列表APIsrc/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- 移除假数据，连接APIsrc/frontend/store/projectStore.js- 扩展状态管理src/frontend/views/LogView.vue- 连接真实APIsrc/frontend/views/CommandView.vue- 连接真实APIsrc/frontend/App.vue- 修正健康检查端点openspec/specs/logging/spec.md- 更新规范openspec/specs/command/spec.md- 更新规范openspec/specs/redis-connection/spec.md- 更新规范
⚠️ 风险与注意事项
- 数据迁移风险：确保迁移过程中数据不丢失
- 向后兼容性：保持现有API的兼容性
- 性能影响：大量项目时需要优化查询性能
- 测试覆盖：确保所有修改都有对应的测试
✅ 验收标准
- ✅ 界面只展示真实有效的项目数据
- ✅ Redis数据结构统一为项目列表
- ✅ 所有相关代码与新数据结构兼容
- ✅ 文档和规范已更新
- ✅ 所有测试通过
- ✅ 代码符合项目规范
- ✅ 性能满足要求
📊 预期成果
- 修复界面显示问题，移除测试假数据
- 统一Redis数据结构，提高可维护性
- 完善测试覆盖，提高代码质量
- 更新文档和规范，保持一致性
- 提供完整的变更记录和测试报告