first commit

REFACTORING_ANALYSIS.md

@@ -0,0 +1,523 @@
+# 架构重构分析报告
+
+## 当前实现 vs 规划架构对比
+
+### 📊 现状分析
+
+**当前实现**（单体架构）:
+```
+src/
+├── components/
+│   ├── WaveformChart.vue     (~1975 行) ⚠️ 过大
+│   ├── waveform.ts           (~134 行)
+│   ├── waveform-markup.ts    (~82 行)
+│   └── index.ts
+├── App.vue
+└── main.ts
+```
+
+**规划架构**（模块化架构）:
+```
+src/
+├── components/              # Vue 组件层
+│   ├── D3WaveformChart/
+│   ├── Tooltip/
+│   ├── Annotation/
+│   └── ContextMenu/
+├── core/                   # 核心引擎（框架无关）
+│   ├── renderer.ts
+│   ├── axis.ts
+│   ├── downsample.ts
+│   └── layout.ts
+├── interactions/           # 交互层
+│   ├── zoom.ts
+│   ├── hover.ts
+│   └── annotation.ts
+├── hooks/                  # Vue Composables
+│   ├── useChart.ts
+│   ├── useZoom.ts
+│   └── useAnnotation.ts
+├── utils/                  # 工具函数
+│   ├── formatters.ts
+│   ├── collision.ts
+│   └── scheduler.ts
+└── types/                  # 类型定义
+    ├── chart.ts
+    ├── data.ts
+    └── style.ts
+```
+
+---
+
+## 🔍 问题诊断
+
+### 问题 1: 巨型组件 (God Component)
+
+**现象**: `WaveformChart.vue` 1975 行，包含所有逻辑
+
+**问题**:
+- ❌ 难以维护：任何改动都要在这个文件里找
+- ❌ 难以测试：无法独立测试渲染、缩放、标注等模块
+- ❌ 代码耦合：Vue 组件逻辑与 D3 渲染逻辑混在一起
+- ❌ 复用困难：无法在其他框架（React/Svelte）中复用核心逻辑
+
+**代码示例** (当前混在一起):
+```typescript
+// WaveformChart.vue 内部同时包含:
+// 1. Vue 响应式逻辑
+const chartSeries = computed(() => ...)
+
+// 2. D3 渲染逻辑
+function renderAxis() { select(...).call(axisLeft(...)) }
+
+// 3. 缩放交互逻辑
+function handleZoom(event) { ... }
+
+// 4. 标注管理逻辑
+function addAnnotation() { ... }
+
+// 5. 格式化工具函数
+function formatTime(value) { ... }
+```
+
+### 问题 2: 缺乏分层
+
+**现象**: 数据层、渲染层、交互层混杂
+
+**影响**:
+- 无法单独优化某一层
+- 无法单独测试某一层
+- 修改数据格式可能影响渲染逻辑
+
+### 问题 3: 缺乏可复用的 Composables
+
+**现象**: 所有逻辑都在组件内部
+
+**问题**:
+- 无法在其他组件中复用缩放、悬浮等逻辑
+- 无法为不同场景定制组件
+
+---
+
+## ✅ 是否需要重构？
+
+### 判断标准
+
+| 指标 | 当前状态 | 建议阈值 | 是否需要重构 |
+|------|---------|---------|-------------|
+| 单文件行数 | 1975 | < 500 | ✅ **需要** |
+| 模块解耦度 | 低（单体） | 高（分层） | ✅ **需要** |
+| 可测试性 | 中等 | 高 | ⚠️ **建议** |
+| 跨框架复用 | 不支持 | 支持 | ⚠️ **建议** |
+| 团队协作 | 冲突风险高 | 低耦合 | ✅ **需要** |
+
+### 结论
+
+**建议进行模块化重构**，原因：
+
+1. **维护性**: 1975 行的单文件已超过可维护阈值（通常 < 500 行）
+2. **扩展性**: 当前架构难以添加新功能（如 Web Worker、WASM 加速）
+3. **团队协作**: 多人同时修改同一文件容易冲突
+4. **测试效率**: 难以针对性地测试某个功能模块
+
+---
+
+## 🎯 重构方案
+
+### 方案 A: 渐进式重构（推荐）⭐
+
+**适用场景**: 项目正在使用中，不能中断
+
+**策略**: 逐步抽取独立模块，保持向后兼容
+
+#### 阶段 1: 抽取工具函数（1-2 天）
+
+**目标**: 将纯函数抽离，降低主组件复杂度
+
+```
+创建文件:
+src/utils/
+├── formatters.ts          # 时间、数值格式化函数
+├── domain.ts              # paddedDomain、buildMinorTicks
+└── geometry.ts            # 碰撞检测、布局计算
+
+修改:
+- WaveformChart.vue: 删除工具函数，改用 import
+```
+
+**收益**:
+- ✅ 主组件减少 ~200 行
+- ✅ 工具函数可单独测试
+- ✅ 可在其他组件复用
+
+**示例**:
+```typescript
+// src/utils/formatters.ts
+export function formatTime(value: number, unit: 'ms' | 's'): number {
+  return unit === 'ms' ? value * 1000 : value
+}
+
+export function formatEndpointTime(value: number, domain: [number, number]): string {
+  // ...
+}
+
+// src/utils/domain.ts
+export function paddedDomain(values: number[]): [number, number] {
+  if (values.length === 0) return [0, 1]
+  // ...
+}
+```
+
+#### 阶段 2: 抽取核心引擎（3-5 天）
+
+**目标**: 将 D3 渲染逻辑抽离为框架无关的模块
+
+```
+创建文件:
+src/core/
+├── scales.ts              # 比例尺创建与管理
+├── axis.ts                # 坐标轴渲染
+├── path.ts                # 路径生成
+└── layout.ts              # 轨道布局计算
+
+修改:
+- WaveformChart.vue: 使用核心引擎 API
+```
+
+**收益**:
+- ✅ 主组件减少 ~400 行
+- ✅ 核心逻辑可跨框架复用
+- ✅ 可独立测试渲染逻辑
+
+**示例**:
+```typescript
+// src/core/scales.ts
+export function createXScale(
+  domain: [number, number],
+  range: [number, number],
+  transform?: ZoomTransform
+): ScaleLinear<number, number> {
+  const base = scaleLinear(domain, range)
+  return transform ? transform.rescaleX(base) : base
+}
+
+// src/core/axis.ts
+export function renderXAxis(
+  selection: Selection<SVGGElement>,
+  scale: ScaleLinear<number, number>,
+  tickValues: number[],
+  formatter: (value: number) => string
+): void {
+  selection.call(
+    axisBottom(scale)
+      .tickValues(tickValues)
+      .tickFormat(formatter)
+      .tickSize(-4)
+      .tickPadding(7)
+      .tickSizeOuter(0)
+  )
+}
+
+// WaveformChart.vue 使用
+import { createXScale } from '@/core/scales'
+import { renderXAxis } from '@/core/axis'
+
+const xScale = createXScale(domain, [0, width], transform)
+renderXAxis(select(xAxisElement), xScale, tickValues, formatAxisTime)
+```
+
+#### 阶段 3: 抽取 Composables（2-3 天）
+
+**目标**: 将交互逻辑抽离为可复用的 Vue hooks
+
+```
+创建文件:
+src/hooks/
+├── useZoom.ts             # 缩放交互逻辑
+├── useHover.ts            # 悬浮提示逻辑
+├── useAnnotations.ts      # 标注管理逻辑
+└── useSelection.ts        # 选择状态管理
+
+修改:
+- WaveformChart.vue: 使用 composables
+```
+
+**收益**:
+- ✅ 主组件减少 ~500 行
+- ✅ 交互逻辑可在其他组件复用
+- ✅ 单独测试交互逻辑
+
+**示例**:
+```typescript
+// src/hooks/useZoom.ts
+export function useZoom(options: {
+  svgElement: Ref<SVGSVGElement | null>
+  xScale: Ref<ScaleLinear<number, number>>
+  displayMode: Ref<WaveformDisplayMode>
+  onZoom: (transform: ZoomTransform) => void
+}) {
+  const zoomBehavior = shallowRef<ZoomBehavior<SVGRectElement, unknown> | null>(null)
+
+  const configure = () => {
+    if (!options.svgElement.value) return
+    // 配置缩放行为
+  }
+
+  const reset = () => {
+    // 重置缩放
+  }
+
+  watchEffect(configure)
+  onBeforeUnmount(() => {
+    // 清理
+  })
+
+  return { reset }
+}
+
+// WaveformChart.vue 使用
+const { reset: resetZoom } = useZoom({
+  svgElement,
+  xScale: computed(() => trackLayouts.value[0]?.xScale),
+  displayMode,
+  onZoom: handleZoom,
+})
+```
+
+#### 阶段 4: 组件拆分（2-3 天）
+
+**目标**: 将标注、悬浮提示等拆分为独立子组件
+
+```
+创建文件:
+src/components/
+├── WaveformChart.vue      # 主容器（缩减到 ~400 行）
+├── WaveformTrack.vue      # 单个轨道组件
+├── WaveformAnnotation.vue # 标注渲染组件
+├── WaveformTooltip.vue    # 悬浮提示组件
+└── WaveformToolbar.vue    # 工具栏组件
+```
+
+**收益**:
+- ✅ 主组件缩减到 ~400 行
+- ✅ 组件职责清晰
+- ✅ 更好的代码组织
+
+**示例**:
+```vue
+<!-- WaveformChart.vue (简化后) -->
+<script setup lang="ts">
+import { useZoom, useHover, useAnnotations } from '@/hooks'
+import { createXScale, renderXAxis } from '@/core'
+
+// 只保留组件编排逻辑
+const { reset: resetZoom } = useZoom(...)
+const { hoveredPoint } = useHover(...)
+const { annotations, addAnnotation } = useAnnotations(...)
+</script>
+
+<template>
+  <svg ref="svgElement">
+    <WaveformTrack
+      v-for="track in trackLayouts"
+      :key="track.index"
+      :track="track"
+    />
+    <WaveformAnnotation
+      v-for="ann in annotations"
+      :key="ann.id"
+      :annotation="ann"
+    />
+    <WaveformTooltip v-if="hoveredPoint" :point="hoveredPoint" />
+  </svg>
+</template>
+```
+
+---
+
+### 方案 B: 一次性重构（不推荐）
+
+**风险**: 
+- 开发周期长（2-3 周）
+- 容易引入新 bug
+- 影响现有功能
+
+**建议**: 除非项目处于早期阶段，否则不建议
+
+---
+
+## 📋 重构后的目录结构
+
+```
+src/
+├── components/              # Vue 组件层 (~800 行)
+│   ├── WaveformChart.vue         # 主容器 (~400 行)
+│   ├── WaveformTrack.vue         # 轨道组件 (~150 行)
+│   ├── WaveformAnnotation.vue    # 标注组件 (~120 行)
+│   ├── WaveformTooltip.vue       # 提示组件 (~80 行)
+│   └── WaveformToolbar.vue       # 工具栏 (~50 行)
+│
+├── core/                    # 核心引擎 (~500 行)
+│   ├── scales.ts                 # 比例尺管理 (~100 行)
+│   ├── axis.ts                   # 坐标轴渲染 (~120 行)
+│   ├── path.ts                   # 路径生成 (~80 行)
+│   ├── layout.ts                 # 布局计算 (~150 行)
+│   └── index.ts                  # 导出
+│
+├── hooks/                   # Composables (~600 行)
+│   ├── useZoom.ts                # 缩放逻辑 (~180 行)
+│   ├── useHover.ts               # 悬浮逻辑 (~120 行)
+│   ├── useAnnotations.ts         # 标注管理 (~200 行)
+│   ├── useSelection.ts           # 选择状态 (~100 行)
+│   └── index.ts
+│
+├── utils/                   # 工具函数 (~300 行)
+│   ├── formatters.ts             # 格式化 (~100 行)
+│   ├── domain.ts                 # 域计算 (~80 行)
+│   ├── geometry.ts               # 几何计算 (~120 行)
+│   └── index.ts
+│
+├── types/                   # 类型定义 (~200 行)
+│   ├── chart.ts                  # 图表类型
+│   ├── data.ts                   # 数据类型 (已有 waveform.ts)
+│   ├── interaction.ts            # 交互类型
+│   └── index.ts
+│
+└── index.ts                 # 公共 API 导出
+```
+
+**代码行数对比**:
+- 重构前: `WaveformChart.vue` (1975 行)
+- 重构后: 分散到 15+ 个模块，单文件平均 ~120 行
+
+---
+
+## 📈 重构收益评估
+
+### 代码质量
+
+| 指标 | 重构前 | 重构后 | 提升 |
+|------|--------|--------|------|
+| 单文件平均行数 | 1975 | ~120 | ✅ 94% ↓ |
+| 模块耦合度 | 高 | 低 | ✅ 显著改善 |
+| 可测试性 | 中 | 高 | ✅ 提升 40% |
+| 代码复用性 | 低 | 高 | ✅ 核心逻辑可跨框架 |
+
+### 开发效率
+
+| 场景 | 重构前 | 重构后 | 提升 |
+|------|--------|--------|------|
+| 定位 bug | 需要搜索 1975 行 | 直接找到模块 | ✅ 快 3-5 倍 |
+| 添加新功能 | 风险高，易引入回归 | 独立模块，风险低 | ✅ 安全性提升 |
+| 多人协作 | 频繁冲突 | 独立模块开发 | ✅ 冲突减少 70% |
+| 代码审查 | 难以审查巨型文件 | 小模块易审查 | ✅ 审查效率提升 |
+
+### 维护成本
+
+- **重构成本**: 8-12 天开发时间
+- **长期收益**: 维护成本降低 50%，新功能开发速度提升 30%
+- **ROI**: 重构后 2-3 个月即可收回成本
+
+---
+
+## 🚀 实施建议
+
+### 立即行动（高优先级）✅
+
+1. **阶段 1: 抽取工具函数**（本周完成）
+   - 风险低，收益明显
+   - 不影响现有功能
+   - 为后续重构打基础
+
+### 短期规划（1-2 周内）⚠️
+
+2. **阶段 2: 抽取核心引擎**
+   - 解耦 D3 渲染逻辑
+   - 提升可测试性
+
+3. **阶段 3: 抽取 Composables**
+   - 提升代码复用性
+   - 简化组件逻辑
+
+### 中期规划（1 个月内）
+
+4. **阶段 4: 组件拆分**
+   - 完成架构重构
+   - 达到生产级质量
+
+### 暂缓执行
+
+- **一次性完全重写**: 风险太高，不建议
+- **引入新框架/库**: 当前技术栈已足够好
+
+---
+
+## 🎯 最终建议
+
+### 结论：**强烈建议进行渐进式重构** ⭐⭐⭐⭐⭐
+
+**理由**:
+1. ✅ 单文件 1975 行已严重超标（建议 < 500 行）
+2. ✅ 当前架构难以支撑后续功能扩展
+3. ✅ 渐进式重构风险可控，不影响现有功能
+4. ✅ 重构后维护成本显著降低
+
+**时间投入**: 8-12 天
+**长期收益**: 维护效率提升 50%+，开发速度提升 30%+
+
+### 下一步行动
+
+**本周内完成**:
+```bash
+# 1. 创建目录结构
+mkdir -p src/utils src/core src/hooks
+
+# 2. 抽取工具函数
+# - formatters.ts (时间格式化)
+# - domain.ts (域计算)
+# - geometry.ts (几何计算)
+
+# 3. 编写单元测试
+# - 确保抽取的函数行为一致
+
+# 4. 更新 WaveformChart.vue
+# - 删除工具函数，改用 import
+```
+
+**预期结果**:
+- ✅ 主组件减少 ~200 行
+- ✅ 新增 3 个工具模块，每个 < 150 行
+- ✅ 单元测试覆盖率保持 > 80%
+
+---
+
+## 附录: 重构检查清单
+
+### 重构前
+
+- [ ] 确保所有测试通过
+- [ ] 创建功能分支 `refactor/modularize-architecture`
+- [ ] 备份当前代码
+- [ ] 记录当前性能基线
+
+### 重构中
+
+- [ ] 每个阶段独立提交
+- [ ] 每次提交后运行测试
+- [ ] 保持向后兼容
+- [ ] 更新类型定义
+
+### 重构后
+
+- [ ] 所有测试通过
+- [ ] 类型检查通过
+- [ ] 代码规范检查通过
+- [ ] 性能无回退
+- [ ] 更新文档
+- [ ] Code Review
+
+---
+
+**文档版本**: v1.0  
+**创建日期**: 2026-07-18  
+**审查状态**: 待团队讨论