XuJiacheng
a8faa7dcaa
- 重构Redis心跳数据结构，使用统一的项目列表键 - 新增数据迁移工具和API端点 - 更新前端以使用真实项目数据 - 添加系统部署配置和文档 - 修复代码格式和样式问题
184 lines
6.0 KiB
Markdown
184 lines
6.0 KiB
Markdown
# 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数据结构，提高可维护性
|
||
- 完善测试覆盖，提高代码质量
|
||
- 更新文档和规范，保持一致性
|
||
- 提供完整的变更记录和测试报告 |