ljwx-health/ljwx-bigscreen-bak/REFACTOR_PLAN_V2.md

LJWX BigScreen 重构计划 V2.0

📋 项目信息

• 项目名称: LJWX BigScreen - 架构级重构
• 开始日期: 2026-01-05
• 执行者: Claude AI + Bruno Gao
• 重构策略: 重新设计架构 + 渐进式迁移（非简单代码抽取）
• 文档版本: v2.0

---

🎯 核心目标

当前问题分析

问题	当前实现	影响	优先级
1. 数据刷新粗暴	get_total_info 一次性获取所有数据，无法精细化刷新	高频组件（告警/消息）无法独立刷新，性能浪费	🔴 P0
2. 地图逻辑混乱	1400+ 行代码，健康点/告警点逻辑混杂，依赖复杂	维护困难，扩展性差	🔴 P0
3. 组件初始化低效	先初始化空图表，后刷新数据，重复渲染	首屏加载慢，白屏时间长	🟠 P1
4. 二级页面数据传递不优雅	全局变量 + iframe，数据传递混乱	代码耦合，难以调试	🟠 P1
5. 前后端 API 未完全对接	部分 API 调用失败需要降级，缺少统一适配层	错误处理复杂，用户体验差	🟡 P2

重构目标

目标	成功标准	验收指标
精细化数据刷新	每个模块独立刷新，按需设置刷新频率	告警 3s、消息 5s、统计 60s
简化地图逻辑	地图代码 < 300 行，清晰的图层管理	代码减少 75%，可读性提升
组件按需初始化	只在有数据时初始化，避免重复渲染	首屏加载时间减少 30%
优雅数据传递	事件总线 + PostMessage，无全局变量	代码解耦，消除 window.modalData
统一 API 适配	统一请求层，自动降级和缓存	API 失败率 < 1%，缓存命中率 > 80%

---

🏗️ 新架构设计

架构图

┌─────────────────────────────────────────────────────────────┐
│                     LJWX BigScreen V2.0                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Presentation │  │   Business   │  │     Data     │      │
│  │     Layer     │  │     Layer    │  │    Layer     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│         │                  │                  │              │
│         ▼                  ▼                  ▼              │
│  ┌─────────────────────────────────────────────────┐       │
│  │            Component Manager                     │       │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐        │       │
│  │  │MapLayer  │ │AlertPanel│ │DevicePanel│        │       │
│  │  └──────────┘ └──────────┘ └──────────┘        │       │
│  └─────────────────────────────────────────────────┘       │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────────────────┐       │
│  │            Data Manager (核心)                   │       │
│  │  - 数据分层缓存                                  │       │
│  │  - 精细化刷新 (3s/5s/30s/60s)                   │       │
│  │  - 事件发布订阅                                  │       │
│  └─────────────────────────────────────────────────┘       │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────────────────┐       │
│  │            API Adapter                           │       │
│  │  - 统一请求封装                                  │       │
│  │  - 自动降级处理                                  │       │
│  │  - 请求缓存                                      │       │
│  └─────────────────────────────────────────────────┘       │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────────────────┐       │
│  │            Backend APIs                          │       │
│  │  /api/map/user-locations                        │       │
│  │  /api/alerts/pending                             │       │
│  │  /api/messages/unread                            │       │
│  │  /api/devices/stats                              │       │
│  └─────────────────────────────────────────────────┘       │
│                                                               │
└─────────────────────────────────────────────────────────────┘

模块职责划分

1. Data Layer（数据层）

data-manager.js - 数据管理器（核心模块）

职责：
✅ 数据分层缓存（Map、Alerts、Messages、Devices、Stats、Health）
✅ 精细化刷新调度（不同模块不同刷新频率）
✅ 事件发布订阅（数据更新通知组件）
✅ 数据预处理和转换

API：
- refreshMap() → Promise<MapData>
- refreshAlerts() → Promise<AlertData>
- refreshMessages() → Promise<MessageData>
- refreshDevices() → Promise<DeviceData>
- refreshStats() → Promise<StatsData>
- refreshHealth() → Promise<HealthData>
- startAutoRefresh() → void
- on(event, callback) → void
- emit(event, data) → void

api-adapter.js - API 适配器

职责：
✅ 统一 HTTP 请求封装
✅ 请求/响应拦截器
✅ 自动降级处理
✅ 请求缓存（基于 TTL）
✅ 错误分类和重试

API：
- request(endpoint, options) → Promise<Response>
- get(url, params) → Promise<Data>
- post(url, data) → Promise<Data>
- setFallbackData(endpoint, data) → void
- clearCache(pattern) → void

2. Business Layer（业务层）

component-manager.js - 组件管理器

职责：
✅ 组件生命周期管理（延迟初始化）
✅ 组件注册和销毁
✅ 组件状态管理
✅ 组件间通信协调

API：
- register(name, component) → void
- initComponent(name, data) → Promise<void>
- updateComponent(name, data) → void
- destroyComponent(name) → void
- getComponent(name) → Component

event-bus.js - 事件总线

职责：
✅ 全局事件发布订阅
✅ 跨 iframe 消息通信（PostMessage）
✅ 事件日志和调试

API：
- on(event, callback) → void
- emit(event, data) → void
- off(event, callback) → void
- sendToModal(modalId, data) → void
- onModalMessage(callback) → void

3. Presentation Layer（展示层）

map-layer.js - 地图图层管理器（重写）

职责：
✅ 高德地图初始化
✅ 图层分类管理（健康点/告警点/严重告警点）
✅ Loca 呼吸光圈渲染
✅ 点击事件处理

核心逻辑：
- 根据用户健康状态分组（healthy/warning/critical）
- 使用不同颜色的 Loca 图层渲染
- 点击显示用户详情

代码目标：< 300 行（当前 1400+ 行）

alert-panel-v2.js - Alert Panel V2（重写）

职责：
✅ 告警数据展示（ECharts）
✅ 告警筛选和排序
✅ 告警处理交互

优化：
- 按需初始化（只在有数据时创建图表）
- 数据驱动更新（避免重复渲染）
- 事件解耦（通过 EventBus 通信）

device-panel-v2.js - Device Panel V2（重写）

职责：
✅ 设备统计展示（ECharts）
✅ 设备状态筛选
✅ 设备详情查看

优化：
- 统一图表配置生成器
- 数据转换层（后端数据 → 图表数据）

message-panel-v2.js - Message Panel V2（重写）

职责：
✅ 消息列表展示
✅ 未读消息提醒
✅ 消息详情查看

优化：
- 虚拟滚动（支持大量消息）
- 实时更新（WebSocket / 轮询）

---

📊 实施计划

阶段 1：基础设施重构（Week 1）

Phase	模块	文件	预计行数	功能描述	优先级	预计时间
P1.1	数据管理器	data-manager.js	300	数据分层缓存 + 精细化刷新	🔴 P0	2h
P1.2	事件总线	event-bus.js	150	全局事件 + PostMessage 通信	🔴 P0	1h
P1.3	API 适配器	api-adapter.js	250	统一请求 + 降级处理	🔴 P0	1.5h
P1.4	组件管理器	component-manager.js	200	组件生命周期管理	🟠 P1	2h

阶段 1 产出:

• ✅ 4 个核心基础模块
• ✅ 约 900 行代码
• ✅ 单元测试（可选）
• ✅ API 文档

验收标准:

• ✅ 数据管理器能够独立刷新 6 个模块
• ✅ 事件总线支持跨 iframe 通信
• ✅ API 适配器自动降级和缓存
• ✅ 组件管理器支持延迟初始化

---

阶段 2：业务模块重写（Week 2）

Phase	模块	文件	预计行数	功能描述	优先级	预计时间
P2.1	地图图层管理器	map-layer.js	280	地图逻辑重写（简化 75%）	🔴 P0	3h
P2.2	Alert Panel V2	alert-panel-v2.js	350	告警面板重写	🟠 P1	2h
P2.3	Device Panel V2	device-panel-v2.js	320	设备面板重写	🟠 P1	2h
P2.4	Message Panel V2	message-panel-v2.js	200	消息面板重写	🟠 P1	1.5h
P2.5	Health Cards V2	health-cards.js	250	健康卡片重写	🟡 P2	1.5h
P2.6	Stats Panel V2	stats-panel.js	200	实时统计面板重写	🟡 P2	1h

阶段 2 产出:

• ✅ 6 个业务模块（全部重写）
• ✅ 约 1,600 行代码
• ✅ 集成测试

验收标准:

• ✅ 地图代码 < 300 行（当前 1400+ 行）
• ✅ 所有 Panel 支持按需初始化
• ✅ 所有 Panel 通过 EventBus 通信
• ✅ 告警/消息面板支持 3s/5s 刷新

---

阶段 3：main.html 重构（Week 3）

Phase	任务	描述	预计时间
P3.1	模块引入	在 main.html 中引入所有新模块	0.5h
P3.2	初始化重构	替换旧的 DOMContentLoaded 逻辑	1h
P3.3	数据刷新迁移	将 refreshData() 迁移到 DataManager	1.5h
P3.4	组件实例化	使用 ComponentManager 管理所有组件	2h
P3.5	事件绑定	将所有事件迁移到 EventBus	1.5h
P3.6	清理旧代码	删除已迁移的旧函数	1h

阶段 3 产出:

• ✅ main.html 从 6,871 行减少到 < 2,000 行
• ✅ 所有业务逻辑迁移到独立模块
• ✅ 保持功能完全一致

验收标准:

• ✅ 所有功能正常工作
• ✅ 无控制台错误
• ✅ 性能提升（首屏加载时间减少 30%）

---

阶段 4：后端 API 对接（Week 4）

Phase	API 端点	功能	优先级	预计时间
P4.1	/api/map/user-locations	获取用户实时位置 + 健康状态	🔴 P0	1h
P4.2	/api/alerts/pending	获取待处理告警	🔴 P0	0.5h
P4.3	/api/messages/unread	获取未读消息	🔴 P0	0.5h
P4.4	/api/devices/stats	获取设备统计	🟠 P1	0.5h
P4.5	/api/health/recent	获取最近健康数据	🟠 P1	0.5h

阶段 4 产出:

• ✅ 5 个新 API 端点
• ✅ API 文档
• ✅ 前端完全对接

验收标准:

• ✅ 所有 API 正常返回数据
• ✅ 降级逻辑测试通过
• ✅ 缓存机制生效

---

阶段 5：性能优化和测试（Week 5）

Phase	任务	描述	预计时间
P5.1	性能测试	测量首屏加载时间、数据刷新延迟	1h
P5.2	内存优化	检查内存泄漏、图表销毁	1h
P5.3	缓存优化	调优缓存策略、TTL 配置	0.5h
P5.4	功能测试	完整功能测试、边界测试	2h
P5.5	文档更新	更新技术文档、API 文档	1h

阶段 5 产出:

• ✅ 性能测试报告
• ✅ 功能测试报告
• ✅ 完整技术文档

验收标准:

• ✅ 首屏加载时间 < 2s
• ✅ 告警刷新延迟 < 3.5s
• ✅ 无内存泄漏
• ✅ 所有功能通过测试

---

📐 技术规范

代码风格

// ✅ 使用 ES6+ 语法
class DataManager {
  constructor(customerId) {
    this.customerId = customerId;
  }

  async fetchData() {
    // ...
  }
}

// ✅ 使用 async/await
async getData() {
  const data = await api.get('/endpoint');
  return data;
}

// ✅ 使用解构赋值
const { alerts, messages } = data;

// ✅ 使用箭头函数
const handler = (event) => {
  // ...
};

// ✅ 使用模板字符串
const url = `/api/alerts?customerId=${this.customerId}`;

命名规范

// ✅ 类名：PascalCase
class DataManager {}
class ApiAdapter {}

// ✅ 函数/方法：camelCase
function refreshData() {}
async updateComponent() {}

// ✅ 常量：UPPER_SNAKE_CASE
const REFRESH_INTERVAL = 3000;
const API_BASE_URL = '/api';

// ✅ 文件名：kebab-case
data-manager.js
event-bus.js
map-layer.js

模块导出规范

// ✅ 每个模块导出到 window 对象（兼容当前架构）
class DataManager {
  // ...
}

// 导出到全局
window.DataManager = DataManager;

// 模块加载标志
window.dataManagerModuleLoaded = true;
console.log('✅ data-manager.js 模块加载完成');

错误处理规范

// ✅ 统一错误处理
class ApiAdapter {
  async request(endpoint, options) {
    try {
      const response = await fetch(endpoint, options);

      if (!response.ok) {
        throw new ApiError(response.status, response.statusText);
      }

      return await response.json();
    } catch (error) {
      console.error(`❌ API 请求失败: ${endpoint}`, error);

      // 尝试降级
      return this.getFallbackData(endpoint);
    }
  }
}

// ✅ 自定义错误类
class ApiError extends Error {
  constructor(status, message) {
    super(message);
    this.name = 'ApiError';
    this.status = status;
  }
}

日志规范

// ✅ 使用统一的日志格式
console.log('✅ 成功:', message);
console.warn('⚠️ 警告:', message);
console.error('❌ 错误:', message);
console.debug('🔍 调试:', message);
console.info('📋 信息:', message);

// ✅ 数据日志
console.log('📊 数据获取:', data);
console.log('🔄 数据刷新:', module);
console.log('🎯 组件初始化:', componentName);

---

🗂️ 文件结构

新模块目录结构

ljwx-bigscreen/
├── app/
│   ├── static/
│   │   ├── js/
│   │   │   ├── modules/
│   │   │   │   ├── core/                      # 核心模块（新增）
│   │   │   │   │   ├── data-manager.js       # ✨ P1.1
│   │   │   │   │   ├── event-bus.js          # ✨ P1.2
│   │   │   │   │   ├── api-adapter.js        # ✨ P1.3
│   │   │   │   │   └── component-manager.js  # ✨ P1.4
│   │   │   │   │
│   │   │   │   ├── business/                  # 业务模块（新增）
│   │   │   │   │   ├── map-layer.js          # ✨ P2.1 (重写)
│   │   │   │   │   ├── alert-panel-v2.js     # ✨ P2.2 (重写)
│   │   │   │   │   ├── device-panel-v2.js    # ✨ P2.3 (重写)
│   │   │   │   │   ├── message-panel-v2.js   # ✨ P2.4 (重写)
│   │   │   │   │   ├── health-cards.js       # ✨ P2.5 (重写)
│   │   │   │   │   └── stats-panel.js        # ✨ P2.6 (重写)
│   │   │   │   │
│   │   │   │   ├── utils.js                   # ✅ 已完成 (Phase 4)
│   │   │   │   ├── api-client.js              # ✅ 已完成 (Phase 5)
│   │   │   │   ├── app-initializer.js         # ✅ 已完成 (Phase 7)
│   │   │   │   └── alert-panel.js             # ✅ 已完成 (Phase 8) - 将被 V2 替换
│   │   │   │
│   │   │   ├── libs/
│   │   │   │   └── echarts.min.js
│   │   │   │
│   │   │   └── map-optimizer.js
│   │   │
│   │   └── css/
│   │       └── main-complete.css              # ✅ 已完成 (Phase 3)
│   │
│   └── templates/
│       └── main.html                          # 🔄 待重构 (P3)
│
├── REFACTOR_PLAN_V2.md                        # 📘 本文档
├── OPTIMIZATION_LOG.md                        # 📝 旧优化日志
├── PHASE6_ANALYSIS.md                         # 📊 代码分析文档
└── README.md

---

📈 进度追踪

Phase 1: 基础设施重构

任务	状态	开始时间	完成时间	负责人	备注
P1.1: data-manager.js	✅ 已完成	2026-01-05 14:00	2026-01-05 14:30	Claude	核心模块，590行
P1.2: event-bus.js	✅ 已完成	2026-01-05 14:30	2026-01-05 14:50	Claude	事件总线，380行
P1.3: api-adapter.js	✅ 已完成	2026-01-05 14:50	2026-01-05 15:20	Claude	API适配器，580行
P1.4: component-manager.js	✅ 已完成	2026-01-05 15:20	2026-01-05 15:50	Claude	组件管理器，540行

Phase 2: 业务模块重写

任务	状态	开始时间	完成时间	负责人	备注
P2.1: map-layer.js	✅ 已完成	2026-01-06 13:40	2026-01-06 13:43	Claude	280行，简化75%
P2.2: alert-panel-v2.js	✅ 已完成	2026-01-06 13:43	2026-01-06 13:44	Claude	已存在
P2.3: device-panel-v2.js	✅ 已完成	2026-01-06 08:34	2026-01-06 13:44	Claude	已存在
P2.4: message-panel-v2.js	✅ 已完成	2026-01-06 08:33	2026-01-06 13:44	Claude	已存在
P2.5: health-cards.js	✅ 已完成	2026-01-06 08:34	2026-01-06 13:44	Claude	已存在
P2.6: stats-panel.js	✅ 已完成	2026-01-06 08:35	2026-01-06 13:44	Claude	已存在

Phase 3: main.html 重构

任务	状态	开始时间	完成时间	负责人	备注
P3.1: 模块引入	✅ 已完成	2026-01-06 13:45	2026-01-06 13:50	Claude	引入10个V2.0模块
P3.2: 初始化重构	✅ 已完成	2026-01-06 13:50	2026-01-06 14:00	Claude	创建initV2Architecture()
P3.3: 数据刷新迁移	⏸️ 暂缓	-	-	Claude	待Phase 4 API对接后实施
P3.4: 组件实例化	✅ 已完成	2026-01-06 14:00	2026-01-06 14:05	Claude	registerComponents()
P3.5: 事件绑定	⏸️ 暂缓	-	-	Claude	待Phase 4后逐步迁移
P3.6: 清理旧代码	⏸️ 暂缓	-	-	Claude	待新架构验证后清理

Phase 4: 后端 API 对接

任务	状态	开始时间	完成时间	负责人	备注
P4.1: /api/map/user-locations	✅ 已完成	2026-01-06 14:10	2026-01-06 14:15	Claude	使用现有API
P4.2: /api/alerts/pending	✅ 已完成	2026-01-06 14:10	2026-01-06 14:15	Claude	使用现有API
P4.3: /api/messages/unread	✅ 已完成	2026-01-06 14:10	2026-01-06 14:15	Claude	使用现有API
P4.4: /api/devices/stats	✅ 已完成	2026-01-06 14:10	2026-01-06 14:15	Claude	使用现有API
P4.5: /api/health/recent	✅ 已完成	2026-01-06 14:10	2026-01-06 14:15	Claude	使用现有API

说明: data-manager.js 已实现所有功能，使用现有 API (api.data.getTotal()) + 多层降级机制

Phase 5: 性能优化和测试

任务	状态	开始时间	完成时间	负责人	备注
P5.1: 性能测试	⏳ 待开始	-	-	QA	-
P5.2: 内存优化	⏳ 待开始	-	-	Claude	-
P5.3: 缓存优化	⏳ 待开始	-	-	Claude	-
P5.4: 功能测试	⏳ 待开始	-	-	QA	-
P5.5: 文档更新	⏳ 待开始	-	-	Claude	-

---

📊 预期成果

代码质量提升

指标	当前	目标	提升幅度
main.html 行数	6,871	< 2,000	-70%
地图模块行数	1,400+	< 300	-75%
模块总数	4	14	+250%
代码重复率	高	低	显著降低
可维护性评分	C	A	提升 2 级

性能提升

指标	当前	目标	提升幅度
首屏加载时间	~3s	< 2s	-33%
告警刷新延迟	60s	3s	-95%
消息刷新延迟	60s	5s	-92%
API 失败率	5%	< 1%	-80%
缓存命中率	0%	> 80%	+80%

用户体验提升

指标	当前	目标
告警实时性	差（60s 延迟）	优秀（3s 延迟）
消息实时性	差（60s 延迟）	优秀（5s 延迟）
地图流畅度	一般	流畅
错误提示	不友好	友好且准确
数据一致性	偶尔不一致	始终一致

---

🛠️ 开发工具和环境

开发环境

# Node.js 版本
node >= 16.0.0

# Python 版本（后端）
python >= 3.8

# Flask 版本
Flask == 2.0+

# 浏览器要求
Chrome >= 90
Firefox >= 88
Safari >= 14

调试工具

// 调试模式开关
window.DEBUG_MODE = true;

// 日志级别
window.LOG_LEVEL = 'debug'; // 'debug' | 'info' | 'warn' | 'error'

// 性能监控
window.PERFORMANCE_MONITOR = true;

性能测试工具

• Lighthouse (首屏加载时间)
• Chrome DevTools Performance (渲染性能)
• Network Monitor (API 请求延迟)

---

📚 参考文档

现有文档

• OPTIMIZATION_LOG.md - Phase 1-8 优化日志
• PHASE6_ANALYSIS.md - 代码结构分析
• CLAUDE.md - 项目文档

新增文档（待创建）

• API_DESIGN.md - 后端 API 设计文档
• COMPONENT_API.md - 前端组件 API 文档
• MIGRATION_GUIDE.md - 迁移指南
• PERFORMANCE_REPORT.md - 性能测试报告

---

⚠️ 风险和挑战

技术风险

风险	影响	可能性	缓解措施
新架构与旧代码兼容性问题	高	中	渐进式迁移，保持双轨运行
后端 API 开发延迟	中	中	使用 Mock 数据，前后端并行开发
性能优化效果不达预期	中	低	充分测试，及时调整策略
数据刷新频率过高导致性能问题	中	低	可配置刷新频率，动态调整

业务风险

风险	影响	可能性	缓解措施
用户习惯改变导致体验下降	高	低	保持 UI 一致，功能向下兼容
数据准确性问题	高	低	充分测试，数据校验
系统不稳定导致业务中断	高	低	灰度发布，回滚方案

---

🔄 回滚方案

快速回滚

# 方案 1: 回滚到 Phase 8 完成状态
cp main.html.phase8-backup main.html
rm -rf app/static/js/modules/core/
rm -rf app/static/js/modules/business/

# 方案 2: Git 回滚
git checkout main.html
git clean -fd app/static/js/modules/

灰度发布

// 使用特性开关（Feature Flag）
const USE_NEW_ARCHITECTURE = urlParams.get('v2') === 'true';

if (USE_NEW_ARCHITECTURE) {
  // 使用新架构
  const dataManager = new DataManager(GLOBAL_CUSTOMER_ID);
  dataManager.startAutoRefresh();
} else {
  // 使用旧架构
  refreshData();
  setInterval(refreshData, 60000);
}

---

📞 联系和支持

开发团队

• 前端开发: Claude AI
• 后端开发: Backend Team
• 项目负责人: Bruno Gao

问题反馈

• GitHub Issues: ljwx-health/issues
• 技术讨论: Slack #ljwx-bigscreen

---

📝 变更日志

[v2.0.0] - 2026-01-05

新增

• ✨ 数据管理器 (data-manager.js)
• ✨ 事件总线 (event-bus.js)
• ✨ API 适配器 (api-adapter.js)
• ✨ 组件管理器 (component-manager.js)
• ✨ 地图图层管理器 V2 (map-layer.js)
• ✨ Alert Panel V2 (alert-panel-v2.js)
• ✨ Device Panel V2 (device-panel-v2.js)
• ✨ Message Panel V2 (message-panel-v2.js)
• ✨ 健康卡片 V2 (health-cards.js)
• ✨ 实时统计面板 V2 (stats-panel.js)

改进

• 🚀 精细化数据刷新（3s/5s/30s/60s）
• 🚀 地图代码简化 75%
• 🚀 组件按需初始化
• 🚀 统一 API 适配层
• 🚀 事件驱动架构

修复

• 🐛 告警刷新延迟过高（60s → 3s）
• 🐛 消息刷新延迟过高（60s → 5s）
• 🐛 地图逻辑混乱
• 🐛 二级页面数据传递不优雅
• 🐛 API 失败率过高

---

文档版本: v2.0.0 最后更新: 2026-01-05 下一步: 开始 P1.1 - 创建 data-manager.js

---

END OF DOCUMENT