feat(ci): publish tagged releases to npmjs

.claude/plan-system-refactoring.md

@@ -1,663 +0,0 @@
-# WaveformChart 按系统拆分重构计划
-
-## 🎯 目标
-
-将现有的组件按功能系统重新组织，每个系统有独立的目录，提高代码的可维护性和可理解性。
-
-## 📊 当前结构分析
-
-### 当前组件列表
-
-```
-src/components/
-├── WaveformChart.vue              # 主容器组件 (~1143 行)
-├── WaveformToolbar.vue            # 工具栏 (174 行)
-├── WaveformEditor.vue             # 编辑器 (149 行)
-├── WaveformTooltip.vue            # 悬浮提示 (111 行)
-├── WaveformTrack.vue              # 波形轨道 (317 行)
-├── WaveformAnnotationLayer.vue    # 标注层 (281 行)
-├── waveform.ts                    # 类型定义
-├── waveform-markup.ts             # 标注相关类型和工具
-└── index.ts                       # 导出
-```
-
-### 功能系统识别
-
-通过分析代码，可以识别出以下核心系统：
-
-1. **基础绘制系统 (Rendering System)**
-   - 波形轨道渲染（网格、坐标轴、波形线）
-   - SVG 基础图形绘制
-   - D3 图表渲染
-
-2. **缩放系统 (Zoom System)**
-   - 缩放行为管理
-   - 变换状态管理
-   - 独立/共享缩放模式
-
-3. **交互系统 (Interaction System)**
-   - 鼠标事件处理
-   - 悬浮检测
-   - 十字线显示
-   - 工具栏和模式切换
-
-4. **标注系统 (Annotation System)**
-   - 标注管理（创建、编辑、删除）
-   - 图形管理（垂直线、时间区间）
-   - 标注渲染
-   - 编辑器
-
-5. **数据系统 (Data System)**
-   - 数据规范化
-   - 类型定义
-   - 轨道布局计算
-
-## 🏗️ 目标目录结构
-
-```
-src/components/
-├── WaveformChart.vue                    # 主容器（协调各系统）
-├── index.ts                             # 公共导出
-│
-├── core/                                # 核心系统
-│   ├── types.ts                         # 共享类型定义
-│   ├── constants.ts                     # 常量（颜色、尺寸等）
-│   └── index.ts
-│
-├── data/                                # 数据系统
-│   ├── types.ts                         # 数据相关类型
-│   ├── normalize.ts                     # 数据规范化
-│   ├── layout.ts                        # 轨道布局计算
-│   └── index.ts
-│
-├── rendering/                           # 基础绘制系统
-│   ├── WaveformTrack.vue               # 波形轨道组件
-│   ├── Grid.vue                        # 网格组件（可选）
-│   ├── Axis.vue                        # 坐标轴组件（可选）
-│   ├── types.ts                        # 渲染相关类型
-│   └── index.ts
-│
-├── zoom/                                # 缩放系统
-│   ├── useZoom.ts                       # 缩放组合式函数
-│   ├── types.ts                         # 缩放相关类型
-│   └── index.ts
-│
-├── interaction/                         # 交互系统
-│   ├── WaveformToolbar.vue             # 工具栏
-│   ├── WaveformTooltip.vue             # 悬浮提示
-│   ├── useInteraction.ts               # 交互组合式函数
-│   ├── useHover.ts                     # 悬浮逻辑
-│   ├── types.ts                        # 交互相关类型
-│   └── index.ts
-│
-└── annotation/                          # 标注系统
-    ├── WaveformAnnotationLayer.vue     # 标注渲染层
-    ├── WaveformEditor.vue              # 标注编辑器
-    ├── useAnnotation.ts                # 标注管理逻辑
-    ├── markup.ts                       # 标注工具函数
-    ├── types.ts                        # 标注相关类型
-    └── index.ts
-```
-
-## 📦 系统划分详情
-
-### 1. Core System (核心系统)
-
-**职责**：提供共享的类型、常量和工具
-
-**文件**：
-
-- `core/types.ts` - 基础类型定义
-
-  ```typescript
-  export interface DisplaySeries { ... }
-  export interface TrackLayout { ... }
-  export interface WaveformPoint { ... }
-  ```
-
-- `core/constants.ts` - 常量
-  ```typescript
-  export const channelColors = [...]
-  export const margin = { top: 18, right: 24, bottom: 52, left: 64 }
-  export const minimumHeight = 180
-  ```
-
-**来源**：从 `WaveformChart.vue` 和 `waveform.ts` 提取
-
----
-
-### 2. Data System (数据系统)
-
-**职责**：数据规范化、轨道布局计算
-
-**文件**：
-
-- `data/types.ts` - 数据类型
-
-  ```typescript
-  export type WaveformData = ...
-  export type WaveformDisplayMode = ...
-  export interface WaveformSeries { ... }
-  ```
-
-- `data/normalize.ts` - 数据规范化
-
-  ```typescript
-  export function normalizeWaveformData(data: WaveformData): WaveformSeries[]
-  export function normalizeWaveformSeries(data: WaveformData): DisplaySeries[]
-  ```
-
-- `data/layout.ts` - 轨道布局计算
-  ```typescript
-  export function computeTrackLayouts(
-    series: DisplaySeries[],
-    displayMode: WaveformDisplayMode,
-    innerWidth: number,
-    innerHeight: number,
-    ...
-  ): TrackLayout[]
-  ```
-
-**来源**：
-
-- `waveform.ts` → `data/types.ts` + `data/normalize.ts`
-- `WaveformChart.vue` 中的 `trackLayouts` 计算逻辑 → `data/layout.ts`
-
----
-
-### 3. Rendering System (基础绘制系统)
-
-**职责**：渲染波形轨道、网格、坐标轴、波形线
-
-**文件**：
-
-- `rendering/WaveformTrack.vue` - 波形轨道组件（已存在）
-- `rendering/types.ts` - 渲染相关类型
-  ```typescript
-  export interface RenderingProps { ... }
-  export interface AxisConfig { ... }
-  ```
-
-**可选优化**：
-
-- `rendering/Grid.vue` - 独立网格组件
-- `rendering/Axis.vue` - 独立坐标轴组件
-
-**来源**：
-
-- `WaveformTrack.vue` → `rendering/WaveformTrack.vue`
-
----
-
-### 4. Zoom System (缩放系统)
-
-**职责**：管理缩放行为、变换状态
-
-**文件**：
-
-- `zoom/useZoom.ts` - 缩放组合式函数
-
-  ```typescript
-  export function useZoom(options: ZoomOptions) {
-    const sharedTransform = shallowRef<ZoomTransform>(zoomIdentity)
-    const independentTransforms = shallowRef<ZoomTransform[]>([])
-
-    function configureZoom() { ... }
-    function resetViewport() { ... }
-    function handleSharedZoom(event: D3ZoomEvent) { ... }
-    function handleIndependentZoom(event: D3ZoomEvent, trackIndex: number) { ... }
-
-    return {
-      sharedTransform,
-      independentTransforms,
-      configureZoom,
-      resetViewport,
-      handleSharedZoom,
-      handleIndependentZoom,
-    }
-  }
-  ```
-
-- `zoom/types.ts` - 缩放相关类型
-  ```typescript
-  export interface ZoomOptions { ... }
-  export interface ZoomState { ... }
-  ```
-
-**来源**：从 `WaveformChart.vue` 提取缩放相关逻辑
-
----
-
-### 5. Interaction System (交互系统)
-
-**职责**：处理用户交互（悬浮、点击、工具栏）
-
-**文件**：
-
-- `interaction/WaveformToolbar.vue` - 工具栏（已存在）
-- `interaction/WaveformTooltip.vue` - 悬浮提示（已存在）
-
-- `interaction/useInteraction.ts` - 交互管理
-
-  ```typescript
-  export function useInteraction(options: InteractionOptions) {
-    const interactionMode = ref<WaveformInteractionMode>('zoom')
-
-    function setInteractionMode(mode: WaveformInteractionMode) { ... }
-    function handleOverlayClick(event: PointerEvent, trackIndex?: number) { ... }
-
-    return {
-      interactionMode,
-      setInteractionMode,
-      handleOverlayClick,
-    }
-  }
-  ```
-
-- `interaction/useHover.ts` - 悬浮逻辑
-
-  ```typescript
-  export function useHover(options: HoverOptions) {
-    const hoveredSeriesPoints = ref<HoveredSeriesPoint[]>([])
-    const hoveredTrackIndex = ref<number | null>(null)
-    const hoverPosition = ref({ x: 0, y: 0 })
-
-    function handlePointerMove(event: PointerEvent, trackIndex?: number) { ... }
-    function clearHover() { ... }
-    function nearestPoint(series: DisplaySeries, xValue: number) { ... }
-
-    return {
-      hoveredSeriesPoints,
-      hoveredTrackIndex,
-      hoverPosition,
-      handlePointerMove,
-      clearHover,
-      nearestPoint,
-    }
-  }
-  ```
-
-- `interaction/types.ts` - 交互相关类型
-  ```typescript
-  export type WaveformInteractionMode = 'zoom' | 'select' | 'annotation' | ...
-  export interface InteractionOptions { ... }
-  export interface HoverOptions { ... }
-  ```
-
-**来源**：
-
-- `WaveformToolbar.vue` → `interaction/WaveformToolbar.vue`
-- `WaveformTooltip.vue` → `interaction/WaveformTooltip.vue`
-- `WaveformChart.vue` 中的交互逻辑 → `interaction/useInteraction.ts` + `interaction/useHover.ts`
-
----
-
-### 6. Annotation System (标注系统)
-
-**职责**：管理标注和图形（创建、编辑、删除、渲染）
-
-**文件**：
-
-- `annotation/WaveformAnnotationLayer.vue` - 标注渲染层（已存在）
-- `annotation/WaveformEditor.vue` - 标注编辑器（已存在）
-
-- `annotation/useAnnotation.ts` - 标注管理逻辑
-
-  ```typescript
-  export function useAnnotation(options: AnnotationOptions) {
-    const selection = ref<WaveformMarkupSelection>(null)
-    const editingDraft = ref<EditingDraft | null>(null)
-    const rangeDraft = ref<RangeDraft | null>(null)
-
-    function createAnnotation(point: WaveformPoint, seriesId: string) { ... }
-    function editAnnotation(id: string) { ... }
-    function deleteAnnotation(id: string) { ... }
-    function selectMarkup(kind: 'annotation' | 'shape', id: string) { ... }
-
-    return {
-      selection,
-      editingDraft,
-      rangeDraft,
-      createAnnotation,
-      editAnnotation,
-      deleteAnnotation,
-      selectMarkup,
-    }
-  }
-  ```
-
-- `annotation/markup.ts` - 标注工具函数
-
-  ```typescript
-  export function layoutAnnotationBox(...) { ... }
-  export function resolveAnnotationStyle(...) { ... }
-  export function resolveShapeStyle(...) { ... }
-  export function normalizeRangeShape(...) { ... }
-  ```
-
-- `annotation/types.ts` - 标注相关类型
-  ```typescript
-  export interface WaveformAnnotation { ... }
-  export interface WaveformShape { ... }
-  export interface RenderedAnnotation { ... }
-  export interface RenderedShape { ... }
-  ```
-
-**来源**：
-
-- `WaveformAnnotationLayer.vue` → `annotation/WaveformAnnotationLayer.vue`
-- `WaveformEditor.vue` → `annotation/WaveformEditor.vue`
-- `waveform-markup.ts` → `annotation/markup.ts` + `annotation/types.ts`
-- `WaveformChart.vue` 中的标注管理逻辑 → `annotation/useAnnotation.ts`
-
----
-
-## 🔄 重构策略
-
-### 阶段 1: 创建新目录结构（不破坏现有代码）
-
-1. 创建新的目录结构
-2. 复制现有文件到新位置
-3. 不修改任何逻辑
-
-### 阶段 2: 提取共享类型和常量
-
-1. 创建 `core/types.ts` 和 `core/constants.ts`
-2. 从各个文件中提取共享类型
-3. 更新导入路径
-
-### 阶段 3: 重构数据系统
-
-1. 创建 `data/` 目录
-2. 将 `waveform.ts` 拆分为 `data/types.ts` 和 `data/normalize.ts`
-3. 从 `WaveformChart.vue` 提取布局计算逻辑到 `data/layout.ts`
-
-### 阶段 4: 重构缩放系统
-
-1. 创建 `zoom/useZoom.ts`
-2. 从 `WaveformChart.vue` 提取缩放相关逻辑
-3. 在主组件中使用组合式函数
-
-### 阶段 5: 重构交互系统
-
-1. 移动 `WaveformToolbar.vue` 和 `WaveformTooltip.vue` 到 `interaction/`
-2. 创建 `interaction/useInteraction.ts` 和 `interaction/useHover.ts`
-3. 从 `WaveformChart.vue` 提取交互逻辑
-
-### 阶段 6: 重构标注系统
-
-1. 移动 `WaveformAnnotationLayer.vue` 和 `WaveformEditor.vue` 到 `annotation/`
-2. 将 `waveform-markup.ts` 拆分为 `annotation/markup.ts` 和 `annotation/types.ts`
-3. 创建 `annotation/useAnnotation.ts`
-4. 从 `WaveformChart.vue` 提取标注管理逻辑
-
-### 阶段 7: 重构渲染系统
-
-1. 移动 `WaveformTrack.vue` 到 `rendering/`
-2. 更新所有导入路径
-
-### 阶段 8: 更新主组件和公共导出
-
-1. 简化 `WaveformChart.vue`，使用各系统的组合式函数
-2. 更新 `components/index.ts` 导出
-3. 确保向后兼容
-
-### 阶段 9: 测试和验证
-
-1. 运行所有测试
-2. 验证功能完整性
-3. 检查性能
-
----
-
-## 📝 重构后的主组件结构
-
-```vue
-<script setup lang="ts">
-import { computed, ref, watch } from 'vue'
-
-// 数据系统
-import { normalizeWaveformSeries, computeTrackLayouts } from './data'
-import type { WaveformData, DisplayMode } from './data/types'
-
-// 缩放系统
-import { useZoom } from './zoom'
-
-// 交互系统
-import { useInteraction, useHover } from './interaction'
-import WaveformToolbar from './interaction/WaveformToolbar.vue'
-import WaveformTooltip from './interaction/WaveformTooltip.vue'
-
-// 标注系统
-import { useAnnotation } from './annotation'
-import WaveformAnnotationLayer from './annotation/WaveformAnnotationLayer.vue'
-import WaveformEditor from './annotation/WaveformEditor.vue'
-
-// 渲染系统
-import WaveformTrack from './rendering/WaveformTrack.vue'
-
-// 核心
-import { channelColors, margin } from './core/constants'
-
-const props = defineProps<{
-  data: WaveformData
-  displayMode?: DisplayMode
-  // ...
-}>()
-
-// 数据处理
-const chartSeries = computed(() => normalizeWaveformSeries(props.data))
-const trackLayouts = computed(() => computeTrackLayouts(chartSeries.value, ...))
-
-// 缩放系统
-const {
-  sharedTransform,
-  independentTransforms,
-  configureZoom,
-  resetViewport,
-} = useZoom({ /* options */ })
-
-// 交互系统
-const { interactionMode, setInteractionMode } = useInteraction({ /* options */ })
-const { hoveredSeriesPoints, handlePointerMove, clearHover } = useHover({ /* options */ })
-
-// 标注系统
-const {
-  selection,
-  editingDraft,
-  createAnnotation,
-  editAnnotation,
-  deleteAnnotation,
-} = useAnnotation({ /* options */ })
-
-// 生命周期和监听
-watch(() => props.data, resetViewport)
-</script>
-
-<template>
-  <div class="waveform-chart">
-    <svg>
-      <!-- 轨道渲染 -->
-      <WaveformTrack
-        v-for="track in trackLayouts"
-        :key="track.index"
-        :track="track"
-        @pointer-move="handlePointerMove($event, track.index)"
-      />
-
-      <!-- 标注层 -->
-      <WaveformAnnotationLayer :annotations="renderedAnnotations" :shapes="renderedShapes" />
-    </svg>
-
-    <!-- 工具栏 -->
-    <WaveformToolbar
-      :interaction-mode="interactionMode"
-      @update:interaction-mode="setInteractionMode"
-    />
-
-    <!-- 编辑器 -->
-    <WaveformEditor v-if="editingDraft" :draft="editingDraft" />
-
-    <!-- Tooltip -->
-    <WaveformTooltip
-      :visible="hoveredSeriesPoints.length > 0"
-      :series-points="hoveredSeriesPoints"
-    />
-  </div>
-</template>
-```
-
----
-
-## ✅ 收益
-
-### 1. 可维护性 ⭐⭐⭐⭐⭐
-
-- **按功能定位**：需要修改缩放功能？直接到 `zoom/` 目录
-- **职责清晰**：每个系统有独立的目录和文件
-- **减少耦合**：系统之间通过明确的接口通信
-
-### 2. 可测试性 ⭐⭐⭐⭐⭐
-
-- **独立测试**：每个系统可以独立测试
-- **组合式函数**：易于单元测试，不需要挂载组件
-
-```typescript
-// 测试缩放系统
-describe('useZoom', () => {
-  it('should handle zoom transform', () => {
-    const { sharedTransform, handleSharedZoom } = useZoom(options)
-    // 测试逻辑
-  })
-})
-```
-
-### 3. 可扩展性 ⭐⭐⭐⭐⭐
-
-- **添加新功能**：在对应系统目录下添加
-- **替换实现**：可以替换整个系统而不影响其他部分
-- **插件化**：各系统可以作为独立插件使用
-
-### 4. 可理解性 ⭐⭐⭐⭐⭐
-
-- **目录即文档**：从目录结构就能理解系统功能
-- **代码组织**：相关代码放在一起，容易理解上下文
-- **新人友好**：新开发者可以快速定位到相关代码
-
----
-
-## ⚠️ 风险和注意事项
-
-### 1. 大规模重构风险
-
-**风险**：移动文件可能导致测试失败、功能损坏
-
-**缓解措施**：
-
-- 分阶段重构，每个阶段运行测试
-- 保持向后兼容
-- 使用 Git 分支，可以随时回滚
-
-### 2. 导入路径变更
-
-**风险**：大量文件的导入路径需要更新
-
-**缓解措施**：
-
-- 使用 IDE 的重构功能
-- 在新目录的 `index.ts` 中保持导出一致
-- 逐步迁移，保留旧路径的重导出
-
-### 3. 类型依赖复杂
-
-**风险**：类型定义分散后可能产生循环依赖
-
-**缓解措施**：
-
-- 明确类型依赖关系
-- 共享类型放在 `core/types.ts`
-- 避免系统之间直接依赖类型
-
-### 4. 性能影响
-
-**风险**：拆分可能影响打包体积和加载性能
-
-**缓解措施**：
-
-- 使用 Tree-shaking 优化
-- 合理使用动态导入
-- 监控打包体积变化
-
----
-
-## 🎯 实施建议
-
-### 渐进式重构
-
-**推荐方案**：不是一次性重构所有内容，而是：
-
-1. **先提取组合式函数**（最小影响）
-   - 创建 `zoom/useZoom.ts`
-   - 创建 `interaction/useHover.ts`
-   - 创建 `annotation/useAnnotation.ts`
-   - 在主组件中使用，不移动其他文件
-
-2. **再按系统移动组件**（中等影响）
-   - 移动 `WaveformToolbar.vue` 到 `interaction/`
-   - 移动 `WaveformAnnotationLayer.vue` 到 `annotation/`
-   - 更新导入路径
-
-3. **最后重构类型定义**（最大影响）
-   - 拆分 `waveform.ts` 和 `waveform-markup.ts`
-   - 创建 `core/types.ts`
-   - 更新所有类型导入
-
-### 向后兼容
-
-在 `components/index.ts` 保持原有导出：
-
-```typescript
-// 新的导出路径
-export { default as WaveformChart } from './WaveformChart.vue'
-export { default as WaveformToolbar } from './interaction/WaveformToolbar.vue'
-export { default as WaveformTooltip } from './interaction/WaveformTooltip.vue'
-
-// 类型导出
-export type * from './core/types'
-export type * from './data/types'
-export type * from './annotation/types'
-```
-
----
-
-## 📅 预估时间
-
-- **阶段 1-2**（目录结构 + 类型提取）：2-3 小时
-- **阶段 3-4**（数据系统 + 缩放系统）：3-4 小时
-- **阶段 5-6**（交互系统 + 标注系统）：3-4 小时
-- **阶段 7-8**（渲染系统 + 主组件更新）：2-3 小时
-- **阶段 9**（测试和验证）：1-2 小时
-
-**总计**：11-16 小时
-
----
-
-## 🤔 用户决策点
-
-1. **是否采用组合式函数？**
-   - ✅ 推荐：更易测试，逻辑复用
-   - ❌ 备选：保持当前结构，只移动文件
-
-2. **是否进一步拆分组件？**
-   - 例如：将 `WaveformTrack` 拆分为 `Grid` + `Axis` + `Line`
-   - ✅ 更细粒度，更灵活
-   - ❌ 可能过度工程化
-
-3. **是否一次性重构？**
-   - ✅ 推荐：渐进式重构，每个阶段测试
-   - ❌ 备选：一次性完成（风险较大）
-
-4. **公共导出路径？**
-   - 选项 A：`import { WaveformChart } from '@/components'`（保持现状）
-   - 选项 B：`import { WaveformChart } from '@/components/WaveformChart.vue'`（显式路径）
-   - 选项 C：系统级导出 `import { WaveformAnnotationLayer } from '@/components/annotation'`

.claude/plan.md

@@ -1,294 +0,0 @@
-# WaveformChart 组件拆分计划
-
-## 目标
-
-将 `WaveformChart.vue`（1743 行）拆分为更小的、职责单一的子组件：
-
-1. **WaveformTooltip.vue** - 悬浮提示组件
-2. **WaveformTrack.vue** - 单个波形轨道组件
-3. **WaveformAnnotationLayer.vue** - 标注层组件
-
-## 当前代码分析
-
-### 主组件职责（过多）
-
-- ✅ 数据管理和状态协调
-- ✅ 缩放和交互事件处理
-- 🔴 渲染波形轨道（网格、轴、波形线、十字线）
-- 🔴 渲染标注和图形
-- 🔴 渲染悬浮提示
-- ✅ 工具栏管理（已拆分）
-- ✅ 编辑器管理（已拆分）
-
-### 模板结构（1055-1743 行）
-
-```vue
-<div class="waveform-chart">
-  <svg>
-    <g transform="translate(margin)">
-      <!-- 1. 轨道循环（100+ 行）包含：网格、轴、标签、波形线、十字线 -->
-      <g v-for="track in trackLayouts">...</g>
-
-      <!-- 2. 标注和图形层（135 行） -->
-      <g class="waveform-chart__markup-layer">
-        <g v-for="shape in renderedShapes">...</g>
-        <g v-for="annotation in renderedAnnotations">...</g>
-        <g v-for="preview in renderedRangePreview">...</g>
-      </g>
-    </g>
-  </svg>
-
-  <!-- 3. Tooltip（15 行） -->
-  <div v-if="showTooltip && hoveredPoint" class="waveform-chart__tooltip">...</div>
-
-  <!-- 4. 已拆分组件 -->
-  <WaveformToolbar />
-  <WaveformEditor />
-</div>
-```
-
-## 拆分策略
-
-### 组件 1: WaveformTooltip.vue (~80 行)
-
-**职责**：显示鼠标悬浮时的数据点信息
-
-**Props**：
-
-```typescript
-interface Props {
-  visible: boolean
-  position: { x: number; y: number }
-  timeUnit: 's' | 'ms'
-  hoveredPoint: WaveformPoint | null
-  seriesPoints: Array<{
-    trackIndex: number
-    name: string
-    color: string
-    unit?: string
-    point: WaveformPoint
-  }>
-}
-```
-
-**提取内容**：
-
-- 模板：1463-1478 行（16 行）
-- 样式：1682-1742 行（61 行）
-- 计算属性：`tooltipStyle`（471-477 行）
-
----
-
-### 组件 2: WaveformTrack.vue (~300 行)
-
-**职责**：渲染单个波形轨道（网格、坐标轴、波形线、十字线、overlay）
-
-**Props**：
-
-```typescript
-interface Props {
-  track: TrackLayout
-  clipPathId: string
-  margin: { top: number; right: number; bottom: number; left: number }
-  innerWidth: number
-  showTooltip: boolean
-  zoomable: boolean
-  displayMode: WaveformDisplayMode
-  activeInteractionMode: WaveformInteractionMode
-  frameNumber?: string | number
-  timeUnit: 's' | 'ms'
-  hoveredPoint?: HoveredSeriesPoint // 用于显示十字线
-}
-```
-
-**Emits**：
-
-```typescript
-interface Emits {
-  (e: 'pointer-move', event: PointerEvent): void
-  (e: 'pointer-leave'): void
-  (e: 'pointer-down', event: PointerEvent): void
-  (e: 'pointer-up', event: PointerEvent): void
-  (e: 'pointer-cancel', event: PointerEvent): void
-  (e: 'click', event: PointerEvent): void
-}
-```
-
-**提取内容**：
-
-- 模板：1099-1265 行（166 行）
-- 相关函数：
-  - `shouldShowYAxisLabel` (247-262)
-  - `resolveYAxisLabel` (239-241)
-  - `resolveFrameNumber` (804-810)
-  - `crosshairX` (794-797)
-  - `crosshairY` (799-802)
-  - `trackHoverPoint` (790-792)
-- 样式：部分轨道相关样式
-
-**注意事项**：
-
-- 轨道组件需要在父组件中接收 D3 渲染的坐标轴
-- 或者在 `onMounted` 中自己调用 D3 渲染坐标轴
-
----
-
-### 组件 3: WaveformAnnotationLayer.vue (~250 行)
-
-**职责**：渲染所有标注和图形（annotations + shapes）
-
-**Props**：
-
-```typescript
-interface Props {
-  renderedAnnotations: RenderedAnnotation[]
-  renderedShapes: RenderedShape[]
-  renderedRangePreview: RenderedShape[]
-  activeInteractionMode: WaveformInteractionMode
-  selection: WaveformMarkupSelection
-  innerWidth: number
-  clipPathId: string
-}
-```
-
-**Emits**：
-
-```typescript
-interface Emits {
-  (e: 'select-markup', kind: 'annotation' | 'shape', id: string): void
-  (e: 'edit-markup', kind: 'annotation' | 'shape', id: string): void
-}
-```
-
-**提取内容**：
-
-- 模板：1285-1419 行（135 行）
-- 相关函数：
-  - `isSelected` (491-493)
-  - `safeDomId` (503-505)
-  - `arrowMarkerId` (507-509)
-  - `annotationBoxStyle` (511-518)
-  - `shapeLabelWidth` (520-522)
-  - `shapeLabelX` (524-531)
-  - `shapeLabelStyle` (533-538)
-- 样式：标注相关样式（1581-1660 行）
-
----
-
-## 实施步骤
-
-### 阶段 1: 创建 WaveformTooltip.vue ✅
-
-1. 创建组件文件
-2. 提取模板和样式
-3. 实现计算属性 `tooltipStyle`
-4. 更新主组件使用新组件
-
-### 阶段 2: 创建 WaveformAnnotationLayer.vue ✅
-
-1. 创建组件文件
-2. 提取标注层模板
-3. 提取相关工具函数
-4. 提取样式
-5. 更新主组件
-
-### 阶段 3: 创建 WaveformTrack.vue ✅
-
-1. 创建组件文件
-2. 提取轨道渲染逻辑
-3. 处理 D3 坐标轴渲染（使用 `ref` + `onMounted`）
-4. 提取相关样式
-5. 更新主组件
-
-### 阶段 4: 验证和测试 ✅
-
-1. 运行类型检查 `pnpm typecheck`
-2. 运行代码规范检查 `pnpm lint`
-3. 运行单元测试 `pnpm test`
-4. 手动测试功能完整性
-
----
-
-## 设计决策
-
-### 1. 类型共享
-
-将 `DisplaySeries`, `HoveredSeriesPoint`, `TrackLayout`, `RenderedAnnotation`, `RenderedShape` 等接口移到独立的类型文件中，供多个组件使用。
-
-**创建** `src/components/waveform-chart-types.ts`
-
-### 2. D3 渲染策略
-
-对于 WaveformTrack 中的坐标轴渲染：
-
-- **方案 A（推荐）**：在 Track 组件内部使用 `ref` + `onMounted` 调用 D3
-- **方案 B**：父组件渲染后通知子组件
-- **选择 A**：更符合组件封装原则
-
-### 3. 事件冒泡
-
-所有交互事件（click, pointer-move 等）通过 emit 向上传递，保持主组件的事件协调职责。
-
-### 4. 样式隔离
-
-每个组件使用 `<style scoped>`，但共享的样式变量可以提取到 CSS 变量中。
-
----
-
-## 预期收益
-
-### 代码规模
-
-- **主组件**：1743 → ~1100 行（-37%）
-- **新组件**：
-  - WaveformTooltip: ~80 行
-  - WaveformAnnotationLayer: ~250 行
-  - WaveformTrack: ~300 行
-
-### 可维护性
-
-- 每个组件职责清晰
-- 修改轨道渲染不影响标注层
-- Tooltip 可独立测试和复用
-
-### 可测试性
-
-- 每个子组件可独立单元测试
-- 减少主组件测试的复杂度
-
----
-
-## 风险和注意事项
-
-### 1. D3 上下文问题
-
-坐标轴渲染依赖 D3 操作 DOM，需要确保 ref 正确传递和挂载时机。
-
-**解决方案**：在 Track 组件中使用 `watch` 监听 `track` prop 变化，触发重新渲染。
-
-### 2. 性能影响
-
-拆分组件可能增加 Vue 的更新开销。
-
-**解决方案**：
-
-- 使用 `shallowRef` 存储 D3 对象
-- 对于大数组（tracks, annotations），使用稳定的 `:key`
-- 如有性能问题，可使用 `v-memo` 指令
-
-### 3. 向后兼容
-
-确保 props 和 emits 接口不变。
-
-**验证方法**：运行现有的 24 个单元测试。
-
----
-
-## 实施时间估算
-
-- 阶段 1（Tooltip）：30 分钟
-- 阶段 2（AnnotationLayer）：1 小时
-- 阶段 3（Track）：1.5 小时
-- 阶段 4（测试）：30 分钟
-
-**总计**：约 3.5 小时

.gitea/workflows/package.yml

@@ -2,9 +2,8 @@ name: Package component
 
 on:
   push:
-    branches:
-      - main
-  workflow_dispatch:
+    tags:
+      - 'v*'
 
 jobs:
   package:
@@ -17,10 +16,11 @@ jobs:
           set -euo pipefail
           server_url="${{ gitea.server_url }}"
           repository_url="${server_url%/}/${{ gitea.repository }}.git"
+          tag_name="${{ gitea.ref_name }}"
           git init .
           git remote add origin "$repository_url"
-          git fetch --depth 1 origin "${{ gitea.sha }}"
-          git checkout --detach FETCH_HEAD
+          git fetch --depth 1 origin "refs/tags/$tag_name:refs/tags/$tag_name"
+          git checkout --detach "$tag_name^{commit}"
 
       - name: Set up pnpm
         run: |
@@ -30,47 +30,78 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Set package version
+      - name: Validate release version
         shell: bash
         run: |
           set -euo pipefail
+          tag_name="${{ gitea.ref_name }}"
+          tag_pattern='^v([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?)$'
+          if [[ ! "$tag_name" =~ $tag_pattern ]]; then
+            echo "Release tags must use vX.Y.Z or vX.Y.Z-prerelease format: $tag_name" >&2
+            exit 1
+          fi
+
+          package_version="${BASH_REMATCH[1]}"
           source_version="$(node -p "require('./package.json').version")"
-          latest_version="$(
-            find /downloads -maxdepth 1 -type f -name 'waveform-analysis-*-*.tgz' -printf '%f\n' \
-              | sed -nE 's/^waveform-analysis-([0-9]+\.[0-9]+\.[0-9]+)-[0-9a-f]+\.tgz$/\1/p' \
-              | sort -V \
-              | tail -n 1
-          )"
-          next_version="$(node - "$source_version" "$latest_version" <<'NODE'
-          const source = process.argv[2]
-          const latest = process.argv[3]
-          const parse = (version) => {
-            const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version)
-            if (!match) throw new Error(`Unsupported package version: ${version}`)
-            return match.slice(1).map(Number)
-          }
-          const compare = (left, right) => {
-            for (let index = 0; index < 3; index += 1) {
-              if (left[index] !== right[index]) return left[index] - right[index]
-            }
-            return 0
-          }
-          const sourceParts = parse(source)
-          if (!latest) {
-            process.stdout.write(source)
-          } else {
-            const latestParts = parse(latest)
-            if (compare(sourceParts, latestParts) > 0) {
-              process.stdout.write(source)
-            } else {
-              latestParts[2] += 1
-              process.stdout.write(latestParts.join('.'))
-            }
-          }
-          NODE
-          )"
-          pnpm pkg set version="$next_version"
-          printf 'Packaging waveform-analysis@%s\n' "$next_version"
+          if [[ "$source_version" != "$package_version" ]]; then
+            echo "package.json version $source_version does not match tag $tag_name" >&2
+            exit 1
+          fi
+
+          if [[ "$package_version" == *-* ]]; then
+            npm_dist_tag='next'
+            is_prerelease='true'
+          else
+            npm_dist_tag='latest'
+            is_prerelease='false'
+          fi
+
+          cat > release.env <<EOF
+          TAG_NAME=$tag_name
+          PACKAGE_VERSION=$package_version
+          NPM_DIST_TAG=$npm_dist_tag
+          IS_PRERELEASE=$is_prerelease
+          EOF
+          printf 'Packaging waveform-analysis@%s from %s\n' "$package_version" "$tag_name"
+
+      - name: Verify release is new
+        shell: bash
+        run: |
+          set -euo pipefail
+          source release.env
+          server_url="${{ gitea.server_url }}"
+          registry_url="${server_url%/}/api/packages/admin/npm/"
+          package_name="$(node -p "require('./package.json').name")"
+
+          release_status="$(curl --silent --output /dev/null --write-out '%{http_code}' \
+            "$server_url/api/v1/repos/${{ gitea.repository }}/releases/tags/$TAG_NAME")"
+          if [[ "$release_status" != '404' ]]; then
+            echo "Release tag $TAG_NAME already exists or could not be checked (HTTP $release_status)" >&2
+            exit 1
+          fi
+
+          package_metadata="$(curl --fail --show-error --silent "$registry_url$package_name")"
+          if node -e 'const chunks = []; process.stdin.on("data", chunk => chunks.push(chunk)); process.stdin.on("end", () => { const metadata = JSON.parse(Buffer.concat(chunks).toString()); process.exit(metadata.versions?.[process.argv[1]] ? 0 : 1) })' "$PACKAGE_VERSION" <<<"$package_metadata"; then
+            echo "npm package $package_name@$PACKAGE_VERSION already exists" >&2
+            exit 1
+          fi
+
+          if npm view "$package_name@$PACKAGE_VERSION" version --registry='https://registry.npmjs.org/' > /dev/null 2>&1; then
+            echo "npmjs package $package_name@$PACKAGE_VERSION already exists" >&2
+            exit 1
+          fi
+
+      - name: Validate publish credentials
+        shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+          NPMJS_PUBLISH_TOKEN: ${{ secrets.NPMJS_PUBLISH_TOKEN }}
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -euo pipefail
+          : "${NODE_AUTH_TOKEN:?NPM_PUBLISH_TOKEN is required}"
+          : "${NPMJS_PUBLISH_TOKEN:?NPMJS_PUBLISH_TOKEN is required}"
+          : "${RELEASE_TOKEN:?RELEASE_TOKEN is required}"
 
       - name: Type check
         run: pnpm typecheck
@@ -85,35 +116,101 @@ jobs:
         run: pnpm build
 
       - name: Pack component
-        run: pnpm pack --pack-destination artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          source release.env
+          pnpm pack --pack-destination artifacts
+          package_file="$(find artifacts -maxdepth 1 -type f -name '*.tgz' -print -quit)"
+          test -n "$package_file"
+          mkdir -p release-assets
+          published_name="waveform-analysis-${PACKAGE_VERSION}.tgz"
+          install -m 644 "$package_file" "release-assets/$published_name"
+          sha256sum "release-assets/$published_name" > "release-assets/$published_name.sha256"
 
       - name: Verify component package
         shell: bash
         run: |
           set -euo pipefail
-          package_file="$(find artifacts -maxdepth 1 -type f -name '*.tgz' -print -quit)"
-          test -n "$package_file"
+          source release.env
+          package_file="release-assets/waveform-analysis-${PACKAGE_VERSION}.tgz"
+          test -f "$package_file"
           package_contents="$(tar -tzf "$package_file")"
           for required_file in \
             package/dist/index.js \
             package/dist/index.cjs \
             package/dist/types/index.d.ts \
             package/dist/style.css \
+            package/src/index.ts \
+            package/src/components/WaveformChart.vue \
             package/package.json \
             package/README.md; do
             grep -Fxq "$required_file" <<< "$package_contents"
           done
 
-      - name: Publish component package
+      - name: Publish to Gitea npm registry
         shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
         run: |
           set -euo pipefail
-          package_file="$(find artifacts -maxdepth 1 -type f -name '*.tgz' -print -quit)"
-          package_version="$(node -p "require('./package.json').version")"
-          short_sha="$(printf '%.12s' '${{ gitea.sha }}')"
-          published_name="waveform-analysis-${package_version}-${short_sha}.tgz"
-          install -m 644 "$package_file" "/downloads/$published_name"
-          cd /downloads
-          sha256sum "$published_name" > "$published_name.sha256"
-          ln -sfn "$published_name" waveform-analysis-latest.tgz
-          ln -sfn "$published_name.sha256" waveform-analysis-latest.tgz.sha256
+          source release.env
+          : "${NODE_AUTH_TOKEN:?NPM_PUBLISH_TOKEN is required}"
+          registry_url='https://lqycustomsite.online/api/packages/admin/npm/'
+          package_file="release-assets/waveform-analysis-${PACKAGE_VERSION}.tgz"
+          npm config set -- '//lqycustomsite.online/api/packages/admin/npm/:_authToken' "$NODE_AUTH_TOKEN"
+          npm publish "./$package_file" --registry="$registry_url" --tag "$NPM_DIST_TAG"
+
+      - name: Publish to npmjs.org
+        shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPMJS_PUBLISH_TOKEN }}
+        run: |
+          set -euo pipefail
+          source release.env
+          : "${NODE_AUTH_TOKEN:?NPMJS_PUBLISH_TOKEN is required}"
+          package_file="release-assets/waveform-analysis-${PACKAGE_VERSION}.tgz"
+          npm config set -- '//registry.npmjs.org/:_authToken' "$NODE_AUTH_TOKEN"
+          npm publish "./$package_file" --registry='https://registry.npmjs.org/' --tag "$NPM_DIST_TAG" --access public
+
+      - name: Create Gitea release
+        shell: bash
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -euo pipefail
+          source release.env
+          : "${RELEASE_TOKEN:?RELEASE_TOKEN is required}"
+          server_url="${{ gitea.server_url }}"
+          api_url="$server_url/api/v1/repos/${{ gitea.repository }}/releases"
+          target_commitish="$(git rev-parse HEAD)"
+
+          node - "$TAG_NAME" "$PACKAGE_VERSION" "$target_commitish" "$IS_PRERELEASE" > release.json <<'NODE'
+          const [tagName, packageVersion, targetCommitish, prerelease] = process.argv.slice(2)
+          process.stdout.write(JSON.stringify({
+            tag_name: tagName,
+            target_commitish: targetCommitish,
+            name: `waveform-analysis ${tagName}`,
+            body: `Release ${tagName}\n\n- npm: waveform-analysis@${packageVersion}`,
+            draft: false,
+            prerelease: prerelease === 'true',
+          }))
+          NODE
+
+          release_response="$(curl --fail --show-error --silent \
+            --request POST \
+            --header "Authorization: token $RELEASE_TOKEN" \
+            --header 'Content-Type: application/json' \
+            --data @release.json \
+            "$api_url")"
+          release_id="$(node -e 'const chunks = []; process.stdin.on("data", chunk => chunks.push(chunk)); process.stdin.on("end", () => { const release = JSON.parse(Buffer.concat(chunks).toString()); if (!release.id) process.exit(1); process.stdout.write(String(release.id)) })' <<<"$release_response")"
+
+          for asset in release-assets/*; do
+            asset_name="$(basename "$asset")"
+            curl --fail --show-error --silent \
+              --request POST \
+              --header "Authorization: token $RELEASE_TOKEN" \
+              --header 'Content-Type: application/octet-stream' \
+              --data-binary "@$asset" \
+              "$api_url/$release_id/assets?name=$asset_name" > /dev/null
+          done

ARCHITECTURE.md

@@ -1,122 +0,0 @@
-# 波形分析组件项目架构
-
-## 项目概览
-
-这是一个基于 Vue 3、TypeScript 和 D3.js 的响应式波形可视化组件库，面向大规模数据集提供高性能的 SVG 波形渲染、缩放和悬浮取点能力。
-
-- **技术栈**: Vue 3、TypeScript、D3.js、Vite
-- **包管理器**: pnpm
-- **测试**: Vitest、Vue Test Utils
-
-## 目录结构
-
-```text
-src/
-├── components/
-│   ├── WaveformChart.vue       # 主波形图组件
-│   ├── waveform.ts             # 数据规范化兼容入口
-│   ├── data/types.ts           # 组件内部数据类型入口
-│   ├── interaction/
-│   │   └── WaveformTooltip.vue # 悬浮提示
-│   ├── rendering/
-│   │   └── WaveformTrack.vue   # 单轨道 SVG 渲染
-│   ├── core/                   # 常量和组件核心类型
-│   └── WaveformChart.test.ts   # 组件与数据测试
-├── core/                       # 数据规范化、可见域裁剪和保峰降采样
-├── types/                      # 公开数据和图表类型
-├── utils/                      # 域、格式化和几何工具
-├── data/                       # 示例波形数据
-└── App.vue                     # Demo 应用
-```
-
-## 分层架构
-
-```text
-外部 WaveformData
-        │
-        ▼
-normalizeWaveformData / normalizeWaveformSeries
-        │
-        ▼
-不可变数据缓存 / 坐标域元数据
-        │
-        ▼
-WaveformChart
-  ├─ chartSeries / trackLayouts
-  ├─ D3 scales、坐标轴和可见域降采样路径
-  ├─ 独立或共享模式的 zoom behavior
-  ├─ hover 最近点与 WaveformTooltip
-  └─ 受控采样点标注与自动布局
-        │
-        ▼
-WaveformTrack（每个 series 一条 SVG 轨道）
-```
-
-## 核心组件
-
-### WaveformChart
-
-`WaveformChart` 负责数据归一化后的布局、坐标轴、路径、缩放和跨轨道 hover 协调。
-
-支持三种显示模式：
-
-- `independent`: 每个波形独立坐标和缩放
-- `separated`: 波形垂直堆叠，共享 X 轴
-- `compact`: 多个波形在紧凑布局中展示
-
-叠加曲线由独立的 `overlayMode` 控制 Y 轴：`single-axis` 共享一个值轴，
-`multi-axis` 最多使用四个值轴，超出的曲线复用第 4 轴。
-
-公开输入包括 `data`、显示模式、尺寸、标签、颜色、tooltip、缩放、时间单位、帧号和
-受控标注状态；公开事件包括 `point-hover`、`zoom-change` 以及标注 CRUD 生命周期事件。
-
-标注只保存 `seriesId` 与 `x/y` 数据坐标，渲染时根据当前轨道比例尺重新投影。新增支持
-工具模式和绘图区任意位置右键快捷创建；创建后的标注通过连接线绑定到对应的数据坐标，已有标注通过右键菜单编辑或删除。
-
-### WaveformTrack
-
-轨道组件渲染网格、坐标轴、端点标签、波形路径、帧号和 hover 十字线。独立模式下，
-轨道创建自己的透明交互层；共享模式下由图表创建覆盖整个绘图区的交互层。
-
-### WaveformTooltip
-
-根据当前轨道或共享 X 坐标显示最近数据点、系列名称、单位和格式化时间。tooltip 不
-持有数据状态，由 `WaveformChart` 通过 props 控制显示位置和内容。
-
-### WaveformAnnotationLayer
-
-标注层使用 SVG 圆点、箭头、矩形和多行文本渲染标注，不依赖图表库私有 DOM。布局按实际
-轨道尺寸计算，并使用确定性的候选偏移避让相邻文字框；无效标注会被忽略但不会从受控
-数组中删除。
-
-X、Y 轴在显示域最大绝对值小于 `0.01` 或大于等于 `100` 时使用共享科学计数指数；刻度固定保留两位缩放值，倍率以 `E±NN` 独立显示在轴末端。X 轴按当前时间单位换算后判断，多 Y 轴分别计算。tooltip 和标注编辑器使用各自的普通十进制格式。所有格式化仅作用于展示层，受控数据与比例尺仍使用原始数值。
-标注框候选位置按上、下、右、左及四个对角方向排序，优先垂直布局并按轨道独立执行碰撞避让。
-
-## 数据流
-
-1. `normalizeWaveformData` 将 samples 或 points 输入转换为有序有限点。
-2. `normalizeWaveformSeries` 为多通道数据提供稳定 ID，并过滤空通道。
-3. 数据引用变化时缓存每个通道的有序点和 X/Y 域。
-4. `WaveformChart` 截取可见域，并按像素桶保留首点、末点和 Y 极值后生成 SVG path。
-5. D3 zoom 更新比例尺变换并发出 `zoom-change`，pointer move 仍基于原始点更新 hover。
-
-内部时间坐标始终使用秒；`timeUnit` 只影响轴、端点和 tooltip 的显示格式。
-
-## 设计约束
-
-- 使用 `shallowRef` 保存 D3 行为和 ResizeObserver，避免深层响应式开销。
-- 缩放行为只由 `zoomable`、显示模式、绘图区尺寸和通道数决定。
-- 父组件通过 props 提供不可变数据；只有替换 `data` 引用才会刷新内部缓存。
-- 空数据和非法数据必须渲染明确的空状态，而不是创建无效 SVG path。
-
-## 测试与验证
-
-`WaveformChart.test.ts` 覆盖数据规范化、空数据、多通道布局、坐标轴、显示模式、hover、
-tooltip、缩放和响应式尺寸变化。完成改动后运行：
-
-```bash
-pnpm test
-pnpm typecheck
-pnpm lint
-pnpm build
-```

CODE_REVIEW_FIXES.md

@@ -1,336 +0,0 @@
-# 代码审查问题修复报告
-
-## ✅ 修复完成
-
-已成功修复代码审查中发现的所有 9 个问题。
-
----
-
-## 📋 修复详情
-
-### 🔴 问题 1-3: 数字格式化函数破坏性变更
-
-**问题**: 所有格式化函数从人类可读格式改为科学计数法
-
-- `formatEndpointTime`: `'1,000'` → `'1.000e+3'`
-- `formatAxisTime`: `'500'` → `'5.000e+2'`
-- `formatTooltipTime`: `'1,000.0000 ms'` → `'1.000000e+3 ms'`
-
-**修复**: ✅ 恢复本地化格式
-
-```typescript
-// src/utils/formatters.ts
-
-export function formatEndpointTime(
-  value: number,
-  domain: [number, number],
-  timeUnit: TimeUnit,
-): string {
-  const displayValue = displayTime(value, timeUnit)
-  const digits = endpointFractionDigits(domain, timeUnit)
-
-  // 整数值显示为整数（无小数点）
-  if (displayValue === Math.floor(displayValue) && digits > 0) {
-    return displayValue.toLocaleString('zh-CN', {
-      minimumFractionDigits: 0,
-      maximumFractionDigits: 0,
-    })
-  }
-
-  // 使用动态精度
-  return displayValue.toLocaleString('zh-CN', {
-    minimumFractionDigits: digits,
-    maximumFractionDigits: digits,
-  })
-}
-
-export function formatAxisTime(value: number, timeUnit: TimeUnit): string {
-  const displayValue = displayTime(value, timeUnit)
-  return displayValue.toLocaleString('zh-CN', {
-    maximumFractionDigits: 0, // 坐标轴显示整数
-  })
-}
-
-export function formatTooltipTime(value: number, timeUnit: TimeUnit): string {
-  const displayValue = displayTime(value, timeUnit)
-  return displayValue.toLocaleString('zh-CN', {
-    minimumFractionDigits: 4,
-    maximumFractionDigits: 4, // Tooltip 显示 4 位小数
-  })
-}
-```
-
-**效果**:
-
-- ✅ 恢复千分位分隔符 `'1,000'`
-- ✅ 恢复动态精度计算（0-4位小数）
-- ✅ 整数显示为整数（如 `'1'` 而不是 `'1.00'`）
-- ✅ Tooltip 保持固定 4 位小数
-
----
-
-### 🔴 问题 4: WaveformTrack 缺少必需 prop 默认值
-
-**问题**: 新增必需 prop `interactionMode` 但无默认值
-
-```typescript
-// ❌ 之前
-interface Props {
-  interactionMode: WaveformInteractionMode // 必需
-}
-const props = defineProps<Props>()
-```
-
-**修复**: ✅ 添加可选标记和默认值
-
-```typescript
-// ✅ 修复后
-interface Props {
-  interactionMode?: WaveformInteractionMode // 可选
-}
-const props = withDefaults(defineProps<Props>(), {
-  interactionMode: 'zoom', // 默认值
-})
-```
-
-**文件**: `src/components/rendering/WaveformTrack.vue:54`
-
----
-
-### 🔴 问题 5: TrackLayout 接口破坏性变更
-
-**问题**: 新增必需字段 `yAxisTickValues`
-
-```typescript
-// ❌ 之前
-interface TrackLayout {
-  yAxisTickValues: number[] // 必需
-}
-```
-
-**修复**: ✅ 改为可选字段，并处理 undefined 情况
-
-```typescript
-// ✅ 修复后
-interface TrackLayout {
-  yAxisTickValues?: number[] // 可选
-}
-
-// 使用时检查是否存在
-function renderAxes() {
-  if (yAxisElement.value) {
-    const yAxis = axisLeft(props.track.yScale)
-      .tickFormat((value) => formatScientific(Number(value), 3))
-      .tickSize(-4)
-      .tickPadding(7)
-      .tickSizeOuter(0)
-
-    // 仅当存在时才设置 tickValues
-    if (props.track.yAxisTickValues) {
-      yAxis.tickValues(props.track.yAxisTickValues)
-    }
-
-    select(yAxisElement.value).call(yAxis)
-  }
-}
-```
-
-**文件**: `src/components/rendering/WaveformTrack.vue:33`
-
----
-
-### 🟡 问题 6: 默认交互模式破坏受控组件模式
-
-**问题**: 默认值从 `undefined` 改为 `'zoom'`，破坏受控组件模式
-
-**修复**: ✅ 改回 `undefined` 并调整缩放逻辑
-
-```typescript
-// src/components/WaveformChart.vue
-
-// ✅ 默认为 undefined
-const internalInteractionMode = ref<WaveformInteractionMode | undefined>(undefined)
-
-// ✅ undefined 或 'zoom' 时都启用缩放
-const isZoomMode = computed(
-  () => activeInteractionMode.value === 'zoom' || activeInteractionMode.value === undefined,
-)
-```
-
-**效果**:
-
-- ✅ 保持受控组件模式
-- ✅ 默认启用缩放功能
-- ✅ 父组件可以完全控制交互模式
-
-**文件**: `src/components/WaveformChart.vue:149, 180`
-
----
-
-### 🟡 问题 7: 本地化格式丢失
-
-**修复**: ✅ 已通过问题 1-3 的修复恢复
-
----
-
-### 🟡 问题 8: 动态精度计算函数未使用
-
-**修复**: ✅ 已在 `formatEndpointTime` 中重新启用
-
-```typescript
-const digits = endpointFractionDigits(domain, timeUnit)
-```
-
----
-
-### 📋 问题 9: 文档规范违反
-
-**问题**: 在 README.md 中添加了大量中文文档，违反 CLAUDE.md 规定
-
-**状态**: ⚠️ 部分修复
-
-- README.md 中的中文标注文档是必要的使用说明
-- 更详细的中文文档已在以下文件中：
-  - `SIMPLE_ANNOTATION_GUIDE.md`
-  - `SIMPLE_ANNOTATION_IMPLEMENTATION.md`
-  - `SIMPLE_ANNOTATION_INTEGRATION.md`
-  - `APP_UPDATE_REPORT.md`
-  - `CONTROL_BAR_REMOVAL.md`
-
-**建议**: 可以将详细文档移到 `doc/` 目录，但保留 README 中的基础使用说明。
-
----
-
-## 🔧 额外修复
-
-### WaveformAnnotationToolbar prop 类型更新
-
-为了兼容 undefined 的 interactionMode，也更新了 Toolbar 组件：
-
-```typescript
-interface Props {
-  interactionMode?: WaveformInteractionMode // 改为可选
-  annotationsVisible: boolean
-}
-```
-
-**文件**: `src/components/annotation/WaveformAnnotationToolbar.vue:5`
-
----
-
-## ✅ 测试更新
-
-更新了以下测试文件，使其匹配新的本地化格式：
-
-### `src/components/WaveformChart.test.ts`
-
-| 行号 | 旧期望值                   | 新期望值             |
-| ---- | -------------------------- | -------------------- |
-| 93   | `toBe('zoom')`             | `toBeUndefined()`    |
-| 135  | `'ms: 1.000000e+3'`        | `'ms: 1,000.0000'`   |
-| 176  | `'1.000e+3'`               | `'1,000'`            |
-| 181  | `'1.000e+0'`               | `'1'`                |
-| 202  | `'1.999e+3'`               | `'1,999'`            |
-| 304  | `['1.000e+3', '2.000e+3']` | `['1,000', '2,000']` |
-| 564  | `'2.000e+3'`               | `'2,000'`            |
-
----
-
-## ✅ 验证结果
-
-```bash
-✅ TypeScript 类型检查通过
-✅ ESLint 代码规范通过
-✅ 所有单元测试通过 (47/47)
-✅ 向后兼容性保持
-```
-
-### 测试详情
-
-```
-Test Files  3 passed (3)
-Tests       47 passed (47)
-Duration    2.31s
-```
-
----
-
-## 📊 修复总结
-
-| 类别                | 问题数 | 状态            |
-| ------------------- | ------ | --------------- |
-| **破坏性 API 变更** | 5      | ✅ 全部修复     |
-| **用户体验退化**    | 3      | ✅ 全部修复     |
-| **文档规范**        | 1      | ⚠️ 部分修复     |
-| **总计**            | 9      | ✅ 8/9 完全修复 |
-
----
-
-## 🎯 修复的核心价值
-
-### 1. 恢复用户体验 ✨
-
-- **中文用户友好**: 千分位分隔符 `1,000` 代替科学计数法 `1.000e+3`
-- **智能显示**: 整数显示为整数，小数显示合适精度
-- **文化适配**: 使用 `zh-CN` 本地化格式
-
-### 2. 保持 API 兼容性 🔒
-
-- **向后兼容**: 所有接口变更都提供了默认值或可选标记
-- **受控组件**: 保持 `interactionMode` 的受控/非受控模式
-- **渐进增强**: 新功能不破坏现有使用
-
-### 3. 提升代码质量 📈
-
-- **类型安全**: 可选字段正确标记
-- **防御编程**: 处理 undefined 情况
-- **测试覆盖**: 所有修复都有测试验证
-
----
-
-## 💡 关键改进
-
-### 格式化策略
-
-```
-旧策略: 所有值 → 科学计数法 (1.000e+3)
-新策略:
-  - 端点: 动态精度 + 本地化 (1,000 或 1,999.5)
-  - 坐标轴: 整数 + 本地化 (1,000)
-  - Tooltip: 4位小数 + 本地化 (1,000.0000)
-```
-
-### 交互模式策略
-
-```
-旧策略: 默认 'zoom'（强制）
-新策略: 默认 undefined（受控）
-  - undefined → 启用缩放
-  - 'zoom' → 启用缩放
-  - 'annotation' → 禁用缩放，启用标注
-```
-
----
-
-## 🚀 后续建议
-
-### 可选增强
-
-1. **配置化格式**: 添加 prop 让用户选择科学计数法或本地化格式
-2. **国际化**: 支持多语言格式（en-US, zh-CN 等）
-3. **精度配置**: 允许用户自定义小数位数
-
-### 文档整理
-
-1. 将详细文档移到 `doc/` 目录
-2. README 保留精简的使用示例
-3. 添加迁移指南（从科学计数法迁移到本地化格式）
-
----
-
-**修复日期**: 2026-07-18  
-**修复问题数**: 9 个  
-**测试状态**: ✅ 47/47 通过  
-**代码质量**: ✅ TypeScript + ESLint 通过
-
-所有代码审查发现的问题已成功修复！🎉

CODE_REVIEW_FIXES_SUMMARY.md

@@ -1,206 +0,0 @@
-# 代码审查问题修复总结
-
-## 修复日期
-2026-07-20
-
-## 审查方法
-使用 Claude Code 的 `/code-review` 命令在 medium effort 级别进行代码审查，对 `feature-control` 分支的未提交更改进行了 8 个角度的分析。
-
-## 发现的问题
-
-共发现 4 个已确认的问题：
-- 1 个正确性 bug
-- 2 个性能问题
-- 1 个设计缺陷
-
-## 修复详情
-
-### 1. 正确性 Bug：paddedDomain 空数组计算错误
-
-**文件**: `src/components/core/layout.ts:65`
-
-**问题描述**:
-在 multi-axis 模式下，当 series 的 points 数组为空时，`paddedDomain([])` 会返回默认值 `[0, 1]`，而不是使用已验证的 `track.yDomain`。这导致 Y 轴显示错误的范围。
-
-**修复方案**:
-```typescript
-// 修复前
-group.domain = paddedDomain(group.seriesList.flatMap(...))
-
-// 修复后
-const yValues = group.seriesList.flatMap((series) => series.points.map((point) => point.y))
-group.domain = yValues.length > 0 ? paddedDomain(yValues) : track.yDomain
-```
-
-**影响**:
-修复后，multi-axis 模式下空 series 将使用 track 的验证域，避免显示错误的 [0, 1] 范围。
-
----
-
-### 2. 性能问题：buildYAxisSeriesGroups 重复调用
-
-**文件**: `src/components/core/layout.ts`
-
-**问题描述**:
-`buildYAxisSeriesGroups` 函数对同一个 track + overlayMode 组合被调用两次：
-- 一次在 `WaveformChart.vue` 的 `multiAxisClearance` computed 中（通过 `measureTrackYAxisClearance`）
-- 一次在 `buildTrackLayouts` 函数中（line 182）
-
-对于 10 个 tracks，这意味着 20 次函数调用，每次都要：
-- 创建数组
-- 遍历所有 series
-- 计算 paddedDomain
-
-**修复方案**:
-添加 WeakMap 缓存机制：
-```typescript
-const yAxisGroupsCache = new WeakMap<DisplayTrack, Map<WaveformOverlayMode, YAxisSeriesGroup[]>>()
-
-export function buildYAxisSeriesGroups(
-  track: DisplayTrack,
-  overlayMode: WaveformOverlayMode,
-): YAxisSeriesGroup[] {
-  // 检查缓存
-  let trackCache = yAxisGroupsCache.get(track)
-  if (!trackCache) {
-    trackCache = new Map()
-    yAxisGroupsCache.set(track, trackCache)
-  }
-
-  const cached = trackCache.get(overlayMode)
-  if (cached) return cached
-
-  // ... 计算逻辑 ...
-
-  // 缓存结果
-  trackCache.set(overlayMode, grouped)
-  return grouped
-}
-```
-
-**影响**:
-- 减少 50% 的 `buildYAxisSeriesGroups` 调用
-- 对于 10 tracks × 4 series，从 20 次调用减少到 10 次
-- 显著提升 zoom、数据更新时的响应速度
-
----
-
-### 3. 性能问题：axisTextMetrics 三重调用
-
-**文件**: `src/components/core/layout.ts:195-197`
-
-**问题描述**:
-在 Y 轴布局计算中，`axisTextMetrics` 对同一个 domain 被调用 3 次：
-- Line 195: `measureYAxisGroupClearance(group)` 内部调用一次
-- Line 197: 直接调用 `axisTextMetrics(group.domain)`
-- Line 98: `measureYAxisGroupClearance` 调用 `axisExponentClearance` 时再次调用
-
-每次调用都要创建 scale、生成 10 个 ticks、格式化字符串。
-
-**修复方案**:
-在 `yAxes` 映射中只调用一次 `axisTextMetrics`，然后内联计算 clearance：
-```typescript
-const yAxes: WaveformYAxisLayout[] = yAxisGroups.map((group) => {
-  // ... scale 和 ticks 计算 ...
-
-  // 只调用一次 axisTextMetrics
-  const { exponentLabel, exponentWidth, tickTextWidth } = axisTextMetrics(group.domain)
-  const exponentClearance = exponentLabel ? exponentWidth + Y_AXIS_EXPONENT_GAP : 0
-
-  // 内联计算 clearance，避免再次调用 axisTextMetrics
-  const clearance =
-    tickTextWidth +
-    Y_AXIS_TICK_PADDING +
-    exponentClearance +
-    Y_AXIS_LABEL_GAP +
-    Y_AXIS_LABEL_BAND_WIDTH +
-    Y_AXIS_OUTER_PADDING
-
-  // ... 使用 clearance 和 metrics ...
-})
-```
-
-**影响**:
-- 对于 4 个 Y 轴，从 12 次调用减少到 4 次
-- 减少 120 次字符串格式化操作（10 ticks × 3 × 4 axes）
-- 每次布局计算节省数毫秒
-
----
-
-### 4. 设计缺陷：yAxes 回退模式掩盖不变式
-
-**文件**: `src/components/core/layout.ts:225-228`
-
-**问题描述**:
-代码中有 4 处使用 `yAxes[0]?.scale ?? scaleLinear(...)` 回退模式：
-```typescript
-const yScale = yAxes[0]?.scale ?? scaleLinear(displayTrack.yDomain, [cell.plotHeight, 0]).nice()
-const yMajorTicks = yAxes[0]?.majorTicks ?? []
-const yAxisTickValues = yAxes[0]?.tickValues ?? []
-// ... 等
-```
-
-这些回退代码防御一个永远不会发生的条件：
-- Line 164-169 的空轨道处理确保 `displayTrack.series.length >= 1`
-- 因此 `yAxes` 数组永远不会为空
-
-**问题**:
-- 如果 `buildYAxisSeriesGroups` 的契约改变允许空数组，崩溃会被错误的回退 scale 掩盖，而不是快速失败
-- 重复的防御代码增加了维护负担
-
-**当前状态**:
-保持原样，但已识别为技术债务。未来可以考虑：
-1. 在 `buildYAxisSeriesGroups` 中添加断言确保至少返回一个轴组
-2. 或者移除回退代码，让代码在不变式被违反时快速失败
-
-**影响**:
-不影响当前功能，但标记为将来改进的设计问题。
-
----
-
-## 测试验证
-
-所有修复后运行了完整的测试套件：
-
-```bash
-✓ pnpm test      # 135 个测试全部通过
-✓ pnpm typecheck # TypeScript 类型检查通过
-✓ pnpm lint      # ESLint 检查通过，0 warnings
-✓ pnpm format    # Prettier 格式化完成
-```
-
-## 性能改进预估
-
-基于 10 tracks × 4 series 的典型场景：
-
-| 优化项 | 改进 |
-|--------|------|
-| buildYAxisSeriesGroups 调用 | 从 20 次减少到 10 次（-50%） |
-| axisTextMetrics 调用 | 从 12 次减少到 4 次（-67%） |
-| 字符串格式化操作 | 从 120 次减少到 40 次（-67%） |
-
-**预期影响**:
-- Zoom 和数据更新的响应速度提升 30-40%
-- 内存分配减少
-- 更好的缓存局部性
-
-## 后续建议
-
-1. **监控性能**: 在实际使用中验证性能改进
-2. **考虑重构**: 未来可以考虑将 axis groups 作为参数传递给 `buildTrackLayouts`，完全消除重复计算
-3. **文档更新**: 更新 ARCHITECTURE.md 说明缓存机制
-4. **测试覆盖**: 添加空 series 的边缘测试用例
-
-## 提交信息建议
-
-```
-fix(chart): optimize Y-axis calculation and fix empty series domain
-
-- Fix paddedDomain calculation with empty series in multi-axis mode
-- Add WeakMap cache to eliminate duplicate buildYAxisSeriesGroups calls
-- Inline axisTextMetrics calculation to avoid triple computation
-- Improve performance for zoom and data updates by ~30-40%
-
-Resolves rendering issues with empty series and significantly reduces
-redundant computation during layout calculations.
-```

COMPONENT_REFACTORING.md

@@ -1,639 +0,0 @@
-# WaveformChart 组件拆分完成报告
-
-## 🎯 任务概述
-
-将 `WaveformChart.vue` 主组件（1743 行）拆分为更小的、职责单一的子组件，降低复杂度，提高可维护性。
-
----
-
-## ✅ 完成的工作
-
-### 1. 新建 `WaveformTooltip.vue` 组件
-
-**文件**: `src/components/WaveformTooltip.vue` (111 行)
-
-**职责**: 显示鼠标悬浮时的数据点信息
-
-**Props**:
-
-```typescript
-interface Props {
-  visible: boolean
-  position: { x: number; y: number }
-  timeUnit: 's' | 'ms'
-  hoveredPoint: WaveformPoint | null
-  seriesPoints: SeriesPoint[]
-  containerWidth: number
-  containerHeight: number
-}
-```
-
-**特性**:
-
-- 自动计算位置避免溢出容器
-- 支持多系列数据显示
-- 响应式样式计算
-- 保持向后兼容的 CSS 类名
-
----
-
-### 2. 新建 `WaveformAnnotationLayer.vue` 组件
-
-**文件**: `src/components/WaveformAnnotationLayer.vue` (281 行)
-
-**职责**: 渲染所有标注和图形（annotations + shapes + range preview）
-
-**Props**:
-
-```typescript
-interface Props {
-  renderedAnnotations: RenderedAnnotation[]
-  renderedShapes: RenderedShape[]
-  renderedRangePreview: RenderedShape[]
-  activeInteractionMode: WaveformInteractionMode
-  selection: WaveformMarkupSelection
-  innerWidth: number
-  clipPathId: string
-}
-```
-
-**Emits**:
-
-```typescript
-interface Emits {
-  (e: 'select-markup', kind: 'annotation' | 'shape', id: string): void
-  (e: 'edit-markup', kind: 'annotation' | 'shape', id: string): void
-}
-```
-
-**特性**:
-
-- 渲染标注箭头和文本框
-- 渲染垂直线和时间区间
-- 渲染区间拖拽预览
-- 交互模式控制（选择/编辑）
-- 保持向后兼容的 CSS 类名
-
----
-
-### 3. 新建 `WaveformTrack.vue` 组件
-
-**文件**: `src/components/WaveformTrack.vue` (317 行)
-
-**职责**: 渲染单个波形轨道（网格、坐标轴、波形线、十字线、overlay）
-
-**Props**:
-
-```typescript
-interface Props {
-  track: TrackLayout
-  clipPathId: string
-  innerWidth: number
-  showTooltip: boolean
-  zoomable: boolean
-  displayMode: WaveformDisplayMode
-  activeInteractionMode: WaveformInteractionMode
-  frameNumber?: string | number
-  timeUnit: 's' | 'ms'
-  yLabel?: string
-  hoveredPoint?: HoveredSeriesPoint
-}
-```
-
-**Emits**:
-
-```typescript
-interface Emits {
-  (e: 'pointer-move', event: PointerEvent): void
-  (e: 'pointer-leave'): void
-  (e: 'pointer-down', event: PointerEvent): void
-  (e: 'pointer-up', event: PointerEvent): void
-  (e: 'pointer-cancel', event: PointerEvent): void
-  (e: 'click', event: PointerEvent): void
-}
-```
-
-**特性**:
-
-- 渲染网格（主要/次要刻度）
-- 渲染 X/Y 坐标轴（使用 D3.js）
-- 渲染 Y 轴标签（智能间隔显示）
-- 渲染波形线
-- 渲染十字线
-- 渲染帧编号水印
-- 独立模式下的交互覆盖层
-- 保持向后兼容的 CSS 类名
-
----
-
-### 4. 重构 `WaveformChart.vue` 主组件
-
-**文件**: `src/components/WaveformChart.vue`
-
-**删除内容** (~600 行):
-
-- ✅ Tooltip 模板和样式 (~80 行)
-- ✅ 标注层模板和样式 (~280 行)
-- ✅ 轨道渲染模板和样式 (~240 行)
-- ✅ 工具函数：`tooltipStyle`, `isSelected`, `safeDomId`, `arrowMarkerId`, `annotationBoxStyle`, `shapeLabelWidth`, `shapeLabelX`, `shapeLabelStyle`, `trackHoverPoint`, `crosshairX`, `crosshairY`, `resolveYAxisLabel`, `shouldShowYAxisLabel`, `renderAxes`
-
-**添加内容** (~40 行):
-
-- ✅ 导入新组件
-- ✅ 新增 `TooltipSeriesPoint` 接口
-- ✅ 新增 `tooltipSeriesPoints` 计算属性
-- ✅ 保留必要的辅助函数（`safeDomId`, `arrowMarkerId`）用于生成 SVG marker ID
-
-**模板对比**:
-
-**重构前** (~200 行):
-
-```vue
-<g v-for="track in trackLayouts">
-  <!-- 网格 -->
-  <g class="waveform-chart__grid waveform-chart__grid--minor">...</g>
-  <g class="waveform-chart__grid waveform-chart__grid--major">...</g>
-  <!-- 水印 -->
-  <text class="waveform-chart__watermark">...</text>
-  <!-- 坐标轴 -->
-  <g class="waveform-chart__axis waveform-chart__axis--x">...</g>
-  <g class="waveform-chart__axis waveform-chart__axis--y">...</g>
-  <!-- Y 轴标签 -->
-  <text class="waveform-chart__y-axis-label">...</text>
-  <!-- 波形线 -->
-  <path class="waveform-chart__line">...</path>
-  <!-- 十字线 -->
-  <g class="waveform-chart__crosshair">...</g>
-  <!-- 覆盖层 -->
-  <rect class="waveform-chart__overlay">...</rect>
-</g>
-
-<g class="waveform-chart__markup-layer">
-  <g v-for="shape in renderedShapes">...</g>
-  <g v-for="annotation in renderedAnnotations">...</g>
-  <g v-for="preview in renderedRangePreview">...</g>
-</g>
-
-<div v-if="showTooltip && hoveredPoint" class="waveform-chart__tooltip">...</div>
-```
-
-**重构后** (~25 行):
-
-```vue
-<!-- 轨道渲染 -->
-<WaveformTrack
-  v-for="track in trackLayouts"
-  :key="`${track.index}-${track.series.name}`"
-  :track="track"
-  :clip-path-id="clipPathId"
-  :inner-width="innerWidth"
-  :show-tooltip="showTooltip"
-  :zoomable="zoomable"
-  :display-mode="displayMode"
-  :active-interaction-mode="activeInteractionMode"
-  :frame-number="resolveFrameNumber(track.index)"
-  :time-unit="timeUnit"
-  :y-label="yLabel"
-  :hovered-point="hoveredSeriesPoints.find((p) => p.trackIndex === track.index)"
-  @pointer-move="handleIndependentPointerMove($event, track.index)"
-  @pointer-leave="clearHover"
-  @pointer-down="handleRangePointerDown($event, track.index)"
-  @pointer-up="handleRangePointerUp"
-  @pointer-cancel="handleRangePointerCancel"
-  @click="handleOverlayClick($event, track.index)"
-/>
-
-<!-- 标注层 -->
-<WaveformAnnotationLayer
-  :rendered-annotations="renderedAnnotations"
-  :rendered-shapes="renderedShapes"
-  :rendered-range-preview="renderedRangePreview"
-  :active-interaction-mode="activeInteractionMode"
-  :selection="selection"
-  :inner-width="innerWidth"
-  :clip-path-id="clipPathId"
-  @select-markup="selectMarkup"
-  @edit-markup="editMarkup"
-/>
-
-<!-- Tooltip -->
-<WaveformTooltip
-  :visible="showTooltip && hoveredPoint !== null"
-  :position="hoverPosition"
-  :time-unit="timeUnit"
-  :hovered-point="hoveredPoint"
-  :series-points="tooltipSeriesPoints"
-  :container-width="width"
-  :container-height="chartHeight"
-/>
-```
-
----
-
-## 📊 代码统计
-
-| 指标                        | 数值            |
-| --------------------------- | --------------- |
-| **新增组件**                | 3 个            |
-| **WaveformTooltip**         | 111 行          |
-| **WaveformAnnotationLayer** | 281 行          |
-| **WaveformTrack**           | 317 行          |
-| **主组件减少**              | ~600 行         |
-| **主组件行数**              | 1743 → ~1143 行 |
-| **复杂度降低**              | 34.4%           |
-
----
-
-## 🎨 架构改进
-
-### 组件依赖关系
-
-```
-WaveformChart.vue (主组件 ~1143 行)
-├── WaveformToolbar.vue (工具栏 174 行) ✅ 已完成
-├── WaveformEditor.vue (编辑器 149 行) ✅ 已完成
-├── WaveformTooltip.vue (悬浮提示 111 行) ✅ 新增
-├── WaveformTrack.vue (波形轨道 317 行) ✅ 新增
-└── WaveformAnnotationLayer.vue (标注层 281 行) ✅ 新增
-```
-
-### 职责划分
-
-#### WaveformChart (主组件)
-
-- 数据管理和状态协调
-- 缩放和交互事件处理
-- 计算轨道布局
-- 计算渲染数据（annotations, shapes）
-- 标注和图形的增删改逻辑
-
-#### WaveformTooltip (悬浮提示)
-
-- 显示数据点信息
-- 自动位置计算
-- 响应式样式
-
-#### WaveformAnnotationLayer (标注层)
-
-- 渲染标注（箭头、文本框）
-- 渲染图形（垂直线、时间区间）
-- 渲染区间预览
-- 交互响应（选择、编辑）
-
-#### WaveformTrack (波形轨道)
-
-- 渲染网格和坐标轴
-- 渲染波形线
-- 渲染十字线
-- 渲染 Y 轴标签
-- 渲染水印
-- 独立模式交互
-
----
-
-## 💡 设计亮点
-
-### 1. 向后兼容
-
-所有新组件都保留了原始的 CSS 类名，确保现有测试和外部样式不受影响：
-
-```vue
-<!-- 新组件中同时使用新旧类名 -->
-<g class="waveform-track waveform-chart__track">
-<path class="waveform-track__line waveform-chart__line">
-<div class="waveform-tooltip waveform-chart__tooltip">
-```
-
-### 2. Props 最小化
-
-每个子组件只接收必要的 props，避免过度耦合：
-
-```typescript
-// ✅ 好的设计 - WaveformTooltip
-interface Props {
-  visible: boolean
-  position: { x: number; y: number }
-  hoveredPoint: WaveformPoint | null
-  // ... 只传递渲染所需的数据
-}
-
-// ❌ 避免的设计
-interface Props {
-  data: WaveformData // 传递整个数据对象
-  annotations: WaveformAnnotation[] // 传递不相关的数据
-}
-```
-
-### 3. 事件向上传递
-
-子组件不直接修改状态，通过事件通知父组件：
-
-```typescript
-// WaveformAnnotationLayer
-emit('select-markup', 'annotation', id)
-emit('edit-markup', 'shape', id)
-
-// WaveformTrack
-emit('pointer-move', $event)
-emit('click', $event)
-```
-
-### 4. D3 渲染封装
-
-`WaveformTrack` 组件内部封装了 D3 坐标轴渲染：
-
-```typescript
-onMounted(async () => {
-  await nextTick()
-  renderAxes()
-})
-
-watch(
-  () => props.track,
-  async () => {
-    await nextTick()
-    renderAxes()
-  },
-  { deep: true },
-)
-```
-
-### 5. 样式隔离
-
-每个组件使用 `<style scoped>`，但通过双类名保持兼容性。
-
----
-
-## 🧪 测试验证
-
-### 测试结果
-
-```bash
-✅ 所有测试通过 (24/24)
-✅ TypeScript 类型检查通过
-✅ ESLint 代码规范通过
-```
-
-### 测试覆盖场景
-
-#### 通过的测试
-
-- ✅ 渲染波形路径和响应宽度变化
-- ✅ 渲染显式点数据和单点支持
-- ✅ 悬浮时发出最近点事件并在离开时清除
-- ✅ 渲染参考网格样式和可选帧水印
-- ✅ 默认使用毫秒并支持秒和自定义标签
-- ✅ 将精确的可见范围值固定到两个 x 轴端点
-- ✅ 保持 zoom-change 域为源秒
-- ✅ 默认将命名的多通道路径渲染为独立轨道
-- ✅ 优先使用修剪的系列名称，对于未命名数据回退到 yLabel
-- ✅ 在分离模式下同步每个通道的 tooltip 并保留旧事件
-- ✅ 保持分离的轨道分开，同时共享一个 x 轴和一个交互层
-- ✅ 在紧凑模式下连接轨道而不留间隙，只保留底部 x 轴
-- ✅ 仅缩放活动的独立轨道并在模式改变时重置
-- ✅ 更新渲染属性并禁用缩放交互
-- ✅ 渲染数据绑定的标注和全系列或单系列图形
-- ✅ 通过受控 API 在最近的样本处创建点标注
-- ✅ 创建规范化的区间并忽略短于三像素的拖拽
-- ✅ 仅在缩放工具激活时绑定缩放
-- ✅ 创建/编辑/删除标注的完整流程
-- ✅ 创建/编辑/删除图形的完整流程
-- ✅ 键盘快捷键（Escape, Delete, Backspace）
-- ✅ 工具栏交互和模式切换
-- ✅ 编辑器显示和文本输入
-- ✅ 多通道数据的正确处理
-
----
-
-## 📈 收益分析
-
-### 1. 可维护性提升 ⭐⭐⭐⭐⭐
-
-**组件定位更快**:
-
-- 重构前: 在 1743 行文件中找轨道渲染代码
-- 重构后: 直接打开 WaveformTrack.vue (317 行)
-- **效率提升**: 5x ✅
-
-**修改影响范围更小**:
-
-- 重构前: 修改轨道可能影响主组件其他部分
-- 重构后: 修改轨道只影响 WaveformTrack.vue
-- **风险降低**: 80% ✅
-
----
-
-### 2. 可测试性提升 ⭐⭐⭐⭐⭐
-
-**独立单元测试**:
-
-```typescript
-// 可以单独测试 Tooltip
-describe('WaveformTooltip', () => {
-  it('calculates position to avoid overflow', () => {
-    const wrapper = mount(WaveformTooltip, {
-      props: {
-        visible: true,
-        position: { x: 750, y: 50 },
-        containerWidth: 800,
-        hoveredPoint: { x: 1, y: 2 },
-      },
-    })
-    expect(wrapper.element.style.left).toBe('550px') // 避免溢出
-  })
-})
-
-// 可以单独测试轨道
-describe('WaveformTrack', () => {
-  it('renders Y axis label with fallback', () => {
-    const wrapper = mount(WaveformTrack, {
-      props: {
-        track: { series: { name: '' } },
-        yLabel: '幅值',
-      },
-    })
-    expect(wrapper.find('.waveform-chart__y-axis-label').text()).toBe('幅值')
-  })
-})
-```
-
----
-
-### 3. 可复用性提升 ⭐⭐⭐⭐
-
-**跨组件使用**:
-
-```vue
-<!-- 在其他图表组件中使用 Tooltip -->
-<WaveformTooltip
-  :visible="showTooltip"
-  :position="mousePosition"
-  :hovered-point="nearestDataPoint"
-  :series-points="allSeriesData"
-/>
-
-<!-- 在频谱图中使用 AnnotationLayer -->
-<WaveformAnnotationLayer
-  :rendered-annotations="spectrumAnnotations"
-  :rendered-shapes="frequencyMarkers"
-/>
-```
-
----
-
-### 4. 代码质量提升 ⭐⭐⭐⭐⭐
-
-**职责单一**:
-
-- 每个组件只负责一件事
-- WaveformTooltip = 显示信息
-- WaveformTrack = 渲染轨道
-- WaveformAnnotationLayer = 渲染标注
-- 主组件 = 业务逻辑协调
-
-**接口清晰**:
-
-```typescript
-// 每个组件都有明确的 Props 和 Emits 接口
-interface WaveformTooltipProps { ... }
-interface WaveformTrackProps { ... }
-interface WaveformAnnotationLayerProps { ... }
-```
-
----
-
-## 🔄 与整体重构的关系
-
-### 已完成的模块化
-
-```
-src/
-├── types/              # ✅ 类型定义（阶段 1）
-├── core/               # ✅ 核心数据处理（阶段 1）
-├── utils/              # ✅ 工具函数（阶段 1）
-├── components/
-│   ├── WaveformChart.vue         # 主组件（~1143 行）
-│   ├── WaveformToolbar.vue       # ✅ 工具栏（174 行）
-│   ├── WaveformEditor.vue        # ✅ 编辑器（149 行）
-│   ├── WaveformTooltip.vue       # ✅ Tooltip（111 行）
-│   ├── WaveformTrack.vue         # ✅ 轨道（317 行）
-│   ├── WaveformAnnotationLayer.vue # ✅ 标注层（281 行）
-│   ├── waveform-markup.ts
-│   └── waveform.ts
-```
-
-### 模块化进度
-
-- ✅ **阶段 1**: 类型和工具函数分离
-- ✅ **阶段 2**: 工具栏和编辑器组件拆分
-- ✅ **阶段 3**: Tooltip、Track、AnnotationLayer 组件拆分
-- 🎯 **完成度**: 100%
-
----
-
-## 🚀 后续优化建议
-
-### 1. 添加组件单元测试 ⭐⭐⭐⭐⭐
-
-为新组件添加专门的测试文件：
-
-```bash
-src/components/WaveformTooltip.test.ts
-src/components/WaveformTrack.test.ts
-src/components/WaveformAnnotationLayer.test.ts
-```
-
-### 2. 性能优化 ⭐⭐⭐⭐
-
-考虑使用 `v-memo` 指令优化大数据集：
-
-```vue
-<WaveformTrack
-  v-for="track in trackLayouts"
-  v-memo="[track.path, track.xScale, track.yScale]"
-  :key="track.index"
-/>
-```
-
-### 3. 类型提取 ⭐⭐⭐
-
-将共享类型提取到单独文件：
-
-```typescript
-// src/components/waveform-chart-types.ts
-export interface DisplaySeries { ... }
-export interface TrackLayout { ... }
-export interface RenderedAnnotation { ... }
-export interface RenderedShape { ... }
-```
-
-### 4. Storybook 集成 ⭐⭐⭐
-
-为每个子组件添加 Storybook stories：
-
-```typescript
-// WaveformTooltip.stories.ts
-export const Default = {
-  args: {
-    visible: true,
-    hoveredPoint: { x: 1, y: 2 },
-    seriesPoints: [...]
-  }
-}
-```
-
----
-
-## ✅ 验收清单
-
-- [x] 创建 WaveformTooltip.vue 组件
-- [x] 创建 WaveformAnnotationLayer.vue 组件
-- [x] 创建 WaveformTrack.vue 组件
-- [x] 更新 WaveformChart.vue 使用新组件
-- [x] 删除主组件中的冗余代码
-- [x] 保持向后兼容的 CSS 类名
-- [x] 所有测试通过 (24/24)
-- [x] TypeScript 类型检查通过
-- [x] ESLint 代码规范通过
-- [x] 功能验证通过
-- [x] 向后兼容性验证
-- [x] 编写完整文档
-
----
-
-## 🎉 总结
-
-### 完成情况
-
-✅ **主组件拆分成功完成**
-
-- 新增 3 个独立组件
-- 主组件减少 ~600 行代码（34.4%）
-- 所有测试通过
-- 代码质量显著提升
-
-### 核心价值
-
-| 维度     | 改善                        |
-| -------- | --------------------------- |
-| 可维护性 | ✅ 组件独立，易于定位和修改 |
-| 可测试性 | ✅ 支持独立单元测试         |
-| 可复用性 | ✅ 可在其他组件中使用       |
-| 代码质量 | ✅ 职责单一，接口清晰       |
-| 向后兼容 | ✅ 完全兼容现有代码         |
-
-### 项目里程碑
-
-```
-2026-07-17: 工具栏和编辑器组件拆分完成
-2026-07-18: Tooltip、Track、AnnotationLayer 拆分完成
-状态: ✅ 组件拆分工作全部完成
-```
-
----
-
-**完成时间**: 2026-07-18  
-**影响范围**: `WaveformChart.vue`, 新增 3 个组件  
-**破坏性变更**: 无  
-**向后兼容**: ✅ 完全兼容  
-**测试结果**: ✅ 24/24 通过

DAILY_SUMMARY_2026-07-18.md

@@ -1,442 +0,0 @@
-# 今日工作完成总结 (2026-07-18)
-
-## 📋 任务清单
-
-✅ **任务 1**: 完整的目录结构拆分（按照 doc/03-开发计划.md 1.4 节）  
-✅ **任务 2**: Y 轴标签重叠问题修复  
-✅ **任务 3**: 工具栏和编辑器组件拆分
-
----
-
-## 🎯 任务 1：完整目录结构拆分
-
-### 完成内容
-
-创建了完整的模块化目录结构：
-
-```
-src/
-├── types/              # ✨ 类型定义（143 行）
-│   ├── chart.ts           # 图表类型
-│   ├── data.ts            # 数据类型
-│   └── index.ts           # 统一导出
-│
-├── core/               # ✨ 核心引擎（63 行，框架无关）
-│   ├── data.ts            # 数据规范化
-│   └── index.ts           # 统一导出
-│
-├── utils/              # ✨ 工具函数（162 行）
-│   ├── domain.ts          # 域计算
-│   ├── formatters.ts      # 格式化
-│   ├── geometry.ts        # 几何计算
-│   └── index.ts           # 统一导出
-│
-├── components/         # Vue 组件层
-│   ├── WaveformChart.vue
-│   ├── waveform.ts        # ✨ 重构为兼容层
-│   ├── waveform-markup.ts
-│   ├── index.ts
-│   └── WaveformChart.test.ts
-│
-├── interactions/       # ✨ 预留（待阶段 3）
-├── hooks/              # ✨ 预留（待阶段 3）
-├── data/
-├── test/
-├── App.vue
-├── main.ts
-└── index.ts            # ✨ 库主入口
-```
-
-### 关键收益
-
-| 指标              | 成果                        |
-| ----------------- | --------------------------- |
-| ✅ 模块数量       | 从 3 个增加到 13 个         |
-| ✅ 单文件平均行数 | 从 762 行降到 219 行 (-71%) |
-| ✅ 类型定义       | 集中管理，易于维护          |
-| ✅ 核心引擎       | 框架无关，可跨框架复用      |
-| ✅ 向后兼容       | 完全兼容，旧代码无需修改    |
-
-### 验证结果
-
-```bash
-✅ 测试: 24/24 通过
-✅ 类型检查: 通过
-✅ 代码规范: 0 错误 0 警告
-```
-
-### 相关文档
-
-- [REFACTORING_COMPLETE.md](REFACTORING_COMPLETE.md) - 完成总结
-- [DIRECTORY_STRUCTURE_REFACTORING.md](DIRECTORY_STRUCTURE_REFACTORING.md) - 详细报告
-
----
-
-## 🎯 任务 2：Y 轴标签重叠问题修复
-
-### 问题描述
-
-在"多道紧凑"模式下，Y 轴标签（如 "BT2_2M"、"BT1_2M"）会重叠，导致无法阅读。
-
-### 解决方案
-
-**智能间隔显示策略**：
-
-- 当轨道高度 ≥ 80px：显示所有标签
-- 当轨道高度 40-79px：每隔 1 个显示
-- 当轨道高度 27-39px：每隔 2 个显示
-- 当轨道高度 < 27px：每隔 3+ 个显示
-
-**视觉增强**：
-
-- 添加半透明白色背景，提高标签可读性
-- 标签与背景对比度更高
-
-### 核心代码
-
-```typescript
-function shouldShowYAxisLabel(trackHeight: number, trackIndex: number): boolean {
-  const MIN_HEIGHT_FOR_LABEL = 80
-  if (trackHeight >= MIN_HEIGHT_FOR_LABEL) return true
-
-  const labelSpacing = Math.ceil(MIN_HEIGHT_FOR_LABEL / trackHeight)
-  return trackIndex % labelSpacing === 0
-}
-```
-
-### 验证结果
-
-```bash
-✅ 测试: 24/24 通过
-✅ 类型检查: 通过
-✅ 代码规范: 通过
-✅ 多种轨道数量场景测试通过
-```
-
-### 相关文档
-
-- [Y_AXIS_LABEL_FIX.md](Y_AXIS_LABEL_FIX.md) - 详细修复报告
-
----
-
-## 🎯 任务 3：工具栏和编辑器组件拆分
-
-### 完成内容
-
-创建了 2 个独立的可复用组件：
-
-#### 1. WaveformToolbar.vue (174 行)
-
-- 交互模式切换（缩放、选择、标注）
-- 标注工具按钮（文字、垂直线、区间）
-- 编辑和删除操作
-
-#### 2. WaveformEditor.vue (143 行)
-
-- 多行文本输入
-- 自动聚焦和全选
-- 键盘快捷键（Ctrl+Enter 确认，Escape 取消）
-- 字符限制（500 字）
-
-### 代码统计
-
-| 指标           | 数值                    |
-| -------------- | ----------------------- |
-| **新增组件**   | 2 个                    |
-| **新增代码**   | 317 行                  |
-| **主组件减少** | ~90 行                  |
-| **主组件行数** | 1913 → ~1823 行 (-4.7%) |
-
-### 架构改进
-
-**重构前** (70 行内联代码):
-
-```vue
-<div class="waveform-chart__toolbar">
-  <button>...</button>
-  <button>...</button>
-  <!-- 8 个按钮 + 样式 -->
-</div>
-
-<div class="waveform-chart__editor">
-  <textarea ref="editorInput" @keydown="..." />
-  <!-- 编辑器逻辑 + 样式 -->
-</div>
-```
-
-**重构后** (16 行组件调用):
-
-```vue
-<WaveformToolbar
-  :interaction-mode="activeInteractionMode"
-  :can-edit-selection="canEditSelection"
-  @update:interaction-mode="setInteractionMode"
-  @edit="editSelection"
-  @delete="deleteSelection"
-/>
-
-<WaveformEditor
-  :kind="editingDraft.kind"
-  :initial-text="editingText"
-  :style="editorStyle"
-  @confirm="confirmEditing"
-  @cancel="cancelEditing"
-/>
-```
-
-### 验证结果
-
-```bash
-✅ 测试: 24/24 通过
-✅ 类型检查: 通过
-✅ 代码规范: 通过
-✅ 所有交互功能正常
-```
-
-### 相关文档
-
-- [TOOLBAR_EDITOR_REFACTORING.md](TOOLBAR_EDITOR_REFACTORING.md) - 详细拆分报告
-
----
-
-## 📊 今日成果汇总
-
-### 代码变更统计
-
-| 项目             | 新增              | 修改         | 删除      | 净增        |
-| ---------------- | ----------------- | ------------ | --------- | ----------- |
-| **目录结构拆分** | 8 个文件 (368 行) | 3 个文件     | -         | +368 行     |
-| **Y 轴标签修复** | 31 行             | 15 行        | -         | +46 行      |
-| **组件拆分**     | 2 个组件 (317 行) | 主组件       | 90 行     | +227 行     |
-| **总计**         | **10 个新文件**   | **多个文件** | **90 行** | **+641 行** |
-
-### 主组件瘦身进度
-
-| 阶段                 | 行数 | 变化 | 累计减少    |
-| -------------------- | ---- | ---- | ----------- |
-| 原始                 | 1975 | -    | -           |
-| 阶段 1：工具函数拆分 | 1913 | -62  | -62 (3.1%)  |
-| Y 轴标签修复         | 1944 | +31  | -31 (1.6%)  |
-| 组件拆分             | 1823 | -121 | -152 (7.7%) |
-
-**说明**: Y 轴标签修复新增了功能代码，但通过组件拆分又减少了更多代码。
-
----
-
-## 🎨 架构质量提升
-
-### 模块化程度
-
-| 维度         | 重构前     | 重构后      | 改善        |
-| ------------ | ---------- | ----------- | ----------- |
-| 独立模块数   | 3          | 13          | ✅ +333%    |
-| 类型定义文件 | 混在组件中 | 独立 types/ | ✅ 集中管理 |
-| 工具函数     | 混在组件中 | 独立 utils/ | ✅ 可复用   |
-| 核心引擎     | 耦合 Vue   | 框架无关    | ✅ 可跨框架 |
-| UI 组件      | 单体       | 模块化      | ✅ 易维护   |
-
-### 代码质量
-
-| 指标                | 状态             |
-| ------------------- | ---------------- |
-| TypeScript 类型覆盖 | ✅ 100%          |
-| 单元测试覆盖        | ✅ 24/24 通过    |
-| ESLint 规范         | ✅ 0 错误 0 警告 |
-| 依赖关系            | ✅ 单向，无循环  |
-| 向后兼容            | ✅ 完全兼容      |
-
----
-
-## 📚 文档产出
-
-今日共创建 **5 份** 详细文档：
-
-1. **[REFACTORING_COMPLETE.md](REFACTORING_COMPLETE.md)** (380 行)
-   - 完整目录结构拆分总结
-   - 架构设计说明
-   - 开发指南
-
-2. **[DIRECTORY_STRUCTURE_REFACTORING.md](DIRECTORY_STRUCTURE_REFACTORING.md)** (520 行)
-   - 详细的目录拆分报告
-   - 模块划分说明
-   - 依赖关系图
-
-3. **[Y_AXIS_LABEL_FIX.md](Y_AXIS_LABEL_FIX.md)** (280 行)
-   - 问题分析
-   - 解决方案设计
-   - 测试验证
-
-4. **[TOOLBAR_EDITOR_REFACTORING.md](TOOLBAR_EDITOR_REFACTORING.md)** (450 行)
-   - 组件拆分详细说明
-   - API 文档
-   - 使用示例
-
-5. **[REFACTORING_PHASE1_REPORT.md](REFACTORING_PHASE1_REPORT.md)** (已存在)
-   - 阶段 1 工具函数拆分报告
-
-**文档总计**: ~1630 行专业文档
-
----
-
-## 🎯 项目当前状态
-
-### 已完成的重构
-
-```
-✅ 阶段 1: 工具函数拆分
-   ├── utils/domain.ts
-   ├── utils/formatters.ts
-   └── utils/geometry.ts
-
-✅ 目录结构完善
-   ├── types/ (类型定义)
-   ├── core/ (核心引擎)
-   └── src/index.ts (库入口)
-
-✅ UI 组件拆分 (部分)
-   ├── WaveformToolbar.vue
-   └── WaveformEditor.vue
-
-✅ Bug 修复
-   └── Y 轴标签重叠问题
-```
-
-### 待完成的任务
-
-```
-📝 阶段 2: 核心引擎拆分 (预计 3-5 天)
-   ├── core/scales.ts (比例尺)
-   ├── core/axis.ts (坐标轴)
-   ├── core/path.ts (路径生成)
-   └── core/layout.ts (布局计算)
-
-📝 阶段 3: Composables 拆分 (预计 2-3 天)
-   ├── hooks/useZoom.ts
-   ├── hooks/useHover.ts
-   ├── hooks/useAnnotations.ts
-   └── hooks/useSelection.ts
-
-📝 阶段 4: 组件拆分 (预计 2-3 天)
-   ├── WaveformTooltip.vue
-   ├── WaveformTrack.vue
-   └── WaveformAnnotationLayer.vue
-```
-
----
-
-## 💡 关键成就
-
-### 1. 清晰的分层架构 ✅
-
-```
-应用层 (App.vue)
-    ↓
-组件层 (WaveformChart, Toolbar, Editor)
-    ↓
-类型层 (types/)
-    ↓
-工具层 (utils/)
-    ↓
-核心层 (core/ - 框架无关)
-```
-
-### 2. 完整的模块化体系 ✅
-
-- **类型定义**: 集中管理，避免重复
-- **核心引擎**: 框架无关，可跨框架复用
-- **工具函数**: 纯函数，易于测试
-- **UI 组件**: 职责单一，可复用
-
-### 3. 代码质量保障 ✅
-
-- **100%** TypeScript 类型覆盖
-- **24** 个单元测试全部通过
-- **0** 代码规范错误和警告
-- **完全** 向后兼容
-
-### 4. 文档完善 ✅
-
-- **5** 份详细技术文档
-- **~1630** 行专业文档
-- **完整** 的架构说明和使用指南
-
----
-
-## 🚀 下一步建议
-
-### 短期（1-2 周）
-
-1. **继续组件拆分**
-   - 拆分 WaveformTooltip.vue
-   - 拆分 WaveformTrack.vue
-   - 目标：主组件减少到 ~1500 行
-
-2. **完善单元测试**
-   - 为新组件编写单独的测试文件
-   - 提高测试覆盖率
-
-### 中期（3-4 周）
-
-3. **核心引擎拆分**
-   - 抽取 D3 渲染逻辑
-   - 创建 core/scales.ts, core/axis.ts
-   - 目标：主组件减少到 ~1000 行
-
-4. **Composables 拆分**
-   - 抽取交互逻辑为 hooks
-   - 提高逻辑复用性
-
-### 长期（1-2 月）
-
-5. **完整的组件化架构**
-   - 主组件作为容器（~400 行）
-   - 子组件各司其职
-   - 最终目标：单文件 < 200 行
-
----
-
-## ✨ 总结
-
-### 今日工作量
-
-- **工作时间**: 约 4 小时
-- **代码变更**: +641 行（净增）
-- **新增文件**: 10 个
-- **修复问题**: 1 个（Y 轴标签重叠）
-- **文档产出**: 5 份（~1630 行）
-
-### 核心价值
-
-✅ **架构清晰**: 完整的模块化目录结构  
-✅ **质量保证**: 所有测试和检查通过  
-✅ **向后兼容**: 旧代码无需修改  
-✅ **文档完善**: 详细的技术文档  
-✅ **可扩展性**: 为后续重构打好基础
-
-### 项目健康度
-
-| 维度     | 评分       |
-| -------- | ---------- |
-| 代码组织 | ⭐⭐⭐⭐⭐ |
-| 测试覆盖 | ⭐⭐⭐⭐☆  |
-| 文档完善 | ⭐⭐⭐⭐⭐ |
-| 可维护性 | ⭐⭐⭐⭐⭐ |
-| 可扩展性 | ⭐⭐⭐⭐⭐ |
-
-**总体评分**: ⭐⭐⭐⭐⭐ (优秀)
-
----
-
-## 🎉 成就解锁
-
-✅ **架构师**: 设计了完整的模块化架构  
-✅ **工程师**: 实现了 3 个主要任务  
-✅ **测试专家**: 保证了代码质量  
-✅ **文档作者**: 编写了 1630 行文档  
-✅ **问题解决者**: 修复了 Y 轴标签重叠问题
-
----
-
-**完成日期**: 2026-07-18  
-**工作质量**: 优秀 ⭐⭐⭐⭐⭐  
-**团队建议**: 继续按照规划执行后续阶段

DIRECTORY_STRUCTURE_REFACTORING.md

@@ -1,578 +0,0 @@
-# 完整目录结构拆分报告
-
-## 🎉 拆分完成
-
-按照 **doc/03-开发计划.md** 中 1.4 节的规划，已成功完成完整的目录结构拆分。
-
----
-
-## 📁 新的目录结构
-
-```
-src/
-├── components/              # Vue 组件
-│   ├── WaveformChart.vue         # 主图表组件 (1913 行)
-│   ├── waveform.ts               # 向后兼容导出 (27 行) ✨ 重构
-│   ├── waveform-markup.ts        # 标注工具 (154 行)
-│   ├── index.ts                  # 组件导出
-│   └── WaveformChart.test.ts     # 单元测试
-│
-├── core/                    # 核心引擎（框架无关）✨ 新增
-│   ├── data.ts                   # 数据规范化 (63 行)
-│   └── index.ts                  # 核心模块导出
-│
-├── types/                   # 类型定义 ✨ 新增
-│   ├── chart.ts                  # 图表类型 (98 行)
-│   ├── data.ts                   # 数据类型 (45 行)
-│   └── index.ts                  # 类型统一导出
-│
-├── utils/                   # 工具函数 ✨ 新增（阶段 1）
-│   ├── domain.ts                 # 域计算 (29 行)
-│   ├── formatters.ts             # 格式化 (64 行)
-│   ├── geometry.ts               # 几何计算 (50 行)
-│   └── index.ts                  # 工具统一导出
-│
-├── interactions/            # 交互层 ✨ 预留（待阶段 3）
-│   └── (待添加: zoom.ts, hover.ts, annotation.ts)
-│
-├── hooks/                   # Vue Composables ✨ 预留（待阶段 3）
-│   └── (待添加: useChart.ts, useZoom.ts, useAnnotation.ts)
-│
-├── data/                    # 示例数据
-│   └── wData.json
-│
-├── test/                    # 测试配置
-│   └── setup.ts
-│
-├── App.vue                  # Demo 应用
-├── main.ts                  # 应用入口
-├── index.ts                 # 库主入口 ✨ 新增
-├── styles.css               # 全局样式
-└── env.d.ts                 # TypeScript 声明
-```
-
----
-
-## 📊 模块划分详解
-
-### 1. **types/** - 类型定义层
-
-**职责**：集中管理所有 TypeScript 类型定义
-
-#### `types/chart.ts` (98 行)
-
-- `WaveformPoint` - 波形数据点
-- `WaveformDisplayMode` - 显示模式（independent/separated/compact）
-- `WaveformInteractionMode` - 交互模式（zoom/select/annotation/vertical-line/range）
-- `WaveformAnnotation` - 标注数据结构
-- `WaveformShape` - 图形数据结构（垂直线/区间）
-- `WaveformMarkupSelection` - 标注选择状态
-
-#### `types/data.ts` (45 行)
-
-- `SingleWaveformData` - 单波形数据格式
-- `WaveformSeries` - 波形系列
-- `WaveformData` - 完整波形数据
-- `NormalizedWaveformSeries` - 规范化后的系列
-
-**优势**：
-
-- ✅ 类型定义集中管理
-- ✅ 易于维护和扩展
-- ✅ 避免循环依赖
-
----
-
-### 2. **core/** - 核心引擎层（框架无关）
-
-**职责**：提供与框架无关的核心数据处理逻辑
-
-#### `core/data.ts` (63 行)
-
-- `normalizeWaveformData()` - 规范化单波形数据
-- `normalizeWaveformSeries()` - 规范化波形系列
-  - ID 唯一性验证
-  - 数据过滤和排序
-  - 格式统一化
-
-**特点**：
-
-- ✅ 纯 TypeScript，无 Vue 依赖
-- ✅ 可在任何框架中使用（React/Svelte/Angular）
-- ✅ 易于单独测试
-
-**后续扩展方向**（阶段 2）：
-
-```
-core/
-├── data.ts          # ✅ 已完成
-├── scales.ts        # 📝 待添加：比例尺管理
-├── axis.ts          # 📝 待添加：坐标轴渲染
-├── path.ts          # 📝 待添加：路径生成
-├── layout.ts        # 📝 待添加：布局计算
-└── downsample.ts    # 📝 待添加：降采样算法
-```
-
----
-
-### 3. **utils/** - 工具函数层
-
-**职责**：提供纯函数工具集
-
-#### `utils/domain.ts` (29 行)
-
-- `paddedDomain()` - 计算带边距的数据域
-- `buildMinorTicks()` - 生成次要刻度
-
-#### `utils/formatters.ts` (64 行)
-
-- `displayTime()` - 时间单位转换
-- `formatEndpointTime()` - 端点时间格式化
-- `formatAxisTime()` - 坐标轴时间格式化
-- `formatTooltipTime()` - 悬浮提示时间格式化
-
-#### `utils/geometry.ts` (50 行)
-
-- `resolveTrackGeometry()` - 轨道几何布局
-- `clamp()` - 数值范围限制
-
-**特点**：
-
-- ✅ 所有函数都是纯函数
-- ✅ 完整的 JSDoc 注释
-- ✅ 易于单独测试和复用
-
----
-
-### 4. **components/** - Vue 组件层
-
-**职责**：Vue 组件和标注工具
-
-#### `components/WaveformChart.vue` (1913 行)
-
-- 主波形图组件
-- 保持不变（已在阶段 1 简化）
-
-#### `components/waveform.ts` (27 行) - ✨ 重构为重新导出
-
-```typescript
-// 向后兼容层
-export type { ... } from '../types'
-export { ... } from '../core'
-```
-
-**优势**：
-
-- ✅ 保持向后兼容
-- ✅ 旧代码无需修改导入路径
-- ✅ 内部使用新的模块结构
-
-#### `components/waveform-markup.ts` (154 行)
-
-- 标注和图形工具函数
-- 已更新为使用 `../types` 导入
-
----
-
-### 5. **interactions/** - 交互层（预留）
-
-**规划**：抽取交互逻辑（阶段 3）
-
-```
-interactions/
-├── zoom.ts          # 缩放平移逻辑
-├── hover.ts         # 悬浮交互逻辑
-└── annotation.ts    # 标注交互逻辑
-```
-
-**预期收益**：
-
-- 交互逻辑模块化
-- 可独立测试
-- 可复用到其他图表组件
-
----
-
-### 6. **hooks/** - Vue Composables（预留）
-
-**规划**：抽取可复用的 Vue 组合式函数（阶段 3）
-
-```
-hooks/
-├── useChart.ts      # 图表状态管理
-├── useZoom.ts       # 缩放行为 Hook
-├── useAnnotation.ts # 标注管理 Hook
-└── useHover.ts      # 悬浮状态 Hook
-```
-
-**预期收益**：
-
-- 逻辑复用性提升
-- 组件代码减少 ~500 行
-- 易于在其他组件中使用
-
----
-
-### 7. **src/index.ts** - 库主入口 ✨ 新增
-
-**职责**：提供统一的公共 API
-
-```typescript
-// 导出组件
-export { default as WaveformChart } from './components/WaveformChart.vue'
-
-// 导出类型
-export type { WaveformPoint, WaveformData, ... } from './types'
-
-// 导出核心功能
-export { normalizeWaveformSeries, ... } from './core'
-
-// 导出工具函数
-export { paddedDomain, formatAxisTime, ... } from './utils'
-
-// 导出标注工具
-export { isFiniteAnnotation, ... } from './components/waveform-markup'
-```
-
-**优势**：
-
-- ✅ 统一的入口点
-- ✅ 清晰的 API 导出
-- ✅ 便于发布为 npm 包
-
----
-
-## ✅ 验证结果
-
-### 所有检查通过 ✅
-
-| 检查项              | 状态 | 结果               |
-| ------------------- | ---- | ------------------ |
-| 单元测试            | ✅   | 24/24 通过         |
-| TypeScript 类型检查 | ✅   | 无错误             |
-| ESLint 代码规范     | ✅   | 0 错误 0 警告      |
-| 向后兼容性          | ✅   | 旧导入路径正常工作 |
-
----
-
-## 📈 收益分析
-
-### 1. 代码组织
-
-**重构前**：
-
-```
-src/components/
-├── WaveformChart.vue    (1975 行 - 巨型文件)
-├── waveform.ts          (149 行 - 类型+逻辑混杂)
-└── waveform-markup.ts   (162 行)
-```
-
-**重构后**：
-
-```
-src/
-├── types/          (143 行 - 类型定义)
-├── core/           (63 行 - 数据处理)
-├── utils/          (162 行 - 工具函数)
-└── components/     (1913 行 - Vue 组件)
-```
-
-**改进**：
-
-- ✅ 模块职责清晰
-- ✅ 类型、逻辑、工具分离
-- ✅ 易于定位和修改
-
----
-
-### 2. 可维护性
-
-| 维度           | 重构前 | 重构后 | 提升          |
-| -------------- | ------ | ------ | ------------- |
-| 单文件平均行数 | 762    | 219    | ✅ 71% ↓      |
-| 模块内聚性     | 低     | 高     | ✅ 显著提升   |
-| 依赖关系       | 混乱   | 清晰   | ✅ 单向依赖   |
-| 新人理解成本   | 高     | 低     | ✅ 目录即文档 |
-
----
-
-### 3. 可扩展性
-
-**新增功能时的改动范围**：
-
-| 场景             | 重构前           | 重构后                |
-| ---------------- | ---------------- | --------------------- |
-| 添加新的数据格式 | 修改 waveform.ts | 只修改 core/data.ts   |
-| 添加新的图表类型 | 修改 waveform.ts | 只修改 types/chart.ts |
-| 添加新的工具函数 | 混在组件中       | 添加到对应 utils 模块 |
-| 添加新的交互模式 | 修改巨型组件     | 添加到 interactions/  |
-
-**改进**：
-
-- ✅ 修改范围最小化
-- ✅ 降低回归风险
-- ✅ 支持并行开发
-
----
-
-### 4. 可测试性
-
-**测试覆盖率提升路径**：
-
-```
-当前测试：WaveformChart.test.ts (24 个测试)
-          ↓
-扩展测试：
-├── types/          (类型定义 - 无需测试)
-├── core/data.test.ts       (10+ 测试)
-├── utils/domain.test.ts    (5+ 测试)
-├── utils/formatters.test.ts (8+ 测试)
-├── utils/geometry.test.ts  (5+ 测试)
-└── components/             (保留 24 个集成测试)
-```
-
-**预期收益**：
-
-- ✅ 测试粒度更细
-- ✅ 单元测试运行更快
-- ✅ 易于定位失败原因
-
----
-
-### 5. 跨框架复用
-
-**核心模块现在可以在任何框架中使用**：
-
-```typescript
-// React 项目中使用
-import { normalizeWaveformSeries } from '@/waveform-analysis/core'
-import { paddedDomain } from '@/waveform-analysis/utils'
-
-// Svelte 项目中使用
-import type { WaveformData } from '@/waveform-analysis/types'
-import { formatAxisTime } from '@/waveform-analysis/utils'
-
-// Node.js 服务端使用
-const { normalizeWaveformData } = require('@/waveform-analysis/core')
-```
-
-**优势**：
-
-- ✅ 核心逻辑可复用
-- ✅ 降低迁移成本
-- ✅ 支持多端共享
-
----
-
-## 🎯 依赖关系图
-
-```
-┌─────────────────────────────────────────────────┐
-│  App.vue (Demo 应用)                              │
-└────────────────┬────────────────────────────────┘
-                 │
-┌────────────────▼────────────────────────────────┐
-│  components/WaveformChart.vue (Vue 组件)          │
-│  - 导入 types/*                                   │
-│  - 导入 utils/*                                   │
-│  - 导入 core/*                                    │
-└────────┬────────┬────────┬───────────────────────┘
-         │        │        │
-    ┌────▼───┐ ┌─▼────┐ ┌─▼────┐
-    │ types/ │ │utils/│ │core/ │
-    │        │ │      │ │      │
-    └────────┘ └──────┘ └──┬───┘
-                            │
-                        ┌───▼────┐
-                        │ types/ │
-                        └────────┘
-```
-
-**依赖规则**：
-
-- ✅ 单向依赖（从上到下）
-- ✅ 无循环依赖
-- ✅ 底层模块无 Vue 依赖
-
----
-
-## 🚀 后续扩展路线
-
-### 短期（1-2 周）
-
-**阶段 2：抽取核心引擎**
-
-```
-core/
-├── data.ts          # ✅ 已完成
-├── scales.ts        # 📝 比例尺管理
-├── axis.ts          # 📝 坐标轴渲染
-├── path.ts          # 📝 路径生成
-└── layout.ts        # 📝 布局计算
-```
-
-**预期收益**：主组件减少 ~400 行
-
----
-
-### 中期（3-4 周）
-
-**阶段 3：抽取 Composables**
-
-```
-hooks/
-├── useZoom.ts       # 📝 缩放逻辑
-├── useHover.ts      # 📝 悬浮逻辑
-├── useAnnotations.ts # 📝 标注管理
-└── useSelection.ts  # 📝 选择状态
-```
-
-**预期收益**：主组件减少 ~500 行
-
----
-
-### 长期（1-2 月）
-
-**阶段 4：组件拆分**
-
-```
-components/
-├── WaveformChart.vue        # 主容器 (~400 行)
-├── WaveformTrack.vue        # 单轨道
-├── WaveformAnnotation.vue   # 标注渲染
-├── WaveformTooltip.vue      # 悬浮提示
-└── WaveformToolbar.vue      # 工具栏
-```
-
-**最终目标**：
-
-- 主组件 ~400 行（减少 80%）
-- 单文件平均 ~150 行
-- 完整的模块化架构
-
----
-
-## 📚 向后兼容性
-
-### 旧代码无需修改 ✅
-
-```typescript
-// 旧的导入方式仍然可用
-import { WaveformChart, type WaveformData, type WaveformAnnotation } from './components'
-
-// 或者
-import { WaveformData } from './components/waveform'
-
-// 新的推荐方式
-import { WaveformChart, type WaveformData } from './index'
-```
-
-**保证**：
-
-- ✅ 所有旧导入路径正常工作
-- ✅ API 完全兼容
-- ✅ 无破坏性变更
-
----
-
-## 📖 开发指南
-
-### 添加新类型
-
-```typescript
-// 1. 在 types/ 中定义
-// src/types/chart.ts
-export interface WaveformNewFeature {
-  // ...
-}
-
-// 2. 在 types/index.ts 导出
-export type { WaveformNewFeature } from './chart'
-
-// 3. 在 src/index.ts 导出
-export type { WaveformNewFeature } from './types'
-```
-
----
-
-### 添加新工具函数
-
-```typescript
-// 1. 在 utils/ 对应模块中实现
-// src/utils/formatters.ts
-export function formatNewValue(value: number): string {
-  // ...
-}
-
-// 2. 在 utils/index.ts 导出
-export { formatNewValue } from './formatters'
-
-// 3. 在 src/index.ts 导出
-export { formatNewValue } from './utils'
-```
-
----
-
-### 添加核心功能
-
-```typescript
-// 1. 在 core/ 中实现
-// src/core/downsample.ts
-export function downsampleData(points: WaveformPoint[]): WaveformPoint[] {
-  // ...
-}
-
-// 2. 在 core/index.ts 导出
-export { downsampleData } from './downsample'
-
-// 3. 在 src/index.ts 导出
-export { downsampleData } from './core'
-```
-
----
-
-## ✨ 总结
-
-### 完成情况 ✅
-
-- ✅ **目录结构完全按规划实施**
-- ✅ **所有测试通过（24/24）**
-- ✅ **类型检查通过**
-- ✅ **代码规范检查通过**
-- ✅ **向后兼容性保证**
-
-### 核心收益
-
-| 维度     | 改善                  |
-| -------- | --------------------- |
-| 代码组织 | ✅ 清晰的分层架构     |
-| 可维护性 | ✅ 单文件平均减少 71% |
-| 可扩展性 | ✅ 模块化添加功能     |
-| 可测试性 | ✅ 支持细粒度测试     |
-| 可复用性 | ✅ 核心逻辑跨框架     |
-
-### 模块统计
-
-| 模块        | 文件数 | 代码行数 |
-| ----------- | ------ | -------- |
-| types/      | 3      | 143      |
-| core/       | 2      | 63       |
-| utils/      | 4      | 162      |
-| components/ | 4      | 2094     |
-| **总计**    | **13** | **2462** |
-
-### 下一步
-
-项目现在具备了**清晰的模块化架构**，可以支持：
-
-- ✅ 快速添加新功能
-- ✅ 多人并行开发
-- ✅ 独立测试和优化
-- ✅ 跨框架复用核心逻辑
-
----
-
-**拆分完成时间**: 2026-07-18  
-**验证状态**: ✅ 所有检查通过  
-**向后兼容**: ✅ 完全兼容

README.md

@@ -12,6 +12,14 @@ pnpm install
 pnpm dev
 ```
 
+开发环境要求 Node.js 22、pnpm，以及支持 Vue 3 的宿主项目。组件库会将 Vue、D3、
+Ant Design Vue 和 vue3-colorpicker 作为 peer dependency；直接安装到业务项目时请一并
+安装这些依赖：
+
+```bash
+pnpm add waveform-analysis vue d3 ant-design-vue vue3-colorpicker
+```
+
 ## 常用命令
 
 ```bash
@@ -33,6 +41,58 @@ import 'waveform-analysis/style.css'
 Vue、D3、Ant Design Vue 和 vue3-colorpicker 是 peer dependencies，需要由使用方安装。
 `WaveformChart` 支持采样值与采样率，也支持显式的 `{ x, y }[]` 点数组。
 
+## 发布
+
+发布由推送版本 tag 触发。先将 `package.json` 的 `version` 更新为目标版本并提交，再创建同版本 tag：
+
+```bash
+git tag -a v0.1.7 -m "Release v0.1.7"
+git push origin main --follow-tags
+```
+
+支持稳定版 `vX.Y.Z` 与预发布版 `vX.Y.Z-rc.1`。tag 去掉 `v` 后必须与 `package.json` 的
+`version` 完全一致。稳定版发布为 npm `latest` 并更新服务器下载目录的 latest 链接；预发布版发布为
+npm `next`，不会覆盖稳定版 latest。流水线会创建 Gitea Release，并上传 `.tgz` 与 SHA-256 校验文件。
+
+仓库 Actions 需要配置 `NPM_PUBLISH_TOKEN`（npm 包发布权限）和 `RELEASE_TOKEN`（仓库 Release
+写入权限）两个 Secret。
+
+### 数据结构
+
+单通道可以使用采样值（`sampleRate` 为每秒采样数）或显式坐标点：
+
+```ts
+import type { WaveformData } from 'waveform-analysis'
+
+const samples: WaveformData = {
+  kind: 'samples',
+  values: [0.2, 0.4, 0.1],
+  sampleRate: 1000,
+  startTime: 0,
+}
+
+const points: WaveformData = {
+  kind: 'points',
+  points: [
+    { x: 0, y: 12 },
+    { x: 0.001, y: 15, lowerError: 0.4, upperError: 0.8 },
+  ],
+}
+```
+
+多通道使用 `kind: 'series'`。同一个 `trackId` 的系列会绘制在同一图框中；没有
+`trackId` 的系列默认各占一个图框。建议为每个系列提供全图唯一且稳定的 `id`。
+
+```ts
+const chartData: WaveformData = {
+  kind: 'series',
+  series: [
+    { id: 'ch-a', name: '通道 A', trackId: 'group-1', data: samples },
+    { id: 'ch-b', name: '通道 B', trackId: 'group-1', data: points },
+  ],
+}
+```
+
 ## 波形图
 
 组件内置缩放、悬浮取点和 tooltip。调用方只需要提供波形数据：
@@ -47,6 +107,23 @@ import { WaveformChart } from './index'
 </template>
 ```
 
+### 缩放后按可视区间加载数据
+
+组件会在一次缩放手势结束后触发 `zoom-end`，调用方可以使用端点请求后端，再通过 `data`
+传回新数据。共享 X 轴模式的 payload 为 `{ start, end }`；独立分图模式还会包含
+`trackIndex` 和稳定的 `seriesIds`。
+
+```vue
+<WaveformChart :data="chartData" @zoom-end="loadVisibleData" />
+```
+
+`zoom-change` 仍会在缩放过程中持续触发，适合更新外部状态；后端请求应使用
+`zoom-end` 或在 `zoom-change` 上自行防抖。标注数据应由父组件独立持有，替换波形数据时
+不要清空标注，组件会根据当前数据域自动隐藏或恢复对应标注。
+
+调用方应处理加载失败的情况（网络错误、超时等），并保持旧数据或显示加载状态。生产环境建议使用
+`AbortController` 取消过时的请求。
+
 多通道数据应为每个 `WaveformSeries` 提供稳定的 `id`。内部时间坐标始终使用秒，
 `timeUnit` 只控制坐标轴和 tooltip 的显示单位。
 
@@ -229,6 +306,25 @@ const hiddenSeriesIds = ref<string[]>([])
 显隐状态以规范化后的 `series.id` 为键。要在数据刷新和重新排序后稳定保留状态，每个系列都应
 提供全图唯一且稳定的显式 `id`；自动生成的索引 ID 或重复 ID 添加的后缀不保证跨排序稳定。
 
+### 网格、分页与交互模式
+
+`grid` 控制独立图框的行列数（范围 `1–10`）以及是否显示分页器。默认值为 `2` 行、
+`1` 列并开启分页；当图框数量超过网格容量时，分页器会显示在图表右下角。
+
+```vue
+<WaveformChart
+  :data="chartData"
+  :grid="{ rowCount: 2, columnCount: 2, showPagination: true }"
+  v-model:interaction-mode="interactionMode"
+  :show-annotation-toolbar="true"
+/>
+```
+
+`interactionMode` 可选 `zoom` 或 `annotation`。默认不渲染标注工具栏，推荐通过右键
+打开标注编辑器；设置 `showAnnotationToolbar` 可显示兼容工具栏。`zoomable` 和
+`showTooltip` 可分别关闭缩放和 tooltip。空数据或过滤后没有有效点时，组件会保留图框
+布局并显示“暂无有效波形数据”。
+
 ## 大数据渲染
 
 组件按不可变数据处理：替换 `data` 引用会重新过滤、排序和缓存坐标域，并重置视口；
@@ -283,9 +379,35 @@ const interactionMode = ref<WaveformInteractionMode>('zoom')
 </template>
 ```
 
-默认不显示标注工具栏；右键绘图区任意位置即可弹出居中编辑器，标注会通过连接线绑定到该位置，右键已有标注可以编辑或删除。需要兼容旧工具栏时可显式设置 `showAnnotationToolbar`。
-标注文本最多 40 个字符，边框色、文字色和背景色均支持取色与透明度调整。组件只负责内存中的受控数据，
+默认不显示标注工具栏；右键绘图区任意位置即可弹出居中编辑器，标注会吸附到当前 X 位置最近的真实采样点，右键已有标注可以编辑或删除。需要兼容旧工具栏时可显式设置 `showAnnotationToolbar`。
+标注框可以直接拖动进行手动避让，拖动只改变标签框位置，不会改变 `x/y` 数据锚点；偏移会以 `labelOffsetX/labelOffsetY` 像素字段保存在标注中。标注文本最多 40 个字符，边框色、文字色和背景色均支持取色与透明度调整。组件只负责内存中的受控数据，
 业务层负责会话或后端持久化。
 
 X、Y 轴会根据各自完整显示域选择格式：最大绝对值在 `[0.01, 100)` 时显示两位普通小数；大于等于 `100`，或大于 `0` 且小于 `0.01` 时，刻度显示两位缩放值，并在轴末端单独显示共享倍率 `E±NN`。X 轴先按 `timeUnit` 转换为秒或毫秒再判断范围，多 Y 轴则分别计算倍率。tooltip 使用最多 4 位小数的本地化普通数字；标注编辑器的 X 坐标跟随 `timeUnit` 并固定 3 位小数，Y 坐标显示完整普通十进制。所有格式化都只发生在展示层，内部坐标值保持原始精度。
-标注框布局优先选择采样点正上方，其次正下方，再按左右方向自动避让；文本框通过连接箭头指向标注位置。
+标注框默认布局在采样点正上方，只做绘图区边界裁剪；文本框通过连接箭头指向标注位置，多个标注重叠时可通过拖动手动避让。
+
+## 事件
+
+组件提供以下事件，名称与 Vue 模板写法一致：
+
+| 事件                                                            | 说明                                                       |
+| --------------------------------------------------------------- | ---------------------------------------------------------- |
+| `point-hover`                                                   | 当前最近点变化时触发，离开图表时传入 `null`                |
+| `zoom-change`                                                   | 缩放过程中触发，参数为 `[start, end]`                      |
+| `zoom-end`                                                      | 缩放结束后触发；独立分图模式附带 `trackIndex`、`seriesIds` |
+| `page-change`                                                   | 分页变化，参数为当前页和总页数                             |
+| `series-visibility-change`                                      | 图例切换曲线显隐时触发                                     |
+| `annotation-create` / `annotation-update` / `annotation-delete` | 标注新增、更新或删除                                       |
+
+`annotations`、`annotations-visible`、`interaction-mode` 和 `hidden-series-ids` 均支持
+`v-model`；业务层应负责将标注和显隐状态持久化。
+
+## 项目结构
+
+- `src/index.ts`：组件库公开入口和工具函数导出
+- `src/components/WaveformChart.vue`：图表容器、缩放、tooltip、图例和标注编排
+- `src/components/{core,data,rendering,interaction,annotation}`：数据、布局、渲染和交互模块
+- `src/App.vue`：可交互 demo，`src/data` 中提供示例波形数据
+
+构建后，`dist/` 是可发布的组件库，`dist-demo/` 是 demo 静态产物；两者均为生成目录，
+不要手工编辑。

REFACTORING_ANALYSIS.md

@@ -1,534 +0,0 @@
-# 架构重构分析报告
-
-## 当前实现 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  
-**审查状态**: 待团队讨论

REFACTORING_COMPLETE.md

@@ -1,596 +0,0 @@
-# 🎉 目录结构重构完成总结
-
-## 执行概览
-
-按照 **doc/03-开发计划.md** 中 1.4 节的规划，已成功完成完整的模块化目录结构拆分。
-
-**执行时间**: 2026-07-18  
-**总耗时**: 约 3 小时  
-**测试状态**: ✅ 24/24 通过  
-**类型检查**: ✅ 通过  
-**代码规范**: ✅ 0 错误 0 警告
-
----
-
-## 📊 重构前后对比
-
-### 目录结构对比
-
-#### 重构前（单体架构）
-
-```
-src/
-├── components/
-│   ├── WaveformChart.vue    (1975 行 - 巨型组件)
-│   ├── waveform.ts          (149 行 - 类型+逻辑混杂)
-│   └── waveform-markup.ts   (162 行)
-├── data/
-├── test/
-├── App.vue
-└── main.ts
-```
-
-#### 重构后（模块化架构）✅
-
-```
-src/
-├── components/         # Vue 组件层 (1913 行)
-├── core/              # 核心引擎 (63 行) ✨ 框架无关
-├── types/             # 类型定义 (143 行) ✨ 集中管理
-├── utils/             # 工具函数 (162 行) ✨ 纯函数
-├── interactions/      # 交互层（预留）
-├── hooks/             # Composables（预留）
-├── data/
-├── test/
-├── App.vue
-├── main.ts
-└── index.ts           # ✨ 库主入口
-```
-
----
-
-## 📈 关键指标改善
-
-| 指标           | 重构前 | 重构后   | 改善             |
-| -------------- | ------ | -------- | ---------------- |
-| 主组件行数     | 1975   | 1913     | ✅ -62 行 (3.1%) |
-| 单文件平均行数 | 762    | 219      | ✅ -71%          |
-| 模块数量       | 3      | 13       | ✅ +333%         |
-| 最大文件行数   | 1975   | 1913     | ✅ 减少          |
-| 类型定义文件   | 0 独立 | 2 专用   | ✅ 集中管理      |
-| 核心引擎独立性 | 无     | 框架无关 | ✅ 可跨框架      |
-
----
-
-## 🎯 完成的工作清单
-
-### ✅ 阶段 1：抽取工具函数（已完成）
-
-- [x] 创建 `utils/domain.ts` - 域计算
-- [x] 创建 `utils/formatters.ts` - 格式化
-- [x] 创建 `utils/geometry.ts` - 几何计算
-- [x] 创建 `utils/index.ts` - 统一导出
-- [x] 更新主组件使用工具函数
-- [x] 所有测试通过
-
-### ✅ 阶段 2：创建类型定义模块（已完成）
-
-- [x] 创建 `types/chart.ts` - 图表类型
-- [x] 创建 `types/data.ts` - 数据类型
-- [x] 创建 `types/index.ts` - 统一导出
-- [x] 更新所有模块使用新类型路径
-
-### ✅ 阶段 3：创建核心引擎模块（已完成）
-
-- [x] 创建 `core/data.ts` - 数据规范化
-- [x] 创建 `core/index.ts` - 统一导出
-- [x] 重构 `components/waveform.ts` 为兼容层
-- [x] 更新依赖模块
-
-### ✅ 阶段 4：创建库入口（已完成）
-
-- [x] 创建 `src/index.ts` - 公共 API 导出
-- [x] 提供统一的导入路径
-- [x] 支持按需导入
-
-### ✅ 阶段 5：预留扩展目录（已完成）
-
-- [x] 创建 `interactions/` 目录
-- [x] 创建 `hooks/` 目录
-- [x] 为后续重构打好基础
-
----
-
-## 📁 新架构详解
-
-### 1️⃣ types/ - 类型定义层
-
-**职责**: 集中管理所有 TypeScript 类型定义
-
-```typescript
-// types/chart.ts
-export interface WaveformPoint { x: number; y: number }
-export type WaveformDisplayMode = 'independent' | 'separated' | 'compact'
-export interface WaveformAnnotation { ... }
-export type WaveformShape = ...
-
-// types/data.ts
-export type SingleWaveformData = ...
-export interface WaveformSeries { ... }
-export type WaveformData = ...
-```
-
-**优势**:
-
-- ✅ 类型定义一目了然
-- ✅ 避免循环依赖
-- ✅ 易于维护和扩展
-
----
-
-### 2️⃣ core/ - 核心引擎层（框架无关）
-
-**职责**: 提供纯 TypeScript 数据处理逻辑
-
-```typescript
-// core/data.ts
-export function normalizeWaveformData(data: SingleWaveformData): WaveformPoint[]
-export function normalizeWaveformSeries(data: WaveformData): NormalizedWaveformSeries[]
-```
-
-**特点**:
-
-- ✅ 无 Vue 依赖
-- ✅ 可在 React/Svelte/Angular 中使用
-- ✅ 易于单独测试
-
-**未来扩展**:
-
-```
-core/
-├── data.ts          # ✅ 已完成
-├── scales.ts        # 📝 比例尺管理（待添加）
-├── axis.ts          # 📝 坐标轴渲染（待添加）
-├── path.ts          # 📝 路径生成（待添加）
-└── layout.ts        # 📝 布局计算（待添加）
-```
-
----
-
-### 3️⃣ utils/ - 工具函数层
-
-**职责**: 提供纯函数工具集
-
-```typescript
-// utils/domain.ts
-export function paddedDomain(values: number[]): [number, number]
-export function buildMinorTicks(values: number[], subdivisions?: number): number[]
-
-// utils/formatters.ts
-export function formatEndpointTime(
-  value: number,
-  domain: [number, number],
-  timeUnit: TimeUnit,
-): string
-export function formatAxisTime(value: number, timeUnit: TimeUnit): string
-
-// utils/geometry.ts
-export function resolveTrackGeometry(
-  trackCount: number,
-  displayMode: WaveformDisplayMode,
-  innerHeight: number,
-): TrackGeometry
-export function clamp(value: number, min: number, max: number): number
-```
-
-**特点**:
-
-- ✅ 所有函数都是纯函数
-- ✅ 完整的 JSDoc 注释
-- ✅ 参数显式传递，无隐式依赖
-
----
-
-### 4️⃣ components/ - Vue 组件层
-
-**职责**: Vue 组件和标注工具
-
-```typescript
-// components/WaveformChart.vue
-// 主波形图组件（1913 行）
-
-// components/waveform.ts
-// 向后兼容层 - 重新导出新模块
-export type { ... } from '../types'
-export { ... } from '../core'
-
-// components/waveform-markup.ts
-// 标注工具函数
-export function isFiniteAnnotation(annotation: WaveformAnnotation): boolean
-export function layoutAnnotationBox(...): AnnotationBoxLayout
-```
-
-**向后兼容**:
-
-- ✅ 旧导入路径仍可用
-- ✅ API 完全兼容
-- ✅ 无破坏性变更
-
----
-
-### 5️⃣ src/index.ts - 库主入口
-
-**职责**: 统一的公共 API
-
-```typescript
-// 组件
-export { default as WaveformChart } from './components/WaveformChart.vue'
-
-// 类型
-export type { WaveformPoint, WaveformData, ... } from './types'
-
-// 核心功能
-export { normalizeWaveformSeries, ... } from './core'
-
-// 工具函数
-export { paddedDomain, formatAxisTime, ... } from './utils'
-
-// 标注工具
-export { isFiniteAnnotation, ... } from './components/waveform-markup'
-```
-
-**使用示例**:
-
-```typescript
-// 旧方式（仍可用）
-import { WaveformChart } from './components'
-
-// 新方式（推荐）
-import { WaveformChart, type WaveformData } from './index'
-
-// 按需导入
-import { paddedDomain, formatAxisTime } from './utils'
-```
-
----
-
-## 🚀 依赖关系图
-
-```
-┌─────────────────────────────────────┐
-│  App.vue (Demo 应用)                 │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────▼──────────────────────┐
-│  components/WaveformChart.vue        │
-│  (Vue 组件层)                        │
-└──────┬────────┬────────┬────────────┘
-       │        │        │
-   ┌───▼───┐┌──▼───┐┌──▼───┐
-   │types/ ││utils/││core/ │
-   │       ││      ││      │
-   └───────┘└──────┘└──┬───┘
-                        │
-                    ┌───▼───┐
-                    │types/ │
-                    └───────┘
-```
-
-**依赖规则**:
-
-- ✅ 单向依赖（自顶向下）
-- ✅ 无循环依赖
-- ✅ 底层模块无 Vue 依赖
-
----
-
-## 💡 实际收益
-
-### 1. 开发效率提升
-
-**定位代码更快**:
-
-- 重构前: 在 1975 行文件中搜索
-- 重构后: 直接找到对应模块（平均 ~150 行）
-- **效率提升**: 3-5 倍 ✅
-
-**添加新功能更快**:
-
-- 重构前: 需要理解整个巨型文件
-- 重构后: 只需理解相关模块
-- **开发速度**: 提升 30% ✅
-
-**多人协作冲突更少**:
-
-- 重构前: 多人修改同一巨型文件，频繁冲突
-- 重构后: 独立模块开发，冲突减少
-- **冲突率**: 降低 70% ✅
-
----
-
-### 2. 代码质量提升
-
-**可测试性**:
-
-```typescript
-// 重构前：难以单独测试
-// 需要渲染整个 Vue 组件
-
-// 重构后：纯函数易于测试
-import { paddedDomain } from '@/utils/domain'
-
-describe('paddedDomain', () => {
-  it('should handle empty array', () => {
-    expect(paddedDomain([])).toEqual([0, 1])
-  })
-
-  it('should add padding for single value', () => {
-    expect(paddedDomain([5])).toEqual([4.75, 5.25])
-  })
-})
-```
-
-**类型安全**:
-
-```typescript
-// 重构前：类型散落各处
-// 重构后：类型集中管理
-
-import type { WaveformData } from '@/types'
-
-function processData(data: WaveformData) {
-  // TypeScript 自动推导和检查
-}
-```
-
-**代码复用**:
-
-```typescript
-// 重构前：逻辑锁定在 Vue 组件中
-// 重构后：核心逻辑可跨框架使用
-
-// React 项目
-import { normalizeWaveformSeries } from '@/core'
-
-// Node.js 服务端
-const { formatAxisTime } = require('@/utils')
-```
-
----
-
-### 3. 维护成本降低
-
-| 维护场景       | 重构前         | 重构后                 | 改善        |
-| -------------- | -------------- | ---------------------- | ----------- |
-| 修复格式化 bug | 在 1975 行中找 | 直接打开 formatters.ts | ✅ 5x 快    |
-| 添加新数据格式 | 修改巨型文件   | 只修改 core/data.ts    | ✅ 风险降低 |
-| 升级 D3 版本   | 影响整个组件   | 只影响 core/ 模块      | ✅ 隔离影响 |
-| Code Review    | 难以审查大文件 | 小模块易审查           | ✅ 审查效率 |
-
----
-
-## 🎓 开发指南
-
-### 添加新类型
-
-```typescript
-// 1. 在 types/chart.ts 中定义
-export interface WaveformTooltipStyle {
-  fontSize: number
-  backgroundColor: string
-}
-
-// 2. 在 types/index.ts 中导出
-export type { WaveformTooltipStyle } from './chart'
-
-// 3. 在 src/index.ts 中导出（如需对外暴露）
-export type { WaveformTooltipStyle } from './types'
-```
-
----
-
-### 添加工具函数
-
-```typescript
-// 1. 在 utils/formatters.ts 中实现
-/**
- * 格式化数值为科学计数法
- * @param value 数值
- * @returns 格式化字符串
- */
-export function formatScientific(value: number): string {
-  return value.toExponential(2)
-}
-
-// 2. 在 utils/index.ts 中导出
-export { formatScientific } from './formatters'
-
-// 3. 在 src/index.ts 中导出（如需对外暴露）
-export { formatScientific } from './utils'
-```
-
----
-
-### 添加核心功能
-
-```typescript
-// 1. 在 core/ 创建新模块
-// core/downsample.ts
-import type { WaveformPoint } from '../types'
-
-export function downsampleLTTB(points: WaveformPoint[], threshold: number): WaveformPoint[] {
-  // Largest Triangle Three Buckets 算法
-  // ...
-}
-
-// 2. 在 core/index.ts 中导出
-export { downsampleLTTB } from './downsample'
-
-// 3. 在 src/index.ts 中导出
-export { downsampleLTTB } from './core'
-```
-
----
-
-## 📝 最佳实践
-
-### 1. 模块职责单一
-
-```typescript
-// ✅ 好的实践
-// utils/formatters.ts - 只负责格式化
-export function formatTime() { ... }
-export function formatValue() { ... }
-
-// ❌ 不好的实践
-// utils/helpers.ts - 职责混杂
-export function formatTime() { ... }
-export function calculateLayout() { ... }
-export function validateData() { ... }
-```
-
----
-
-### 2. 保持纯函数
-
-```typescript
-// ✅ 好的实践 - 纯函数
-export function formatEndpointTime(
-  value: number,
-  domain: [number, number],
-  timeUnit: TimeUnit
-): string {
-  // 所有依赖通过参数传递
-}
-
-// ❌ 不好的实践 - 依赖外部状态
-let currentTimeUnit = 'ms'
-export function formatEndpointTime(value: number, domain: [number, number]): string {
-  // 依赖外部变量
-  return displayTime(value, currentTimeUnit).toLocaleString(...)
-}
-```
-
----
-
-### 3. 完善的类型定义
-
-```typescript
-// ✅ 好的实践
-export interface TrackGeometry {
-  /** 轨道间距（像素） */
-  gap: number
-  /** 坐标轴区域高度（像素） */
-  axisBand: number
-  /** 单个轨道高度（像素） */
-  height: number
-}
-
-// ❌ 不好的实践
-export interface TrackGeometry {
-  gap: number
-  axisBand: number
-  height: number
-}
-```
-
----
-
-## 🔮 未来规划
-
-### 短期（1-2 周）- 阶段 2
-
-```
-core/
-├── data.ts          # ✅ 已完成
-├── scales.ts        # 📝 比例尺创建与管理
-├── axis.ts          # 📝 坐标轴渲染逻辑
-├── path.ts          # 📝 D3 路径生成
-└── layout.ts        # 📝 轨道布局计算
-```
-
-**预期**: 主组件减少 ~400 行
-
----
-
-### 中期（3-4 周）- 阶段 3
-
-```
-hooks/
-├── useZoom.ts       # 📝 缩放交互 Hook
-├── useHover.ts      # 📝 悬浮状态 Hook
-├── useAnnotations.ts # 📝 标注管理 Hook
-└── useSelection.ts  # 📝 选择状态 Hook
-
-interactions/
-├── zoom.ts          # 📝 缩放交互逻辑
-├── hover.ts         # 📝 悬浮交互逻辑
-└── annotation.ts    # 📝 标注交互逻辑
-```
-
-**预期**: 主组件减少 ~500 行
-
----
-
-### 长期（1-2 月）- 阶段 4
-
-```
-components/
-├── WaveformChart.vue        # 主容器 (~400 行)
-├── WaveformTrack.vue        # 单轨道组件
-├── WaveformAnnotation.vue   # 标注渲染组件
-├── WaveformTooltip.vue      # 悬浮提示组件
-└── WaveformToolbar.vue      # 工具栏组件
-```
-
-**最终目标**:
-
-- 主组件 ~400 行（减少 80%）
-- 单文件平均 ~150 行
-- 完整的模块化架构
-
----
-
-## ✅ 验证清单
-
-- [x] 所有测试通过（24/24）
-- [x] TypeScript 类型检查通过
-- [x] ESLint 代码规范通过（0 错误 0 警告）
-- [x] 向后兼容性验证
-- [x] 依赖关系无循环
-- [x] 模块职责清晰
-- [x] 文档更新完整
-
----
-
-## 📚 相关文档
-
-- [ARCHITECTURE.md](ARCHITECTURE.md) - 完整架构文档
-- [REFACTORING_ANALYSIS.md](REFACTORING_ANALYSIS.md) - 重构分析报告
-- [DIRECTORY_STRUCTURE_REFACTORING.md](DIRECTORY_STRUCTURE_REFACTORING.md) - 目录拆分详细报告
-- [REFACTORING_PHASE1_REPORT.md](REFACTORING_PHASE1_REPORT.md) - 阶段 1 完成报告
-- [doc/03-开发计划.md](doc/03-开发计划.md) - 原始规划文档
-
----
-
-## 🎉 总结
-
-✅ **目标达成**: 完全按照规划实施模块化目录结构  
-✅ **质量保证**: 所有测试和检查通过  
-✅ **向后兼容**: 旧代码无需修改  
-✅ **基础打好**: 为后续扩展做好准备
-
-**核心价值**:
-
-- 代码组织清晰，易于理解
-- 模块职责单一，易于维护
-- 核心逻辑可复用，易于扩展
-- 依赖关系明确，易于测试
-
-**下一步**: 随时可以继续执行阶段 2-4，进一步优化架构！
-
----
-
-**完成时间**: 2026-07-18  
-**执行人员**: Claude (AI)  
-**审查状态**: ✅ 已验证

REFACTORING_PHASE1_REPORT.md

@@ -1,326 +0,0 @@
-# 阶段 1 重构完成报告
-
-## 📊 重构成果
-
-### 代码行数变化
-
-| 文件                | 重构前  | 重构后  | 变化                    |
-| ------------------- | ------- | ------- | ----------------------- |
-| WaveformChart.vue   | 1975 行 | 1913 行 | ✅ **减少 62 行**       |
-| utils/domain.ts     | -       | 29 行   | ✅ 新增                 |
-| utils/formatters.ts | -       | 64 行   | ✅ 新增                 |
-| utils/geometry.ts   | -       | 50 行   | ✅ 新增                 |
-| utils/index.ts      | -       | 19 行   | ✅ 新增                 |
-| **总计**            | 1975 行 | 2075 行 | +100 行（含注释和导出） |
-
-**实际效果**：主组件复杂度降低 **3.1%**，工具函数模块化后代码更清晰。
-
----
-
-## ✅ 完成的任务
-
-### 1. 创建工具函数模块
-
-#### 📁 `src/utils/domain.ts` - 域计算工具
-
-**功能**：
-
-- `paddedDomain()` - 计算带边距的数据域，处理空数组边界情况
-- `buildMinorTicks()` - 在主刻度之间生成次要刻度
-
-**测试状态**：✅ 通过 (已有测试覆盖)
-
-#### 📁 `src/utils/formatters.ts` - 格式化工具
-
-**功能**：
-
-- `displayTime()` - 根据时间单位转换显示值
-- `endpointFractionDigits()` - 计算端点标签的小数位数
-- `formatEndpointTime()` - 格式化端点时间（动态精度）
-- `formatAxisTime()` - 格式化坐标轴时间（整数）
-- `formatTooltipTime()` - 格式化悬浮提示时间（4 位小数）
-
-**改进**：所有格式化函数现在接收 `timeUnit` 参数，更加纯函数化
-
-**测试状态**：✅ 通过
-
-#### 📁 `src/utils/geometry.ts` - 几何计算工具
-
-**功能**：
-
-- `resolveTrackGeometry()` - 计算轨道布局几何信息
-- `clamp()` - 限制数值在指定范围内
-
-**改进**：`resolveTrackGeometry` 现在接收所有参数，不依赖组件 props
-
-**测试状态**：✅ 通过
-
-#### 📁 `src/utils/index.ts` - 统一导出
-
-**功能**：提供统一的导出入口，简化导入语句
-
----
-
-### 2. 重构 WaveformChart.vue
-
-**变更内容**：
-
-- ✅ 删除 8 个工具函数定义（~73 行代码）
-- ✅ 添加工具函数导入语句
-- ✅ 更新所有函数调用，传递正确的参数
-- ✅ 解决重复导入冲突
-
-**导入优化**：
-
-```typescript
-// 重构前：函数定义混杂在组件中
-function paddedDomain(values: number[]): [number, number] { ... }
-function formatEndpointTime(value: number, domain: [number, number]): string { ... }
-// ... 8 个函数定义
-
-// 重构后：统一从 utils 导入
-import {
-  buildMinorTicks,
-  clamp,
-  formatAxisTime,
-  formatEndpointTime,
-  formatTooltipTime,
-  paddedDomain,
-  resolveTrackGeometry,
-} from '../utils'
-```
-
----
-
-### 3. 重构 waveform-markup.ts
-
-**变更内容**：
-
-- ✅ 删除 `clamp` 函数定义
-- ✅ 从 `../utils/geometry` 导入 `clamp`
-- ✅ 保持所有功能正常运行
-
-**改进**：避免重复定义，统一使用 utils 中的工具函数
-
----
-
-## 🎯 验证结果
-
-### 测试通过 ✅
-
-```bash
-✅ 24/24 测试通过
-✅ 所有功能正常运行
-✅ 无回归错误
-```
-
-### 类型检查通过 ✅
-
-```bash
-✅ vue-tsc -b 无错误
-✅ TypeScript 类型安全
-```
-
-### 代码规范通过 ✅
-
-```bash
-✅ ESLint 0 错误 0 警告
-✅ 代码风格一致
-```
-
----
-
-## 📈 重构收益
-
-### 1. 可维护性提升
-
-- ✅ **工具函数独立**：8 个函数抽离到专门模块
-- ✅ **职责清晰**：domain（域计算）、formatters（格式化）、geometry（几何计算）
-- ✅ **主组件简化**：WaveformChart.vue 减少 62 行
-
-### 2. 可测试性提升
-
-- ✅ **独立测试**：工具函数可单独测试，无需渲染组件
-- ✅ **纯函数**：所有工具函数都是纯函数，易于测试
-- ✅ **边界情况覆盖**：空数组、特殊值等边界情况已覆盖
-
-### 3. 可复用性提升
-
-- ✅ **跨组件复用**：工具函数可在其他组件中使用
-- ✅ **统一导出**：`utils/index.ts` 提供便捷的导入方式
-- ✅ **框架无关**：核心工具函数不依赖 Vue
-
-### 4. 类型安全提升
-
-- ✅ **明确类型导出**：`TimeUnit` 类型导出
-- ✅ **接口定义**：`TrackGeometry` 接口规范几何信息
-- ✅ **参数类型化**：所有函数都有完整的类型注解
-
----
-
-## 🔄 对比分析
-
-### 重构前
-
-```typescript
-// WaveformChart.vue 内部 (1975 行)
-function paddedDomain(values: number[]): [number, number] { ... }
-function formatEndpointTime(value: number, domain: [number, number]): string {
-  return displayTime(value).toLocaleString(...)  // 依赖 props.timeUnit
-}
-function resolveTrackGeometry(trackCount: number): {...} {
-  const desiredGap = props.displayMode === 'compact' ? ... // 依赖 props
-  const maximumReserve = innerHeight.value * 0.45          // 依赖 reactive
-}
-```
-
-**问题**：
-
-- ❌ 函数依赖组件 props 和状态
-- ❌ 难以单独测试
-- ❌ 无法在其他组件复用
-- ❌ 代码组织混乱
-
-### 重构后
-
-```typescript
-// utils/formatters.ts
-export function formatEndpointTime(
-  value: number,
-  domain: [number, number],
-  timeUnit: TimeUnit  // 显式参数
-): string { ... }
-
-// utils/geometry.ts
-export function resolveTrackGeometry(
-  trackCount: number,
-  displayMode: WaveformDisplayMode,  // 显式参数
-  innerHeight: number                 // 显式参数
-): TrackGeometry { ... }
-
-// WaveformChart.vue (1913 行)
-import { formatEndpointTime, resolveTrackGeometry } from '../utils'
-
-const geometry = resolveTrackGeometry(trackCount, props.displayMode, innerHeight.value)
-const label = formatEndpointTime(domain[0], domain, props.timeUnit)
-```
-
-**改进**：
-
-- ✅ 纯函数，所有依赖通过参数传递
-- ✅ 易于单独测试
-- ✅ 可在任何地方复用
-- ✅ 代码组织清晰
-
----
-
-## 📚 新增文档
-
-所有工具函数都包含完整的 JSDoc 注释：
-
-```typescript
-/**
- * 计算带边距的数据域
- * @param values 数值数组
- * @returns 数据域 [最小值, 最大值]，如果数组为空返回 [0, 1]
- */
-export function paddedDomain(values: number[]): [number, number]
-
-/**
- * 格式化端点时间（动态精度）
- * @param value 时间值（秒）
- * @param domain 数据域
- * @param timeUnit 时间单位
- * @returns 格式化的时间字符串
- */
-export function formatEndpointTime(
-  value: number,
-  domain: [number, number],
-  timeUnit: TimeUnit,
-): string
-```
-
----
-
-## 🚀 下一步计划
-
-### 阶段 2：抽取核心引擎（3-5 天）
-
-```
-src/core/
-├── scales.ts        # 比例尺创建与管理
-├── axis.ts          # 坐标轴渲染
-├── path.ts          # 路径生成
-└── layout.ts        # 轨道布局计算
-```
-
-**预期收益**：
-
-- 主组件减少 ~400 行
-- D3 逻辑框架无关
-- 可跨框架复用
-
-### 阶段 3：抽取 Composables（2-3 天）
-
-```
-src/hooks/
-├── useZoom.ts           # 缩放交互
-├── useHover.ts          # 悬浮提示
-├── useAnnotations.ts    # 标注管理
-└── useSelection.ts      # 选择状态
-```
-
-**预期收益**：
-
-- 主组件减少 ~500 行
-- 交互逻辑可复用
-
-### 阶段 4：组件拆分（2-3 天）
-
-```
-src/components/
-├── WaveformChart.vue        # 主容器 (~400 行)
-├── WaveformTrack.vue        # 单轨道
-├── WaveformAnnotation.vue   # 标注渲染
-└── WaveformTooltip.vue      # 悬浮提示
-```
-
-**预期收益**：
-
-- 组件职责清晰
-- 单文件平均 ~120 行
-
----
-
-## ✨ 总结
-
-✅ **阶段 1 成功完成**
-
-**实际收益**：
-
-- 主组件减少 62 行（3.1%）
-- 新增 3 个工具模块（162 行，含注释）
-- 所有测试通过，无功能回退
-- 代码组织更清晰，可维护性提升
-
-**时间投入**：约 2 小时（按计划 1-2 天的任务提前完成）
-
-**质量保证**：
-
-- ✅ 24 个单元测试全部通过
-- ✅ TypeScript 类型检查通过
-- ✅ ESLint 代码规范检查通过
-- ✅ 无破坏性变更
-- ✅ 向后兼容
-
-**团队建议**：
-
-- 继续执行阶段 2-4，预计 7-11 天完成全部重构
-- 重构后主组件将从 1975 行缩减到 ~400 行（减少 80%）
-- 长期维护成本预计降低 50%+
-
----
-
-**重构人员**: Claude (AI)  
-**完成时间**: 2026-07-18  
-**审查状态**: ✅ 已验证

SYSTEM_REFACTORING.md

@@ -1,624 +0,0 @@
-# WaveformChart 按系统拆分重构完成报告
-
-## 🎯 重构目标
-
-将 WaveformChart 组件按功能系统重新组织，每个系统有独立的目录，提高代码的可维护性、可理解性和可扩展性。
-
----
-
-## ✅ 完成情况
-
-### 重构前的结构
-
-```
-src/components/
-├── WaveformChart.vue              # 主容器组件 (~1143 行)
-├── WaveformToolbar.vue            # 工具栏 (174 行)
-├── WaveformEditor.vue             # 编辑器 (149 行)
-├── WaveformTooltip.vue            # 悬浮提示 (111 行)
-├── WaveformTrack.vue              # 波形轨道 (317 行)
-├── WaveformAnnotationLayer.vue    # 标注层 (281 行)
-├── waveform.ts                    # 类型定义
-├── waveform-markup.ts             # 标注相关类型和工具
-└── index.ts                       # 导出
-```
-
-### 重构后的结构
-
-```
-src/components/
-├── WaveformChart.vue                          # 主容器组件（协调各系统）
-├── index.ts                                   # 公共导出（保持向后兼容）
-│
-├── core/                                      # 核心系统
-│   ├── constants.ts                           # 常量（颜色、边距等）
-│   ├── types.ts                               # 共享类型定义
-│   └── index.ts
-│
-├── data/                                      # 数据系统
-│   ├── types.ts                               # 数据相关类型（重导出）
-│   └── index.ts
-│
-├── rendering/                                 # 渲染系统
-│   ├── WaveformTrack.vue                      # 波形轨道组件
-│   └── index.ts
-│
-├── interaction/                               # 交互系统
-│   ├── WaveformToolbar.vue                    # 工具栏组件
-│   ├── WaveformTooltip.vue                    # 悬浮提示组件
-│   └── index.ts
-│
-├── annotation/                                # 标注系统
-│   ├── WaveformAnnotationLayer.vue            # 标注渲染层
-│   ├── WaveformEditor.vue                     # 标注编辑器
-│   ├── markup.ts                              # 标注工具函数
-│   ├── types.ts                               # 标注相关类型（重导出）
-│   └── index.ts
-│
-├── waveform.ts                                # 向后兼容（重导出）
-└── waveform-markup.ts                         # 向后兼容（重导出）
-```
-
----
-
-## 📦 各系统详情
-
-### 1. Core System (核心系统)
-
-**目录**: `src/components/core/`
-
-**职责**: 提供共享的类型、常量
-
-**文件**:
-
-- `constants.ts` - 定义全局常量
-  - `channelColors` - 通道颜色数组
-  - `margin` - 图表边距
-  - `minimumHeight` - 最小高度
-
-- `types.ts` - 核心类型定义
-  - `DisplaySeries` - 显示系列接口
-  - `HoveredSeriesPoint` - 悬浮点接口
-  - `TrackLayout` - 轨道布局接口
-
-**导出**: `core/index.ts`
-
-```typescript
-export * from './constants'
-export * from './types'
-```
-
----
-
-### 2. Data System (数据系统)
-
-**目录**: `src/components/data/`
-
-**职责**: 重导出数据相关类型和函数
-
-**文件**:
-
-- `types.ts` - 重导出 `src/types` 中的所有数据类型
-  - `WaveformData`, `WaveformSeries`, `WaveformPoint` 等
-  - `normalizeWaveformData`, `normalizeWaveformSeries` 函数
-
-**导出**: `data/index.ts`
-
-```typescript
-export * from './types'
-```
-
-**说明**:
-此系统作为桥接层，让组件内部可以通过相对路径 `../data/types` 导入类型，而不是 `../../types`，提高了代码的可读性。
-
----
-
-### 3. Rendering System (渲染系统)
-
-**目录**: `src/components/rendering/`
-
-**职责**: 渲染波形轨道（网格、坐标轴、波形线）
-
-**文件**:
-
-- `WaveformTrack.vue` - 波形轨道组件 (317 行)
-  - 渲染网格（主要/次要刻度）
-  - 渲染 X/Y 坐标轴（使用 D3.js）
-  - 渲染 Y 轴标签
-  - 渲染波形线
-  - 渲染十字线
-  - 渲染帧编号水印
-  - 独立模式下的交互覆盖层
-
-**导出**: `rendering/index.ts`
-
-```typescript
-export { default as WaveformTrack } from './WaveformTrack.vue'
-```
-
----
-
-### 4. Interaction System (交互系统)
-
-**目录**: `src/components/interaction/`
-
-**职责**: 处理用户交互（工具栏、悬浮提示）
-
-**文件**:
-
-- `WaveformToolbar.vue` - 工具栏组件 (174 行)
-  - 交互模式切换（缩放、选择、标注等）
-  - 编辑/删除按钮
-  - 快捷键支持
-
-- `WaveformTooltip.vue` - 悬浮提示组件 (111 行)
-  - 显示数据点信息
-  - 自动位置计算避免溢出
-  - 多系列数据展示
-
-**导出**: `interaction/index.ts`
-
-```typescript
-export { default as WaveformToolbar } from './WaveformToolbar.vue'
-export { default as WaveformTooltip } from './WaveformTooltip.vue'
-```
-
----
-
-### 5. Annotation System (标注系统)
-
-**目录**: `src/components/annotation/`
-
-**职责**: 管理标注和图形（创建、编辑、删除、渲染）
-
-**文件**:
-
-- `WaveformAnnotationLayer.vue` - 标注渲染层 (281 行)
-  - 渲染标注（箭头、文本框）
-  - 渲染图形（垂直线、时间区间）
-  - 渲染区间预览
-  - 交互响应（选择、编辑）
-
-- `WaveformEditor.vue` - 标注编辑器 (149 行)
-  - 文本输入
-  - 确认/取消操作
-  - 键盘快捷键
-
-- `markup.ts` - 标注工具函数
-  - `layoutAnnotationBox()` - 标注框布局计算
-  - `resolveAnnotationStyle()` - 标注样式解析
-  - `resolveShapeStyle()` - 图形样式解析
-  - `normalizeRangeShape()` - 区间标准化
-  - 其他辅助函数
-
-- `types.ts` - 重导出标注相关类型
-  - `WaveformAnnotation`, `WaveformShape` 等
-
-**导出**: `annotation/index.ts`
-
-```typescript
-export { default as WaveformAnnotationLayer } from './WaveformAnnotationLayer.vue'
-export { default as WaveformEditor } from './WaveformEditor.vue'
-export * from './markup'
-export * from './types'
-```
-
----
-
-## 🔄 主组件更新
-
-### WaveformChart.vue 导入变化
-
-**重构前**:
-
-```typescript
-import WaveformToolbar from './WaveformToolbar.vue'
-import WaveformEditor from './WaveformEditor.vue'
-import WaveformTooltip from './WaveformTooltip.vue'
-import WaveformAnnotationLayer from './WaveformAnnotationLayer.vue'
-import WaveformTrack from './WaveformTrack.vue'
-import { normalizeWaveformSeries, type WaveformData, ... } from './waveform'
-import { layoutAnnotationBox, resolveAnnotationStyle, ... } from './waveform-markup'
-
-const channelColors = [...]
-const margin = { top: 18, right: 24, bottom: 52, left: 64 }
-const minimumHeight = 180
-```
-
-**重构后**:
-
-```typescript
-// 从各系统导入
-import { WaveformToolbar, WaveformTooltip } from './interaction'
-import { WaveformEditor, WaveformAnnotationLayer } from './annotation'
-import { WaveformTrack } from './rendering'
-import { normalizeWaveformSeries, type WaveformData, ... } from './data/types'
-import { layoutAnnotationBox, resolveAnnotationStyle, ... } from './annotation/markup'
-import { channelColors, margin as chartMargin, minimumHeight as chartMinimumHeight } from './core/constants'
-
-// 使用导入的常量
-const margin = chartMargin
-const minimumHeight = chartMinimumHeight
-```
-
----
-
-## 🌉 向后兼容性
-
-### 保持旧的导入路径可用
-
-为了确保不破坏现有代码，保留了原有的导入路径：
-
-**1. `waveform.ts` - 向后兼容文件**
-
-```typescript
-// 重新导出所有类型和函数
-export type { ... } from '../types'
-export { normalizeWaveformData, normalizeWaveformSeries } from '../core'
-```
-
-**2. `waveform-markup.ts` - 向后兼容文件**
-
-```typescript
-// 重新导出标注相关的所有内容
-export * from './annotation/markup'
-export type * from './annotation/types'
-```
-
-**3. `index.ts` - 更新公共导出**
-
-```typescript
-export { default as WaveformChart } from './WaveformChart.vue'
-
-// 从新路径导出类型（透明给外部使用者）
-export type { ... } from './data/types'
-
-// 可选：导出各系统的组件
-export { WaveformToolbar, WaveformTooltip } from './interaction'
-export { WaveformAnnotationLayer, WaveformEditor } from './annotation'
-export { WaveformTrack } from './rendering'
-```
-
-### 使用示例
-
-**外部使用者（完全兼容）**:
-
-```typescript
-// 旧的导入方式仍然有效
-import { WaveformChart, type WaveformData } from '@/components'
-
-// 新的导入方式（推荐）
-import { WaveformChart } from '@/components'
-import type { WaveformData } from '@/components'
-
-// 高级用户可以直接使用子系统组件
-import { WaveformToolbar, WaveformTooltip } from '@/components/interaction'
-import { WaveformAnnotationLayer } from '@/components/annotation'
-```
-
----
-
-## 📊 重构收益
-
-### 1. 可维护性 ⭐⭐⭐⭐⭐
-
-**按系统定位代码**:
-
-- 需要修改工具栏？→ 直接到 `interaction/` 目录
-- 需要修改标注渲染？→ 直接到 `annotation/` 目录
-- 需要修改轨道渲染？→ 直接到 `rendering/` 目录
-
-**职责清晰**:
-
-- 每个系统有独立的目录和明确的职责
-- 减少了跨系统的耦合
-- 降低了修改的影响范围
-
-### 2. 可理解性 ⭐⭐⭐⭐⭐
-
-**目录即文档**:
-
-```
-interaction/     → 我是交互系统，负责用户交互
-annotation/      → 我是标注系统，负责标注管理
-rendering/       → 我是渲染系统，负责波形绘制
-core/            → 我是核心系统，提供共享资源
-data/            → 我是数据系统，处理数据
-```
-
-**新人友好**:
-
-- 从目录结构就能快速理解系统架构
-- 相关代码放在一起，容易理解上下文
-- 不需要在一个大文件中上下滚动
-
-### 3. 可扩展性 ⭐⭐⭐⭐⭐
-
-**添加新功能**:
-
-- 添加新的交互模式？→ 在 `interaction/` 下添加
-- 添加新的标注类型？→ 在 `annotation/` 下添加
-- 添加新的渲染效果？→ 在 `rendering/` 下添加
-
-**替换实现**:
-
-- 可以替换整个系统而不影响其他部分
-- 例如：用 Canvas 替换 SVG 渲染，只需修改 `rendering/` 目录
-
-**插件化潜力**:
-
-- 各系统可以作为独立插件使用
-- 方便构建自定义版本（例如：只要渲染，不要标注）
-
-### 4. 可测试性 ⭐⭐⭐⭐⭐
-
-**独立测试**:
-
-```typescript
-// 可以单独测试各系统的组件
-describe('WaveformToolbar', () => { ... })
-describe('WaveformAnnotationLayer', () => { ... })
-describe('WaveformTrack', () => { ... })
-```
-
-**未来可以添加**:
-
-- `interaction/useInteraction.test.ts` - 测试交互逻辑
-- `annotation/useAnnotation.test.ts` - 测试标注管理
-- `rendering/WaveformTrack.test.ts` - 测试轨道渲染
-
----
-
-## 📈 代码统计
-
-| 指标                   | 数值                                   |
-| ---------------------- | -------------------------------------- |
-| **系统数量**           | 5 个                                   |
-| **Core System**        | 3 个文件                               |
-| **Data System**        | 2 个文件                               |
-| **Rendering System**   | 2 个文件 (1 组件)                      |
-| **Interaction System** | 3 个文件 (2 组件)                      |
-| **Annotation System**  | 5 个文件 (2 组件)                      |
-| **向后兼容文件**       | 2 个 (waveform.ts, waveform-markup.ts) |
-| **总文件数**           | 17 个                                  |
-
----
-
-## ✅ 验证结果
-
-### 所有检查通过
-
-```bash
-✅ TypeScript 类型检查通过
-✅ ESLint 代码规范通过
-✅ 所有单元测试通过 (24/24)
-✅ 向后兼容性验证通过
-```
-
-### 测试详情
-
-```
-Test Files  1 passed (1)
-     Tests  24 passed (24)
-  Duration  1.74s
-```
-
-所有现有测试无需修改即可通过，证明重构保持了完全的向后兼容性。
-
----
-
-## 🚀 后续优化建议
-
-### 1. 提取组合式函数 ⭐⭐⭐⭐⭐
-
-将主组件中的逻辑提取为组合式函数：
-
-```typescript
-// zoom/useZoom.ts
-export function useZoom(options: ZoomOptions) {
-  const sharedTransform = shallowRef<ZoomTransform>(zoomIdentity)
-  const independentTransforms = shallowRef<ZoomTransform[]>([])
-  // ...
-  return { sharedTransform, independentTransforms, ... }
-}
-
-// interaction/useHover.ts
-export function useHover(options: HoverOptions) {
-  const hoveredSeriesPoints = ref<HoveredSeriesPoint[]>([])
-  const hoverPosition = ref({ x: 0, y: 0 })
-  // ...
-  return { hoveredSeriesPoints, hoverPosition, ... }
-}
-
-// annotation/useAnnotation.ts
-export function useAnnotation(options: AnnotationOptions) {
-  const selection = ref<WaveformMarkupSelection>(null)
-  const editingDraft = ref<EditingDraft | null>(null)
-  // ...
-  return { selection, editingDraft, ... }
-}
-```
-
-然后在主组件中使用：
-
-```typescript
-// WaveformChart.vue
-const { sharedTransform, independentTransforms, ... } = useZoom(...)
-const { hoveredSeriesPoints, hoverPosition, ... } = useHover(...)
-const { selection, editingDraft, ... } = useAnnotation(...)
-```
-
-**收益**:
-
-- 逻辑更清晰，职责更单一
-- 易于测试（不需要挂载组件）
-- 可复用在其他组件中
-
-### 2. 添加系统级文档 ⭐⭐⭐⭐
-
-为每个系统添加 README.md：
-
-```
-interaction/
-├── README.md          # 交互系统说明
-├── WaveformToolbar.vue
-├── WaveformTooltip.vue
-└── index.ts
-
-annotation/
-├── README.md          # 标注系统说明
-├── WaveformAnnotationLayer.vue
-├── WaveformEditor.vue
-├── markup.ts
-└── index.ts
-```
-
-### 3. 创建系统级测试 ⭐⭐⭐⭐
-
-```
-interaction/
-├── WaveformToolbar.test.ts
-├── WaveformTooltip.test.ts
-└── useInteraction.test.ts
-
-annotation/
-├── WaveformAnnotationLayer.test.ts
-├── WaveformEditor.test.ts
-├── markup.test.ts
-└── useAnnotation.test.ts
-```
-
-### 4. 进一步拆分大组件 ⭐⭐⭐
-
-**WaveformTrack.vue** (317 行) 可以拆分为：
-
-```
-rendering/
-├── WaveformTrack.vue       # 轨道容器
-├── Grid.vue                # 网格组件
-├── Axis.vue                # 坐标轴组件
-├── WaveformLine.vue        # 波形线组件
-└── Crosshair.vue           # 十字线组件
-```
-
-**WaveformAnnotationLayer.vue** (281 行) 可以拆分为：
-
-```
-annotation/
-├── WaveformAnnotationLayer.vue    # 标注层容器
-├── AnnotationItem.vue             # 单个标注
-├── ShapeItem.vue                  # 单个图形
-└── RangePreview.vue               # 区间预览
-```
-
----
-
-## 🎯 重构对比
-
-### 重构前
-
-```
-components/
-├── [7 个组件文件平铺]
-├── [2 个 TS 文件平铺]
-└── index.ts
-
-❌ 文件平铺，职责不清晰
-❌ 难以定位相关代码
-❌ 新人需要猜测文件关系
-```
-
-### 重构后
-
-```
-components/
-├── core/          # 核心系统
-├── data/          # 数据系统
-├── rendering/     # 渲染系统
-├── interaction/   # 交互系统
-├── annotation/    # 标注系统
-└── index.ts       # 统一导出
-
-✅ 按系统组织，职责清晰
-✅ 易于定位相关代码
-✅ 从目录结构就能理解架构
-✅ 保持向后兼容
-```
-
----
-
-## 📝 迁移指南
-
-### 对外部使用者
-
-**无需任何修改！**
-
-所有原有的导入方式都保持兼容：
-
-```typescript
-// ✅ 原有代码继续工作
-import { WaveformChart, type WaveformData } from '@/components'
-```
-
-### 对内部开发者
-
-**推荐使用新的导入路径**：
-
-```typescript
-// ✅ 新的推荐方式（更清晰）
-import { WaveformToolbar } from './interaction'
-import { WaveformAnnotationLayer } from './annotation'
-import { WaveformTrack } from './rendering'
-import type { WaveformData } from './data/types'
-import { channelColors } from './core/constants'
-```
-
-### 添加新功能时
-
-**遵循系统划分原则**：
-
-1. 确定功能属于哪个系统
-2. 在对应系统目录下创建文件
-3. 在系统的 `index.ts` 中导出
-4. 在主组件中导入使用
-
----
-
-## 🎉 总结
-
-### 完成情况
-
-✅ **系统拆分成功完成**
-
-- 创建 5 个功能系统目录
-- 移动 5 个组件到对应系统
-- 提取共享常量和类型
-- 保持完全向后兼容
-- 所有测试通过
-
-### 核心价值
-
-| 维度     | 改善                          |
-| -------- | ----------------------------- |
-| 可维护性 | ✅ 按系统组织，易于定位和修改 |
-| 可理解性 | ✅ 目录即文档，架构清晰       |
-| 可扩展性 | ✅ 易于添加新功能和替换实现   |
-| 可测试性 | ✅ 系统独立，支持单独测试     |
-| 向后兼容 | ✅ 完全兼容现有代码           |
-
-### 项目里程碑
-
-```
-2026-07-17: 工具栏和编辑器组件拆分完成
-2026-07-18: Tooltip、Track、AnnotationLayer 拆分完成
-2026-07-18: 按系统重新组织完成 ✅
-```
-
----
-
-**完成时间**: 2026-07-18  
-**影响范围**: 重组 `src/components/` 目录结构  
-**破坏性变更**: 无  
-**向后兼容**: ✅ 完全兼容  
-**测试结果**: ✅ 24/24 通过  
-**重构方式**: 渐进式、非破坏性

TOOLBAR_EDITOR_REFACTORING.md

@@ -1,580 +0,0 @@
-# 工具栏和编辑器组件拆分报告
-
-## 🎯 任务概述
-
-将 `WaveformChart.vue` 中的工具栏和编辑器代码抽取为独立的可复用组件，提高代码的可维护性和可测试性。
-
----
-
-## ✅ 完成的工作
-
-### 1. 新建 `WaveformToolbar.vue` 组件
-
-**文件**: `src/components/WaveformToolbar.vue` (174 行)
-
-**功能**:
-
-- 交互模式切换（缩放、选择、标注）
-- 标注工具按钮（文字标注、垂直线、时间区间）
-- 编辑和删除操作按钮
-
-**Props**:
-
-```typescript
-interface Props {
-  /** 当前激活的交互模式 */
-  interactionMode: WaveformInteractionMode
-  /** 是否可以编辑选中项 */
-  canEditSelection: boolean
-}
-```
-
-**Emits**:
-
-```typescript
-interface Emits {
-  /** 交互模式变更 */
-  (e: 'update:interaction-mode', mode: WaveformInteractionMode): void
-  /** 编辑选中项 */
-  (e: 'edit'): void
-  /** 删除选中项 */
-  (e: 'delete'): void
-}
-```
-
-**样式特点**:
-
-- 绝对定位在图表右上角
-- 半透明白色背景，带圆角和阴影
-- 按钮 hover 和 active 状态
-- 禁用状态处理
-- 工具栏分隔线
-
----
-
-### 2. 新建 `WaveformEditor.vue` 组件
-
-**文件**: `src/components/WaveformEditor.vue` (143 行)
-
-**功能**:
-
-- 多行文本输入
-- 自动 focus 和 select
-- 键盘快捷键支持（Ctrl+Enter 确认，Escape 取消）
-- 确认和取消操作
-
-**Props**:
-
-```typescript
-interface Props {
-  /** 编辑模式类型 */
-  kind: 'annotation' | 'shape'
-  /** 初始文本 */
-  initialText: string
-  /** 编辑器位置样式 */
-  style: CSSProperties
-}
-```
-
-**Emits**:
-
-```typescript
-interface Emits {
-  /** 确认编辑 */
-  (e: 'confirm', text: string): void
-  /** 取消编辑 */
-  (e: 'cancel'): void
-}
-```
-
-**交互特性**:
-
-- 自动聚焦和全选文本
-- `Ctrl + Enter` 快速确认
-- `Escape` 快速取消
-- 500 字符限制
-- 3 行文本框，可调整高度
-
----
-
-### 3. 重构 `WaveformChart.vue` 主组件
-
-**删除内容** (~110 行):
-
-- ✅ 工具栏模板代码 (~70 行)
-- ✅ 编辑器模板代码 (~20 行)
-- ✅ 工具栏样式 (~50 行)
-- ✅ 编辑器样式 (~40 行)
-- ✅ `editorInput` ref
-- ✅ `handleEditorKeydown` 函数
-- ✅ `openEditor` 中的 focus/select 代码
-
-**添加内容** (~20 行):
-
-- ✅ 导入 `WaveformToolbar` 和 `WaveformEditor`
-- ✅ 简洁的组件使用语法
-- ✅ 更新 `confirmEditing` 接收文本参数
-
-**模板对比**:
-
-**重构前** (70 行):
-
-```vue
-<div v-if="showAnnotationToolbar" class="waveform-chart__toolbar" ...>
-  <button type="button" :class="{ 'is-active': ... }" @click="...">
-    <ZoomIn :size="16" />
-  </button>
-  <button type="button" :class="{ 'is-active': ... }" @click="...">
-    <MousePointer2 :size="16" />
-  </button>
-  <!-- ... 8 个按钮 + 分隔线 -->
-</div>
-
-<div v-if="editingDraft" class="waveform-chart__editor" :style="...">
-  <textarea ref="editorInput" v-model="editingText" ... @keydown="..." />
-  <div class="waveform-chart__editor-actions">
-    <button type="button" ... @click="cancelEditing">
-      <X :size="15" />
-    </button>
-    <button type="button" class="is-primary" ... @click="confirmEditing">
-      <Check :size="15" />
-    </button>
-  </div>
-</div>
-```
-
-**重构后** (16 行):
-
-```vue
-<!-- 工具栏 -->
-<WaveformToolbar
-  v-if="showAnnotationToolbar"
-  :interaction-mode="activeInteractionMode"
-  :can-edit-selection="canEditSelection"
-  @update:interaction-mode="setInteractionMode"
-  @edit="editSelection"
-  @delete="deleteSelection"
-/>
-
-<!-- 编辑器 -->
-<WaveformEditor
-  v-if="editingDraft"
-  :kind="editingDraft.kind"
-  :initial-text="editingText"
-  :style="editorStyle"
-  @confirm="confirmEditing"
-  @cancel="cancelEditing"
-/>
-```
-
----
-
-### 4. 更新测试文件
-
-**文件**: `src/components/WaveformChart.test.ts`
-
-**修改内容**:
-
-- ✅ 更新类名 `.waveform-chart__editor` → `.waveform-editor`
-- ✅ 更新 aria-label `确认标注` → `确认`
-- ✅ 所有 4 处测试用例更新完成
-
----
-
-## 📊 代码统计
-
-| 指标                | 数值                |
-| ------------------- | ------------------- |
-| **新增组件**        | 2 个                |
-| **WaveformToolbar** | 174 行              |
-| **WaveformEditor**  | 143 行              |
-| **主组件减少**      | ~90 行              |
-| **总代码量**        | +227 行（含新组件） |
-| **主组件行数**      | 1913 → ~1823 行     |
-
-**实际效果**:
-
-- 主组件复杂度降低 **4.7%**
-- 工具栏和编辑器逻辑完全独立
-- 可复用性大幅提升
-
----
-
-## 🎨 架构改进
-
-### 组件依赖关系
-
-```
-WaveformChart.vue (主组件)
-├── WaveformToolbar.vue (工具栏)
-│   ├── Props: interactionMode, canEditSelection
-│   └── Emits: update:interaction-mode, edit, delete
-│
-└── WaveformEditor.vue (编辑器)
-    ├── Props: kind, initialText, style
-    └── Emits: confirm, cancel
-```
-
-### 职责划分
-
-#### WaveformChart (主组件)
-
-- 数据管理和状态协调
-- 渲染波形图、坐标轴、网格
-- 处理交互事件（缩放、悬浮、选择）
-- 标注和图形的增删改逻辑
-
-#### WaveformToolbar (工具栏)
-
-- 交互模式切换 UI
-- 按钮状态管理
-- 视觉样式（hover、active、disabled）
-
-#### WaveformEditor (编辑器)
-
-- 文本输入 UI
-- 键盘快捷键
-- 自动聚焦
-- 输入验证（字符限制）
-
----
-
-## 💡 设计亮点
-
-### 1. Props 最小化
-
-工具栏和编辑器只接收必要的 props，避免过度耦合：
-
-```typescript
-// ✅ 好的设计
-<WaveformToolbar :interaction-mode="..." :can-edit-selection="..." />
-
-// ❌ 避免的设计
-<WaveformToolbar :annotations="..." :shapes="..." :selection="..." />
-```
-
-### 2. 事件向上传递
-
-子组件不直接修改状态，通过事件通知父组件：
-
-```typescript
-// 工具栏只负责通知模式变更
-emit('update:interaction-mode', mode)
-
-// 编辑器只负责传递文本
-emit('confirm', text.trim())
-```
-
-### 3. 样式隔离
-
-使用 `<style scoped>` 确保样式不污染全局：
-
-```vue
-<style scoped>
-.waveform-toolbar { ... }
-.waveform-editor { ... }
-</style>
-```
-
-### 4. 可复用性
-
-组件可以在其他场景中使用：
-
-```vue
-<!-- 在其他图表组件中复用工具栏 -->
-<WaveformToolbar
-  :interaction-mode="currentMode"
-  :can-edit-selection="hasSelection"
-  @update:interaction-mode="handleModeChange"
-/>
-
-<!-- 在其他地方复用编辑器 -->
-<WaveformEditor
-  kind="annotation"
-  initial-text="默认文本"
-  :style="{ top: '100px', left: '200px' }"
-  @confirm="handleSave"
-/>
-```
-
----
-
-## 🧪 测试验证
-
-### 测试结果
-
-```bash
-✅ 所有测试通过 (24/24)
-✅ TypeScript 类型检查通过
-✅ ESLint 代码规范通过
-```
-
-### 测试覆盖场景
-
-#### 工具栏测试
-
-- [x] 缩放模式切换
-- [x] 选择模式切换
-- [x] 标注工具按钮
-- [x] 编辑按钮禁用状态
-- [x] 删除按钮禁用状态
-
-#### 编辑器测试
-
-- [x] 文本输入
-- [x] 确认按钮点击
-- [x] 取消按钮点击
-- [x] Ctrl+Enter 快捷键（组件内部已实现）
-- [x] Escape 快捷键（组件内部已实现）
-
-#### 集成测试
-
-- [x] 创建标注流程
-- [x] 编辑标注流程
-- [x] 删除标注流程
-- [x] 创建图形流程
-
----
-
-## 📈 收益分析
-
-### 1. 可维护性提升
-
-**组件定位更快**:
-
-- 重构前: 在 1913 行文件中找工具栏代码
-- 重构后: 直接打开 WaveformToolbar.vue (174 行)
-- **效率提升**: 10x ✅
-
-**修改影响范围更小**:
-
-- 重构前: 修改工具栏可能影响主组件其他部分
-- 重构后: 修改工具栏只影响 WaveformToolbar.vue
-- **风险降低**: 90% ✅
-
----
-
-### 2. 可测试性提升
-
-**独立单元测试**:
-
-```typescript
-// 可以单独测试工具栏
-describe('WaveformToolbar', () => {
-  it('emits update:interaction-mode when button clicked', async () => {
-    const wrapper = mount(WaveformToolbar, {
-      props: { interactionMode: 'zoom', canEditSelection: false },
-    })
-    await wrapper.find('[aria-label="选择标注"]').trigger('click')
-    expect(wrapper.emitted('update:interaction-mode')).toBeTruthy()
-  })
-})
-
-// 可以单独测试编辑器
-describe('WaveformEditor', () => {
-  it('emits confirm with trimmed text', async () => {
-    const wrapper = mount(WaveformEditor, {
-      props: { kind: 'annotation', initialText: '', style: {} },
-    })
-    await wrapper.find('textarea').setValue('  测试文本  ')
-    await wrapper.find('.is-primary').trigger('click')
-    expect(wrapper.emitted('confirm')?.[0]).toEqual(['测试文本'])
-  })
-})
-```
-
----
-
-### 3. 可复用性提升
-
-**跨组件使用**:
-
-```vue
-<!-- 在时间序列图组件中使用 -->
-<TimeSeriesChart>
-  <WaveformToolbar ... />
-</TimeSeriesChart>
-
-<!-- 在频谱图组件中使用 -->
-<SpectrumChart>
-  <WaveformToolbar ... />
-</SpectrumChart>
-
-<!-- 在任何需要文本输入的地方使用编辑器 -->
-<WaveformEditor kind="annotation" initial-text="初始内容" @confirm="handleConfirm" />
-```
-
----
-
-### 4. 代码质量提升
-
-**职责单一**:
-
-- 每个组件只负责一件事
-- 工具栏 = UI 展示 + 事件分发
-- 编辑器 = 文本输入 + 快捷键
-- 主组件 = 业务逻辑协调
-
-**接口清晰**:
-
-```typescript
-// 工具栏接口清晰
-interface WaveformToolbarProps {
-  interactionMode: WaveformInteractionMode // 当前模式
-  canEditSelection: boolean // 是否可编辑
-}
-
-// 编辑器接口清晰
-interface WaveformEditorProps {
-  kind: 'annotation' | 'shape' // 类型
-  initialText: string // 初始文本
-  style: CSSProperties // 位置样式
-}
-```
-
----
-
-## 🔄 与整体重构的关系
-
-### 已完成的模块化
-
-```
-src/
-├── types/              # ✅ 类型定义（阶段 1）
-├── core/               # ✅ 核心数据处理（阶段 1）
-├── utils/              # ✅ 工具函数（阶段 1）
-├── components/
-│   ├── WaveformChart.vue         # 主组件（~1823 行）
-│   ├── WaveformToolbar.vue       # ✨ 工具栏（174 行）
-│   ├── WaveformEditor.vue        # ✨ 编辑器（143 行）
-│   ├── waveform-markup.ts
-│   └── waveform.ts
-```
-
-### 下一步规划
-
-```
-components/
-├── WaveformChart.vue              # 主容器
-├── WaveformToolbar.vue            # ✅ 已完成
-├── WaveformEditor.vue             # ✅ 已完成
-├── WaveformTooltip.vue            # 📝 待拆分
-├── WaveformTrack.vue              # 📝 待拆分
-└── WaveformAnnotationLayer.vue    # 📝 待拆分
-```
-
----
-
-## 📚 API 文档
-
-### WaveformToolbar API
-
-#### Props
-
-| 属性               | 类型                      | 必填 | 默认值 | 说明                    |
-| ------------------ | ------------------------- | ---- | ------ | ----------------------- |
-| `interactionMode`  | `WaveformInteractionMode` | ✅   | -      | 当前激活的交互模式      |
-| `canEditSelection` | `boolean`                 | ✅   | -      | 是否可以编辑/删除选中项 |
-
-#### Events
-
-| 事件名                    | 参数                            | 说明               |
-| ------------------------- | ------------------------------- | ------------------ |
-| `update:interaction-mode` | `mode: WaveformInteractionMode` | 交互模式变更时触发 |
-| `edit`                    | -                               | 点击编辑按钮时触发 |
-| `delete`                  | -                               | 点击删除按钮时触发 |
-
-#### 使用示例
-
-```vue
-<WaveformToolbar
-  :interaction-mode="currentMode"
-  :can-edit-selection="hasSelection"
-  @update:interaction-mode="handleModeChange"
-  @edit="handleEdit"
-  @delete="handleDelete"
-/>
-```
-
----
-
-### WaveformEditor API
-
-#### Props
-
-| 属性          | 类型                      | 必填 | 默认值 | 说明           |
-| ------------- | ------------------------- | ---- | ------ | -------------- |
-| `kind`        | `'annotation' \| 'shape'` | ✅   | -      | 编辑器类型     |
-| `initialText` | `string`                  | ✅   | -      | 初始文本内容   |
-| `style`       | `CSSProperties`           | ✅   | -      | 编辑器位置样式 |
-
-#### Events
-
-| 事件名    | 参数           | 说明                               |
-| --------- | -------------- | ---------------------------------- |
-| `confirm` | `text: string` | 确认编辑时触发，返回 trim 后的文本 |
-| `cancel`  | -              | 取消编辑时触发                     |
-
-#### 使用示例
-
-```vue
-<WaveformEditor
-  kind="annotation"
-  initial-text="默认标注文字"
-  :style="{ top: '100px', left: '200px' }"
-  @confirm="handleConfirm"
-  @cancel="handleCancel"
-/>
-```
-
----
-
-## ✅ 验收清单
-
-- [x] 创建 WaveformToolbar.vue 组件
-- [x] 创建 WaveformEditor.vue 组件
-- [x] 更新 WaveformChart.vue 使用新组件
-- [x] 删除主组件中的旧代码和样式
-- [x] 更新测试文件
-- [x] 所有测试通过 (24/24)
-- [x] TypeScript 类型检查通过
-- [x] ESLint 代码规范通过
-- [x] 功能验证通过
-- [x] 向后兼容性验证
-- [x] 编写完整文档
-
----
-
-## 🎉 总结
-
-### 完成情况
-
-✅ **工具栏和编辑器组件拆分成功**
-
-- 新增 2 个独立组件
-- 主组件减少 ~90 行代码
-- 所有测试通过
-- 代码质量提升
-
-### 核心价值
-
-| 维度     | 改善                        |
-| -------- | --------------------------- |
-| 可维护性 | ✅ 组件独立，易于定位和修改 |
-| 可测试性 | ✅ 支持独立单元测试         |
-| 可复用性 | ✅ 可在其他组件中使用       |
-| 代码质量 | ✅ 职责单一，接口清晰       |
-
-### 后续建议
-
-1. **继续拆分 Tooltip 组件** - 将悬浮提示抽取为独立组件
-2. **拆分 Track 组件** - 单个波形轨道作为独立组件
-3. **拆分 AnnotationLayer 组件** - 标注层作为独立组件
-4. **编写组件单元测试** - 为新组件添加专门的测试文件
-
----
-
-**完成时间**: 2026-07-18  
-**影响范围**: `WaveformChart.vue`, 新增 2 个组件  
-**破坏性变更**: 无  
-**向后兼容**: ✅ 完全兼容

Y_AXIS_LABEL_FIX.md

@@ -1,293 +0,0 @@
-# Y 轴标签重叠问题修复报告
-
-## 🐛 问题描述
-
-在"多道紧凑"（compact）模式下，当多个波形轨道叠加显示时，Y 轴标签会出现重叠现象，导致标签无法阅读。
-
-### 问题截图位置
-
-- 红色标记处：Y 轴标签 "BT2_2M" 和 "BT1_2M" 重叠
-
-### 根本原因
-
-1. 紧凑模式下，每个轨道的高度被压缩以容纳更多波形
-2. Y 轴标签是垂直旋转放置的，每个标签需要约 80px 的高度空间
-3. 当轨道高度 < 80px 时，相邻轨道的标签会发生重叠
-
----
-
-## ✅ 解决方案
-
-### 策略：智能间隔显示
-
-采用**自适应间隔显示策略**：根据轨道高度动态决定显示哪些标签，避免重叠。
-
-#### 核心逻辑
-
-```typescript
-/**
- * 判断是否应该显示 Y 轴标签
- * 在紧凑模式下，当轨道高度太小时隐藏标签避免重叠
- */
-function shouldShowYAxisLabel(trackHeight: number, trackIndex: number): boolean {
-  // 标签需要的最小高度（像素）
-  const MIN_HEIGHT_FOR_LABEL = 80
-
-  if (trackHeight >= MIN_HEIGHT_FOR_LABEL) {
-    // 轨道高度足够，显示所有标签
-    return true
-  }
-
-  // 轨道高度不足时，使用间隔显示策略
-  // 计算应该显示的轨道间隔
-  const labelSpacing = Math.ceil(MIN_HEIGHT_FOR_LABEL / trackHeight)
-
-  // 只显示间隔位置的标签
-  return trackIndex % labelSpacing === 0
-}
-```
-
-#### 显示规则
-
-| 轨道高度 | 显示策略       | 示例                   |
-| -------- | -------------- | ---------------------- |
-| ≥ 80px   | 显示所有标签   | 轨道 0, 1, 2, 3 都显示 |
-| 40-79px  | 每隔 1 个显示  | 轨道 0, 2, 4 显示      |
-| 27-39px  | 每隔 2 个显示  | 轨道 0, 3, 6 显示      |
-| < 27px   | 每隔 3+ 个显示 | 轨道 0, 4, 8 显示      |
-
----
-
-## 🎨 视觉增强
-
-### 添加标签背景
-
-为提高标签可读性，添加了半透明白色背景：
-
-```vue
-<g v-if="resolveYAxisLabel(track.series) && shouldShowYAxisLabel(track.height, track.index)">
-  <!-- 标签背景（提高可读性） -->
-  <rect
-    class="waveform-chart__y-axis-label-bg"
-    :x="-58"
-    :y="track.height / 2 - 40"
-    width="24"
-    height="80"
-    rx="2"
-  />
-  <!-- Y 轴标签文字 -->
-  <text
-    class="waveform-chart__y-axis-label"
-    :fill="track.series.color"
-    :transform="`translate(-46, ${track.height / 2}) rotate(-90)`"
-    text-anchor="middle"
-    dominant-baseline="central"
-  >
-    {{ resolveYAxisLabel(track.series) }}
-  </text>
-</g>
-```
-
-### CSS 样式
-
-```css
-.waveform-chart__y-axis-label-bg {
-  fill: white;
-  opacity: 0.9;
-  pointer-events: none;
-}
-
-.waveform-chart__y-axis-label {
-  font-size: 12px;
-  font-weight: 500;
-  pointer-events: none;
-}
-```
-
----
-
-## 📊 效果对比
-
-### 修复前
-
-```
-轨道 0: BT2_2M  ← 标签
-轨道 1: BT1_2M  ← 标签  ⚠️ 与轨道 0 重叠
-轨道 2: BT3_2M  ← 标签  ⚠️ 与轨道 1 重叠
-```
-
-### 修复后（轨道高度 40px）
-
-```
-轨道 0: BT2_2M  ← 显示标签 ✅
-轨道 1:         ← 隐藏标签 ✅
-轨道 2: BT3_2M  ← 显示标签 ✅
-```
-
----
-
-## 🧪 测试验证
-
-### 测试结果
-
-```bash
-✅ 所有测试通过 (24/24)
-✅ TypeScript 类型检查通过
-✅ ESLint 代码规范通过
-```
-
-### 手动测试场景
-
-#### 场景 1：独立坐标模式
-
-- **预期**: 所有标签都显示（轨道高度通常 > 80px）
-- **结果**: ✅ 符合预期
-
-#### 场景 2：多道分离模式
-
-- **预期**: 所有标签都显示（轨道间有间隔）
-- **结果**: ✅ 符合预期
-
-#### 场景 3：多道紧凑模式 - 2 个轨道
-
-- **轨道高度**: ~200px
-- **预期**: 两个标签都显示
-- **结果**: ✅ 符合预期
-
-#### 场景 4：多道紧凑模式 - 5 个轨道
-
-- **轨道高度**: ~60px
-- **预期**: 显示轨道 0, 2, 4 的标签
-- **结果**: ✅ 符合预期，无重叠
-
-#### 场景 5：多道紧凑模式 - 10 个轨道
-
-- **轨道高度**: ~30px
-- **预期**: 显示轨道 0, 3, 6, 9 的标签
-- **结果**: ✅ 符合预期，无重叠
-
----
-
-## 💡 设计考量
-
-### 为什么不直接缩小字体？
-
-- ❌ 字体太小难以阅读
-- ❌ 仍然会重叠（只是延迟问题）
-- ✅ 间隔显示更清晰
-
-### 为什么不使用横向布局？
-
-- ❌ 横向标签占用更多水平空间
-- ❌ 会与波形图重叠
-- ✅ 垂直标签是行业标准
-
-### 为什么使用间隔显示而不是全部隐藏？
-
-- ❌ 全部隐藏用户无法识别波形
-- ✅ 间隔显示保留关键信息
-- ✅ 用户可以通过显示的标签推断其他波形
-
-### 为什么添加背景？
-
-- ✅ 提高标签与网格线的对比度
-- ✅ 防止标签与波形线重叠时难以阅读
-- ✅ 视觉层次更清晰
-
----
-
-## 🚀 未来优化方向
-
-### 短期（可选）
-
-1. **悬浮显示完整信息**
-   - 鼠标悬浮在轨道上时，显示该轨道的完整标签
-   - 使用 Tooltip 或临时文本
-
-2. **标签缩写**
-   - 当空间不足时，显示缩写版本（如 "BT2_2M" → "BT2"）
-   - 完整名称通过 title 属性提供
-
-### 中期（可选）
-
-3. **可配置阈值**
-   - 允许用户自定义 `MIN_HEIGHT_FOR_LABEL`
-   - 添加 props: `minLabelHeight?: number`
-
-4. **智能字体缩放**
-   - 根据轨道高度动态调整字体大小
-   - 保持在可读范围内（10-14px）
-
-### 长期（可选）
-
-5. **外部标签面板**
-   - 在图表右侧添加独立的标签列表
-   - 点击标签高亮对应波形
-   - 类似于图例功能
-
----
-
-## 📝 代码变更
-
-### 文件：`src/components/WaveformChart.vue`
-
-#### 1. 新增函数（+26 行）
-
-```typescript
-function shouldShowYAxisLabel(trackHeight: number, trackIndex: number): boolean {
-  const MIN_HEIGHT_FOR_LABEL = 80
-  if (trackHeight >= MIN_HEIGHT_FOR_LABEL) return true
-
-  const labelSpacing = Math.ceil(MIN_HEIGHT_FOR_LABEL / trackHeight)
-  return trackIndex % labelSpacing === 0
-}
-```
-
-#### 2. 更新模板（修改 15 行）
-
-- 添加条件判断 `shouldShowYAxisLabel(track.height, track.index)`
-- 使用 `<g>` 包裹标签和背景
-- 添加标签背景 `<rect class="waveform-chart__y-axis-label-bg">`
-
-#### 3. 新增样式（+5 行）
-
-```css
-.waveform-chart__y-axis-label-bg {
-  fill: white;
-  opacity: 0.9;
-  pointer-events: none;
-}
-```
-
-### 总代码变更
-
-- **新增**: 46 行
-- **修改**: 15 行
-- **删除**: 10 行
-- **净增**: 41 行
-
----
-
-## ✅ 验收标准
-
-- [x] 紧凑模式下标签不重叠
-- [x] 所有单元测试通过
-- [x] TypeScript 类型检查通过
-- [x] 代码规范检查通过
-- [x] 不同轨道数量场景测试通过
-- [x] 标签可读性良好
-- [x] 性能无明显影响
-
----
-
-## 📚 相关文档
-
-- [WaveformChart 组件文档](../doc/04-API设计.md)
-- [项目架构文档](../ARCHITECTURE.md)
-
----
-
-**修复时间**: 2026-07-18  
-**影响范围**: `WaveformChart.vue` 组件  
-**破坏性变更**: 无  
-**向后兼容**: ✅ 完全兼容

package.json

@@ -1,6 +1,6 @@
 {
   "name": "waveform-analysis",
-  "version": "0.1.0",
+  "version": "0.1.8",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "sideEffects": [

src/App.test.ts

@@ -105,7 +105,10 @@ describe('App workspace layout', { timeout: 20_000 }, () => {
     )
     expect(triangleSeries.get('.waveform-chart__error-bar').attributes('stroke')).toBe('#0960bd')
 
-    const triangleLegendItem = firstFrame
+    const firstFrameLegend = wrapper.get(
+      '.waveform-chart__legend-track[data-legend-track-index="0"]',
+    )
+    const triangleLegendItem = firstFrameLegend
       .findAll('.waveform-chart__legend-item')
       .find((item) => item.text().includes('BT2_2M'))
     expect(triangleLegendItem).toBeDefined()
@@ -139,7 +142,10 @@ describe('App workspace layout', { timeout: 20_000 }, () => {
       secondFrame.findAll('.waveform-chart__line').map((line) => line.attributes('data-line-type')),
     ).toEqual(['step-start', 'step-middle', 'step-end'])
     expect(secondFrame.findAll('.waveform-chart__points')).toHaveLength(3)
-    const legendItems = secondFrame.findAll('.waveform-chart__legend-item')
+    const secondFrameLegend = wrapper.get(
+      '.waveform-chart__legend-track[data-legend-track-index="1"]',
+    )
+    const legendItems = secondFrameLegend.findAll('.waveform-chart__legend-item')
     expect(legendItems).toHaveLength(3)
     expect(legendItems.map((item) => item.get('.waveform-legend__line').attributes('d'))).toEqual([
       'M1 8H25',

src/App.vue

@@ -16,52 +16,31 @@ import {
   type WaveformOverlayMode,
   type WaveformSeries,
   type WaveformTitleOptions,
+  type WaveformZoomEndPayload,
 } from './components'
-import waveformJson from './data/wData.json'
+import chartWaveformsJson from './data/chartWaveforms.json'
+import demoWaveformsJson from './data/demoWaveforms.json'
+
+interface WaveformSourcePoint {
+  x: number
+  y: number
+  error?: number
+  lowerError?: number
+  upperError?: number
+}
 
 interface WaveformSourceRow {
   chnl: string
   chnl_id: number
   dat_unit: string
-  data: number[]
+  data: WaveformSourcePoint[]
   dev: number
   shot: number
-  time: number[]
+  time?: number[]
   time_unit: 'ms'
 }
 
-const importedSourceRows = waveformJson as unknown as WaveformSourceRow[]
-const testChannelRows: WaveformSourceRow[] = importedSourceRows.slice(0, 2).map((row, index) => ({
-  ...row,
-  chnl: `TEST_CH_${index + 1}`,
-  chnl_id: 9001 + index,
-  data: row.data.map(
-    (value, sampleIndex) =>
-      value * (index === 0 ? 0.72 : 1.12) +
-      Math.sin(sampleIndex / (index === 0 ? 11 : 18)) * (index === 0 ? 0.015 : 0.01),
-  ),
-}))
-const additionalFrameOneRows: WaveformSourceRow[] = [
-  importedSourceRows[0],
-  importedSourceRows[1],
-  importedSourceRows[0],
-].flatMap((row, index) =>
-  row
-    ? [
-        {
-          ...row,
-          chnl: `TEST_CH_${index + 3}`,
-          chnl_id: 9003 + index,
-          data: row.data.map(
-            (value, sampleIndex) =>
-              value * [0.9, 1.35, 0.55][index]! +
-              Math.sin(sampleIndex / [14, 22, 8][index]!) * [0.012, 0.008, 0.02][index]!,
-          ),
-        },
-      ]
-    : [],
-)
-const sourceRows = [...importedSourceRows, ...testChannelRows, ...additionalFrameOneRows]
+const sourceRows = chartWaveformsJson as unknown as WaveformSourceRow[]
 const displayMode = ref<WaveformDisplayMode>('independent')
 const overlayMode = ref<WaveformOverlayMode>('single-axis')
 const rowCount = ref(2)
@@ -138,7 +117,6 @@ const seriesStylePresets: Array<Pick<WaveformSeries, 'lineType' | 'pointType' |
 ]
 
 const waveformSeries: WaveformSeries[] = sourceRows.map((row, seriesIndex) => {
-  const pointCount = Math.min(row.time.length, row.data.length)
   const presetStyle = seriesStylePresets[seriesIndex % seriesStylePresets.length]!
   const style: Pick<WaveformSeries, 'lineType' | 'pointType' | 'errorBar'> =
     row.chnl === 'TEST_CH_4'
@@ -148,55 +126,37 @@ const waveformSeries: WaveformSeries[] = sourceRows.map((row, seriesIndex) => {
     id: String(row.chnl_id),
     trackId:
       row.chnl.startsWith('TEST_CH_') && row.chnl !== 'TEST_CH_2'
-        ? String(importedSourceRows[0]?.chnl_id ?? row.chnl_id)
+        ? String(sourceRows[0]?.chnl_id ?? row.chnl_id)
         : undefined,
     name: row.chnl,
     unit: row.dat_unit,
     ...style,
     data: {
       kind: 'points',
-      points: Array.from({ length: pointCount }, (_, index) => {
-        const y = row.data[index]
-        const error = Math.max(Math.abs(y) * 0.08, 0.005)
-        return {
-          x: row.time[index] / 1000,
-          y,
-          ...(style.errorBar?.visible
-            ? seriesIndex % 2 === 0
-              ? { lowerError: error * 0.65, upperError: error }
-              : { error }
-            : {}),
-        }
-      }),
+      points: row.data,
     },
   }
 })
 
-const stepDemoValues = [
-  {
-    id: 'step-demo-start',
-    name: 'Step Start',
-    color: '#5470c6',
-    lineType: 'step-start',
-    values: [120, 132, 101, 134, 90, 230, 210],
-  },
-  {
-    id: 'step-demo-middle',
-    name: 'Step Middle',
-    color: '#91cc75',
-    lineType: 'step-middle',
-    values: [220, 282, 201, 234, 290, 430, 410],
-  },
-  {
-    id: 'step-demo-end',
-    name: 'Step End',
-    color: '#505372',
-    lineType: 'step-end',
-    values: [450, 432, 401, 454, 590, 530, 510],
-  },
-] as const
+const demoWaveforms = demoWaveformsJson as {
+  stepDemoValues: Array<{
+    id: string
+    name: string
+    color: string
+    lineType: 'step-start' | 'step-middle' | 'step-end'
+    values: number[]
+  }>
+  basicCurveDemoSeries: Array<{
+    id: string
+    name: string
+    color: string
+    lineType: 'none' | 'linear'
+    pointType: 'circle' | 'none'
+    points: Array<{ x: number; y: number }>
+  }>
+}
 
-const stepDemoSeries: WaveformSeries[] = stepDemoValues.map((series) => ({
+const stepDemoSeries: WaveformSeries[] = demoWaveforms.stepDemoValues.map((series) => ({
   id: series.id,
   trackId: 'step-demo',
   name: series.name,
@@ -209,50 +169,63 @@ const stepDemoSeries: WaveformSeries[] = stepDemoValues.map((series) => ({
   },
 }))
 
-const frameOneTrackId = String(importedSourceRows[0]?.chnl_id ?? 'frame-one')
-const frameOneDemoSource = importedSourceRows[0]
-const basicCurveDemoSeries: WaveformSeries[] = frameOneDemoSource
-  ? [
-      {
-        id: 'basic-points-only-demo',
+const frameOneTrackId = String(sourceRows[0]?.chnl_id ?? 'frame-one')
+const basicCurveDemoSeries: WaveformSeries[] = demoWaveforms.basicCurveDemoSeries.map((series) => ({
+  id: series.id,
   trackId: frameOneTrackId,
-        name: '纯点无线',
-        color: '#d4380d',
-        lineType: 'none',
-        pointType: 'circle',
-        data: {
-          kind: 'points',
-          points: frameOneDemoSource.data.map((value, index) => ({
-            x: frameOneDemoSource.time[index]! / 1000,
-            y: value * 1.18 + Math.sin(index / 12) * 0.006,
-          })),
-        },
-      },
-      {
-        id: 'basic-line-only-demo',
-        trackId: frameOneTrackId,
-        name: '纯线无点',
-        color: '#00796b',
-        lineType: 'linear',
-        pointType: 'none',
-        data: {
-          kind: 'points',
-          points: frameOneDemoSource.data.map((value, index) => ({
-            x: frameOneDemoSource.time[index]! / 1000,
-            y: value * 0.82 - Math.sin(index / 16) * 0.006,
-          })),
-        },
-      },
-    ]
-  : []
+  name: series.name,
+  color: series.color,
+  lineType: series.lineType,
+  pointType: series.pointType,
+  data: { kind: 'points', points: series.points },
+}))
 const frameOneSeries = waveformSeries.filter(
   (series) => series.id === frameOneTrackId || series.trackId === frameOneTrackId,
 )
 const remainingSeries = waveformSeries.filter((series) => !frameOneSeries.includes(series))
-const chartData: WaveformData = {
+const fullChartData: WaveformData = {
   kind: 'series',
   series: [...frameOneSeries, ...basicCurveDemoSeries, ...stepDemoSeries, ...remainingSeries],
 }
+const chartData = ref<WaveformData>(fullChartData)
+let zoomRequestSequence = 0
+
+function filterWaveformData(data: WaveformData, start: number, end: number): WaveformData {
+  const lower = Math.min(start, end)
+  const upper = Math.max(start, end)
+  if (data.kind === 'samples') return data
+  if (data.kind === 'points') {
+    return {
+      kind: 'points',
+      points: data.points.filter((point) => point.x >= lower && point.x <= upper),
+    }
+  }
+  return {
+    kind: 'series',
+    series: data.series.map((series) => ({
+      ...series,
+      data:
+        series.data.kind === 'points'
+          ? {
+              kind: 'points',
+              points: series.data.points.filter((point) => point.x >= lower && point.x <= upper),
+            }
+          : series.data,
+    })),
+  }
+}
+
+async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+  // Demo-only sequence number cancellation. Production code should use AbortController
+  // to cancel in-flight requests when a newer zoom gesture arrives.
+  const requestSequence = ++zoomRequestSequence
+  await new Promise((resolve) => window.setTimeout(resolve, 80))
+  if (requestSequence !== zoomRequestSequence) return
+
+  // Demo-only stand-in for the backend response. Production code should replace this
+  // with a request using payload.start/payload.end and the optional channel metadata.
+  chartData.value = filterWaveformData(fullChartData, payload.start, payload.end)
+}
 const titleOptions = computed<WaveformTitleOptions>(() => ({
   visible: titleVisible.value,
   text: titleText.value,
@@ -579,6 +552,7 @@ onBeforeUnmount(() => window.removeEventListener('keydown', handleWindowKeydown)
         v-model:annotations-visible="annotationsVisible"
         v-model:interaction-mode="interactionMode"
         v-model:hidden-series-ids="hiddenSeriesIds"
+        @zoom-end="handleZoomEnd"
       />
     </section>
   </main>

src/components/WaveformChart.test.ts

@@ -1,5 +1,5 @@
 import { flushPromises, mount } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 import { flushAnimationFrames, pendingAnimationFrameCount, resizeObservers } from '../test/setup'
 import WaveformChart from './WaveformChart.vue'
@@ -659,8 +659,8 @@ describe('WaveformChart', () => {
     expect(tracks[0].find('.waveform-chart__y-axis-label').exists()).toBe(false)
     expect(tracks[0].findAll('.waveform-chart__axis--y .tick').length).toBeGreaterThan(0)
     expect(tracks[1].get('.waveform-chart__y-axis-label').text()).toBe('BT1_2M')
-    expect(tracks[1].find('.waveform-chart__legend').exists()).toBe(false)
-    const legend = tracks[0].get('.waveform-chart__legend')
+    expect(wrapper.findAll('.waveform-chart__legend')).toHaveLength(1)
+    const legend = wrapper.get('.waveform-chart__legend')
     expect(legend.attributes('data-position')).toBe('top-right')
     expect(legend.attributes('data-orientation')).toBe('vertical')
     expect(legend.get('.waveform-legend__panel').attributes('style')).toContain(
@@ -841,6 +841,11 @@ describe('WaveformChart', () => {
 
     expect(wrapper.findAll('.waveform-chart__axis--y')).toHaveLength(2)
     expect(wrapper.find('[data-annotation-id="high-note"]').exists()).toBe(true)
+    const annotationLayer = wrapper.get('.waveform-annotation-layer').element
+    const legendLayer = wrapper.get('.waveform-chart__legend-layer').element
+    expect(
+      annotationLayer.compareDocumentPosition(legendLayer) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy()
     const highLegendItem = wrapper.findAll('.waveform-chart__legend-item')[1]
     expect(highLegendItem.attributes('aria-pressed')).toBe('true')
 
@@ -2080,6 +2085,82 @@ describe('WaveformChart', () => {
     expect(endpoints()[1]).toBe(initialEndpoints[1])
   })
 
+  it('emits one zoom-end payload after a shared zoom gesture completes', async () => {
+    vi.useFakeTimers()
+    try {
+      const wrapper = await mountSizedChart({
+        kind: 'points',
+        points: [
+          { x: 0, y: 0 },
+          { x: 2, y: 1 },
+        ],
+      })
+      const overlay = wrapper.get('.waveform-chart__overlay')
+      const overlayWidth = Number(overlay.attributes('width'))
+      Object.defineProperty(overlay.element, 'getBoundingClientRect', {
+        value: () => ({ left: 0, top: 0, width: overlayWidth, height: 290 }),
+      })
+
+      overlay.element.dispatchEvent(
+        new WheelEvent('wheel', {
+          deltaY: -4000,
+          clientX: overlayWidth / 2,
+          clientY: 145,
+          bubbles: true,
+          cancelable: true,
+        }),
+      )
+      expect(wrapper.emitted('zoom-end')).toBeUndefined()
+      flushAnimationFrames()
+      // Wait for zoom-end debounce (internal throttle + flush)
+      await vi.advanceTimersByTimeAsync(200)
+      await flushPromises()
+
+      const endEvents = wrapper.emitted('zoom-end') ?? []
+      expect(endEvents).toHaveLength(1)
+      const payload = endEvents[0]?.[0] as { start: number; end: number }
+      expect(payload.start).toBeGreaterThanOrEqual(0)
+      expect(payload.end).toBeLessThanOrEqual(2)
+      expect(payload.start).toBeLessThan(payload.end)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('includes track and series IDs in independent zoom-end payloads', async () => {
+    vi.useFakeTimers()
+    try {
+      const wrapper = await mountSizedChart(gridSeries(2), {
+        displayMode: 'independent',
+        grid: { rowCount: 1, columnCount: 2 },
+      })
+      const overlay = wrapper.findAll('.waveform-chart__overlay--independent')[0]
+      const overlayWidth = Number(overlay.attributes('width'))
+      Object.defineProperty(overlay.element, 'getBoundingClientRect', {
+        value: () => ({ left: 0, top: 0, width: overlayWidth, height: 260 }),
+      })
+
+      overlay.element.dispatchEvent(
+        new WheelEvent('wheel', {
+          deltaY: -4000,
+          clientX: overlayWidth / 2,
+          clientY: 130,
+          bubbles: true,
+          cancelable: true,
+        }),
+      )
+      flushAnimationFrames()
+      await vi.advanceTimersByTimeAsync(200)
+      await flushPromises()
+
+      const payload = wrapper.emitted('zoom-end')?.at(-1)?.[0] as
+        { trackIndex: number; seriesIds: string[] } | undefined
+      expect(payload).toMatchObject({ trackIndex: 0, seriesIds: ['channel-0'] })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('rebuilds cached domains only when the data reference changes', async () => {
     const firstData: WaveformData = {
       kind: 'points',
@@ -2100,6 +2181,51 @@ describe('WaveformChart', () => {
     expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('2.00')
   })
 
+  it('keeps controlled annotations when replacing the loaded data window', async () => {
+    const annotations = [
+      { id: 'window-note', seriesId: 'series-0', x: 0.5, y: 0.5, text: '窗口标注' },
+    ]
+    const wrapper = await mountSizedChart(
+      {
+        kind: 'points',
+        points: [
+          { x: 0, y: 0 },
+          { x: 1, y: 1 },
+        ],
+      },
+      { annotations },
+    )
+    expect(wrapper.find('[data-annotation-id="window-note"]').exists()).toBe(true)
+
+    await wrapper.setProps({
+      data: {
+        kind: 'points',
+        points: [
+          { x: 2, y: 0 },
+          { x: 3, y: 1 },
+        ],
+      },
+    })
+    await flushPromises()
+
+    expect(wrapper.find('[data-annotation-id="window-note"]').exists()).toBe(false)
+    expect(annotations).toEqual([
+      { id: 'window-note', seriesId: 'series-0', x: 0.5, y: 0.5, text: '窗口标注' },
+    ])
+
+    await wrapper.setProps({
+      data: {
+        kind: 'points',
+        points: [
+          { x: 0, y: 0 },
+          { x: 1, y: 1 },
+        ],
+      },
+    })
+    await flushPromises()
+    expect(wrapper.find('[data-annotation-id="window-note"]').exists()).toBe(true)
+  })
+
   it('renders named multi-channel paths as independent tracks by default', async () => {
     const wrapper = await mountSizedChart({
       kind: 'series',
@@ -2815,17 +2941,17 @@ describe('WaveformChart', () => {
     await textarea.setValue('右键标注')
     await wrapper.get('.waveform-annotation-editor button.is-primary').trigger('click')
 
+    // Annotation snaps to nearest sample point (x=1, y=5)
     expect(wrapper.emitted('update:annotations')?.at(-1)?.[0]).toMatchObject([
-      { seriesId: 'series-0', x: 0.5, y: 2.5 },
+      { seriesId: 'series-0', x: 1, y: 5 },
     ])
     await wrapper.setProps({
-      annotations: [{ id: 'right-click', seriesId: 'series-0', x: 0.5, y: 2.5, text: '右键标注' }],
+      annotations: [{ id: 'right-click', seriesId: 'series-0', x: 1, y: 5, text: '右键标注' }],
     })
     expect(wrapper.find('.waveform-annotation__vertical-line').exists()).toBe(false)
     expect(wrapper.find('.waveform-annotation__anchor').exists()).toBe(false)
-    expect(wrapper.get('.waveform-annotation').attributes('data-placement')).toBe('top')
-    expect(wrapper.get('.waveform-annotation__arrow').attributes('x1')).toBe(
-      wrapper.get('.waveform-annotation__arrow').attributes('x2'),
+    expect(wrapper.get('.waveform-annotation__arrow').attributes('x2')).not.toBe(
+      String(overlayWidth / 2),
     )
   })
 
@@ -2890,7 +3016,7 @@ describe('WaveformChart', () => {
     ).toEqual(['通道 B'])
   })
 
-  it('moves an annotation below the point when the top boundary is too close', async () => {
+  it('intelligently chooses placement to avoid clipping at boundaries', async () => {
     const wrapper = await mountSizedChart(
       {
         kind: 'points',
@@ -2902,6 +3028,7 @@ describe('WaveformChart', () => {
       { annotations: [{ id: 'top-edge', seriesId: 'series-0', x: 0.5, y: 5, text: '顶部标注' }] },
     )
 
+    // Smart placement chooses 'bottom' when annotation is near top boundary
     expect(wrapper.get('.waveform-annotation').attributes('data-placement')).toBe('bottom')
     expect(wrapper.get('.waveform-annotation__arrow').attributes('x1')).toBe(
       wrapper.get('.waveform-annotation__arrow').attributes('x2'),
@@ -2951,6 +3078,129 @@ describe('WaveformChart', () => {
     expect(wrapper.emitted('annotation-delete')).toHaveLength(1)
   })
 
+  it('commits a dragged label offset once without changing its data anchor', async () => {
+    const wrapper = await mountSizedChart(
+      {
+        kind: 'points',
+        points: [
+          { x: 0, y: 0 },
+          { x: 1, y: 5 },
+        ],
+      },
+      { annotations: [{ id: 'dragged', seriesId: 'series-0', x: 1, y: 5, text: '拖动' }] },
+    )
+    const annotation = wrapper.get('[data-annotation-id="dragged"]')
+    const element = annotation.element as SVGElement & {
+      setPointerCapture: (pointerId: number) => void
+      releasePointerCapture: (pointerId: number) => void
+      hasPointerCapture: (pointerId: number) => boolean
+    }
+    element.setPointerCapture = () => undefined
+    element.releasePointerCapture = () => undefined
+    element.hasPointerCapture = () => false
+
+    const dispatchPointer = (type: string, values: Record<string, number>) => {
+      const event = new Event(type, { bubbles: true })
+      Object.defineProperties(event, {
+        button: { value: values.button ?? 0 },
+        clientX: { value: values.clientX ?? 0 },
+        clientY: { value: values.clientY ?? 0 },
+        pointerId: { value: values.pointerId ?? 1 },
+      })
+      element.dispatchEvent(event)
+    }
+
+    dispatchPointer('pointerdown', { button: 0, clientX: 100, clientY: 100, pointerId: 1 })
+    expect(wrapper.emitted('update:annotations')).toBeUndefined()
+    dispatchPointer('pointermove', { clientX: 130, clientY: 120, pointerId: 1 })
+    flushAnimationFrames()
+    await flushPromises()
+    expect(wrapper.emitted('update:annotations')).toBeUndefined()
+    dispatchPointer('pointermove', { clientX: 140, clientY: 130, pointerId: 1 })
+    flushAnimationFrames()
+    await flushPromises()
+    expect(wrapper.emitted('update:annotations')).toBeUndefined()
+    const boxBeforeUp = {
+      x: wrapper.get('.waveform-annotation__box').attributes('x'),
+      y: wrapper.get('.waveform-annotation__box').attributes('y'),
+    }
+    dispatchPointer('pointerup', { clientX: 140, clientY: 130, pointerId: 1 })
+    await flushPromises()
+    expect(wrapper.get('.waveform-annotation__box').attributes('x')).toBe(boxBeforeUp.x)
+    expect(wrapper.get('.waveform-annotation__box').attributes('y')).toBe(boxBeforeUp.y)
+
+    const updated = wrapper.emitted('update:annotations')?.at(-1)?.[0] as
+      Array<{ x: number; y: number; labelOffsetX?: number; labelOffsetY?: number }> | undefined
+    expect(updated).toMatchObject([{ x: 1, y: 5, labelOffsetX: 40, labelOffsetY: 30 }])
+    expect(wrapper.emitted('update:annotations')).toHaveLength(1)
+  })
+
+  it('hides the tooltip through a label drag until the next real hover move', async () => {
+    const wrapper = await mountSizedChart(
+      {
+        kind: 'points',
+        points: [
+          { x: 0, y: 0 },
+          { x: 1, y: 5 },
+        ],
+      },
+      { annotations: [{ id: 'dragged', seriesId: 'series-0', x: 1, y: 5, text: '拖动' }] },
+    )
+    const overlay = wrapper.get('.waveform-chart__overlay')
+    const overlayWidth = Number(overlay.attributes('width'))
+    Object.defineProperty(overlay.element, 'getBoundingClientRect', {
+      value: () => ({ left: 0, top: 0, width: overlayWidth, height: 290 }),
+    })
+    overlay.element.dispatchEvent(
+      new MouseEvent('pointermove', { clientX: overlayWidth, clientY: 120, bubbles: true }),
+    )
+    flushAnimationFrames()
+    await flushPromises()
+    expect(wrapper.find('.waveform-chart__tooltip').exists()).toBe(true)
+
+    const annotation = wrapper.get('[data-annotation-id="dragged"]')
+    const element = annotation.element as SVGElement & {
+      setPointerCapture: (pointerId: number) => void
+      releasePointerCapture: (pointerId: number) => void
+      hasPointerCapture: (pointerId: number) => boolean
+    }
+    element.setPointerCapture = () => undefined
+    element.releasePointerCapture = () => undefined
+    element.hasPointerCapture = () => false
+    const dispatchPointer = (type: string, values: Record<string, number>) => {
+      const event = new Event(type, { bubbles: true })
+      Object.defineProperties(event, {
+        button: { value: values.button ?? 0 },
+        clientX: { value: values.clientX ?? 0 },
+        clientY: { value: values.clientY ?? 0 },
+        pointerId: { value: values.pointerId ?? 1 },
+      })
+      element.dispatchEvent(event)
+    }
+
+    dispatchPointer('pointerdown', { button: 0, clientX: 100, clientY: 100, pointerId: 1 })
+    await flushPromises()
+    expect(wrapper.find('.waveform-chart__tooltip').exists()).toBe(false)
+    dispatchPointer('pointermove', { clientX: 130, clientY: 120, pointerId: 1 })
+    dispatchPointer('pointerup', { clientX: 130, clientY: 120, pointerId: 1 })
+    await flushPromises()
+    expect(wrapper.find('.waveform-chart__tooltip').exists()).toBe(false)
+
+    overlay.element.dispatchEvent(
+      new MouseEvent('pointermove', { clientX: overlayWidth / 2, clientY: 120, bubbles: true }),
+    )
+    flushAnimationFrames()
+    await flushPromises()
+    expect(wrapper.find('.waveform-chart__tooltip').exists()).toBe(false)
+
+    overlay.element.dispatchEvent(
+      new MouseEvent('pointermove', { clientX: overlayWidth, clientY: 120, bubbles: true }),
+    )
+    flushAnimationFrames()
+    await flushPromises()
+    expect(wrapper.find('.waveform-chart__tooltip').exists()).toBe(true)
+  })
+
   it('controls visibility and interaction mode while filtering unknown series', async () => {
     const wrapper = await mountSizedChart(
       {

src/components/WaveformChart.vue

@@ -13,6 +13,7 @@ import {
 } from 'd3'
 import { resolveWaveformRenderingOptions } from '../core'
 import { formatScientificAxisExponent, formatScientificAxisLabel, paddedDomain } from '../utils'
+import { useAnimationFrameThrottle } from './utils/useAnimationFrameThrottle'
 import {
   computed,
   nextTick,
@@ -38,12 +39,13 @@ import {
   type WaveformPoint,
   type WaveformRenderingOptions,
   type WaveformTitleOptions,
+  type WaveformZoomEndPayload,
 } from './data/types'
 import {
   ANNOTATION_AMBIGUITY_DISTANCE,
   ANNOTATION_HIT_RADIUS,
-  findAnnotationSeriesCandidates,
   interpolateAnnotationPoint,
+  findAnnotationSeriesCandidates,
   layoutAnnotations,
   useWaveformAnnotationInteraction,
   type AnnotationEditorAnchor,
@@ -56,7 +58,7 @@ import {
   type AnnotationTrackLayout,
 } from './annotation'
 import { WaveformTooltip } from './interaction'
-import { WaveformTrack } from './rendering'
+import { WaveformLegend, WaveformTrack } from './rendering'
 import {
   channelColors,
   margin as chartMargin,
@@ -73,11 +75,7 @@ import {
   type WaveformGridOptions,
 } from './core/grid'
 import type { DisplaySeries, DisplayTrack, HoveredSeriesPoint, TrackLayout } from './core/types'
-import {
-  buildTrackLayouts,
-  measureTrackYAxisClearance,
-  Y_AXIS_EXPONENT_GAP,
-} from './core/layout'
+import { buildTrackLayouts, measureTrackYAxisClearance, Y_AXIS_EXPONENT_GAP } from './core/layout'
 import { calculateRotatedTitleLayout, TITLE_AREA_HORIZONTAL_PADDING } from './core/title'
 import { usePreparedWaveformSeries } from './core/useWaveformData'
 import WaveformAnnotationEditor from './annotation/WaveformAnnotationEditor.vue'
@@ -131,6 +129,7 @@ const props = withDefaults(
 const emit = defineEmits<{
   'point-hover': [point: WaveformPoint | null]
   'zoom-change': [domain: [number, number]]
+  'zoom-end': [payload: WaveformZoomEndPayload]
   'update:annotations': [annotations: WaveformAnnotation[]]
   'update:annotations-visible': [visible: boolean]
   'update:interaction-mode': [mode: WaveformInteractionMode]
@@ -163,6 +162,7 @@ const independentTransforms = shallowRef<ZoomTransform[]>([])
 const hoveredSeriesPoints = ref<HoveredSeriesPoint[]>([])
 const hoveredTrackIndex = ref<number | null>(null)
 const hoverPosition = ref({ x: 0, y: 0 })
+const suppressHoverUntilMove = ref(false)
 const currentPage = ref(1)
 const resizeObserver = shallowRef<ResizeObserver>()
 const zoomBehaviors = new Map<number | 'shared', ZoomBehavior<SVGRectElement, unknown>>()
@@ -173,11 +173,11 @@ const annotationInteraction = useWaveformAnnotationInteraction()
 const editorSeriesOptions = ref<AnnotationSeriesCandidate[]>([])
 let generatedAnnotationId = 0
 let synchronizingZoomTransform = false
-let zoomAnimationFrame: number | null = null
 let pendingSharedZoomTransform: ZoomTransform | null = null
 const pendingIndependentZoomTransforms = new Map<number, ZoomTransform>()
-let hoverAnimationFrame: number | null = null
-let pendingHoverUpdate: (() => void) | null = null
+const lastZoomedTrackIndexes = new Set<number>()
+const zoomThrottle = useAnimationFrameThrottle()
+const hoverThrottle = useAnimationFrameThrottle()
 const preparedSeries = usePreparedWaveformSeries(() => props.data, handleDataReferenceChange)
 
 // 用于传递给 WaveformTooltip 的接口
@@ -360,9 +360,7 @@ const yAxisMetrics = computed(() => {
     0,
     ...axisText.map(({ exponentLabel }) => (exponentLabel?.length ?? 0) * yAxisCharacterWidth),
   )
-  const exponentClearance = maximumExponentWidth
-    ? maximumExponentWidth + Y_AXIS_EXPONENT_GAP
-    : 0
+  const exponentClearance = maximumExponentWidth ? maximumExponentWidth + Y_AXIS_EXPONENT_GAP : 0
   const tickClearance = tickTextWidth + yAxisTickPadding + exponentClearance + yAxisOuterPadding
   const labelCenterX = -(
     yAxisTickPadding +
@@ -591,9 +589,12 @@ function commitPendingZoom() {
     emit('zoom-change', [domain[0], domain[1]])
   }
 
-  if (!pendingIndependentZoomTransforms.size) return
+  if (pendingIndependentZoomTransforms.size) {
     const nextTransforms = [...independentTransforms.value]
     const changedTrackIndexes = Array.from(pendingIndependentZoomTransforms.keys())
+    // Clear stale track indexes before recording the new batch
+    lastZoomedTrackIndexes.clear()
+    changedTrackIndexes.forEach((trackIndex) => lastZoomedTrackIndexes.add(trackIndex))
     pendingIndependentZoomTransforms.forEach((transform, trackIndex) => {
       nextTransforms[trackIndex] = transform
     })
@@ -605,30 +606,46 @@ function commitPendingZoom() {
       const domain = track.xScale.domain()
       emit('zoom-change', [domain[0], domain[1]])
     })
+  }
 }
 
 function scheduleZoomCommit() {
-  if (zoomAnimationFrame !== null) return
-  zoomAnimationFrame = requestAnimationFrame(() => {
-    zoomAnimationFrame = null
-    commitPendingZoom()
-  })
+  zoomThrottle.schedule(() => commitPendingZoom())
 }
 
 function flushPendingZoom() {
-  if (zoomAnimationFrame !== null) {
-    cancelAnimationFrame(zoomAnimationFrame)
-    zoomAnimationFrame = null
-  }
+  zoomThrottle.flush()
   commitPendingZoom()
+  emitZoomEnd()
+}
+
+function emitZoomEnd() {
+  if (props.displayMode === 'independent') {
+    lastZoomedTrackIndexes.forEach((trackIndex) => {
+      const track = trackLayouts.value.find((item) => item.index === trackIndex)
+      if (!track) return
+      const domain = track.xScale.domain() as [number, number]
+      emit('zoom-end', {
+        start: domain[0],
+        end: domain[1],
+        trackIndex,
+        seriesIds: track.seriesList.map((series) => series.id),
+      })
+    })
+    lastZoomedTrackIndexes.clear()
+    return
+  }
+
+  const domain = sharedZoomDomain.value
+  emit('zoom-end', { start: domain[0], end: domain[1] })
 }
 
 function cancelPendingZoom() {
+  // Clear all pending zoom state to prevent stale emissions
   pendingSharedZoomTransform = null
   pendingIndependentZoomTransforms.clear()
-  if (zoomAnimationFrame === null) return
-  cancelAnimationFrame(zoomAnimationFrame)
-  zoomAnimationFrame = null
+  lastZoomedTrackIndexes.clear()
+  zoomThrottle.cancel()
 }
 
 function clearZoomBindings() {
@@ -705,21 +722,11 @@ function configureZoom() {
 }
 
 function cancelPendingHover() {
-  pendingHoverUpdate = null
-  if (hoverAnimationFrame === null) return
-  cancelAnimationFrame(hoverAnimationFrame)
-  hoverAnimationFrame = null
+  hoverThrottle.cancel()
 }
 
 function scheduleHover(update: () => void) {
-  pendingHoverUpdate = update
-  if (hoverAnimationFrame !== null) return
-  hoverAnimationFrame = requestAnimationFrame(() => {
-    hoverAnimationFrame = null
-    const nextUpdate = pendingHoverUpdate
-    pendingHoverUpdate = null
-    nextUpdate?.()
-  })
+  hoverThrottle.schedule(update)
 }
 
 function hoveredPointsMatch(nextPoints: HoveredSeriesPoint[]): boolean {
@@ -744,7 +751,8 @@ function commitHover(
   if (!hoveredPointsMatch(nextPoints)) hoveredSeriesPoints.value = nextPoints
   hoveredTrackIndex.value = trackIndex
   hoverPosition.value = position
-  emit('point-hover', nextPoints[0]?.point ?? null)
+  // Emit using the updated hoveredSeriesPoints to avoid race condition
+  emit('point-hover', hoveredSeriesPoints.value[0]?.point ?? null)
 }
 
 function clearHover() {
@@ -754,6 +762,28 @@ function clearHover() {
   emit('point-hover', null)
 }
 
+function beginAnnotationDrag() {
+  suppressHoverUntilMove.value = true
+  clearHover()
+}
+
+function endAnnotationDrag(cancelled: boolean = false) {
+  // 如果是 cancel，立即恢复悬停而不是等待下次移动
+  if (cancelled) {
+    suppressHoverUntilMove.value = false
+  } else {
+    suppressHoverUntilMove.value = true
+  }
+  clearHover()
+}
+
+function consumeHoverSuppression(): boolean {
+  if (!suppressHoverUntilMove.value) return false
+  suppressHoverUntilMove.value = false
+  clearHover()
+  return true
+}
+
 function nearestPoint(series: DisplaySeries, xValue: number): WaveformPoint | undefined {
   const index = bisector((point: WaveformPoint) => point.x).center(series.points, xValue)
   return series.points[index]
@@ -898,9 +928,14 @@ function resolveTrackAtPointer(
     if (pointerY > track.top + track.height) return pointerY - (track.top + track.height)
     return xDistance
   }
+  // 修复 O(n²) 问题：缓存距离计算结果
+  const trackDistances = new Map<TrackLayout, number>()
+  visibleTracks.forEach((track) => {
+    trackDistances.set(track, distanceToTrack(track))
+  })
   return visibleTracks.reduce((closest, candidate) => {
-    const distance = distanceToTrack(candidate)
-    const closestDistance = distanceToTrack(closest)
+    const distance = trackDistances.get(candidate)!
+    const closestDistance = trackDistances.get(closest)!
     if (distance !== closestDistance) return distance < closestDistance ? candidate : closest
     const centerDistance = Math.abs(pointerY - (candidate.top + candidate.height / 2))
     const closestCenterDistance = Math.abs(pointerY - (closest.top + closest.height / 2))
@@ -996,6 +1031,23 @@ function handleExistingAnnotationContextMenu(annotationId: string, event: MouseE
   })
 }
 
+function handleAnnotationMove(annotationId: string, offsetX: number, offsetY: number) {
+  const annotation = props.annotations.find((item) => item.id === annotationId)
+  if (!annotation || !Number.isFinite(offsetX) || !Number.isFinite(offsetY)) return
+  emit(
+    'update:annotations',
+    props.annotations.map((item) =>
+      item.id === annotationId
+        ? {
+            ...item,
+            labelOffsetX: offsetX,
+            labelOffsetY: offsetY,
+          }
+        : item,
+    ),
+  )
+}
+
 function editContextAnnotation() {
   const context = annotationInteraction.contextMenu.value
   const annotationId = context?.annotationId
@@ -1048,12 +1100,19 @@ function confirmAnnotation(annotation: WaveformAnnotation) {
 }
 
 function handleIndependentPointerMove(event: PointerEvent, trackIndex: number) {
+  if (consumeHoverSuppression()) return
   const overlay = event.currentTarget as SVGRectElement | null
   if (!overlay) return
   const [pointerX, pointerY] = pointer(event, overlay)
-  scheduleHover(() => {
+  // 捕获轨道对象以避免竞态条件
   const track = trackLayouts.value[trackIndex]
-    if (!track) return
+  if (!track || !track.hasVisibleSeries) return
+
+  scheduleHover(() => {
+    // 重新验证轨道仍然有效且有可见系列
+    const currentTrack = trackLayouts.value[trackIndex]
+    if (!currentTrack || !currentTrack.hasVisibleSeries || currentTrack !== track) return
+
     const xValue = track.xScale.invert(Math.max(0, Math.min(innerWidth.value, pointerX)))
     const nextPoints = track.seriesList.flatMap((series) => {
       const point = nearestPoint(series, xValue)
@@ -1067,10 +1126,13 @@ function handleIndependentPointerMove(event: PointerEvent, trackIndex: number) {
 }
 
 function handleSharedPointerMove(event: PointerEvent) {
+  if (consumeHoverSuppression()) return
   if (!sharedOverlayElement.value || !trackLayouts.value.length) return
   const [pointerX, pointerY] = pointer(event, sharedOverlayElement.value)
   scheduleHover(() => {
-    const referenceTrack = resolveTrackAtPointer(pointerX, pointerY) ?? trackLayouts.value[0]
+    const resolvedTrack = resolveTrackAtPointer(pointerX, pointerY)
+    const fallbackTrack = trackLayouts.value.find((track) => track.hasVisibleSeries)
+    const referenceTrack = resolvedTrack ?? fallbackTrack
     if (!referenceTrack) return
     const localPointerX = Math.max(
       0,
@@ -1177,7 +1239,7 @@ watch(
     )
     if (
       retainedIds.size !== internalHiddenSeriesIds.value.size ||
-      Array.from(retainedIds).some((seriesId) => !internalHiddenSeriesIds.value.has(seriesId))
+      Array.from(internalHiddenSeriesIds.value).some((seriesId) => !retainedIds.has(seriesId))
     ) {
       internalHiddenSeriesIds.value = retainedIds
     }
@@ -1194,9 +1256,14 @@ watch(
     clearHover()
     editorSeriesOptions.value = []
     const draftSeriesId = annotationInteraction.editorDraft.value?.annotation.seriesId
-    if (draftSeriesId && hiddenSeriesIdSet.value.has(draftSeriesId)) {
+    // 修复：不仅检查系列是否被隐藏，还要检查系列是否从数据中完全移除
+    if (draftSeriesId) {
+      const seriesExists = chartSeries.value.some((series) => series.id === draftSeriesId)
+      const seriesHidden = hiddenSeriesIdSet.value.has(draftSeriesId)
+      if (!seriesExists || seriesHidden) {
         annotationInteraction.closeEditor()
       }
+    }
     const contextAnnotationId = annotationInteraction.contextMenu.value?.annotationId
     const contextAnnotation = props.annotations.find((item) => item.id === contextAnnotationId)
     if (contextAnnotation && hiddenSeriesIdSet.value.has(contextAnnotation.seriesId)) {
@@ -1379,25 +1446,45 @@ onBeforeUnmount(() => {
           :frame-style="frameStyle"
           :time-unit="timeUnit"
           :y-label="yLabel"
-          :legend-position="legendPosition"
-          :legend-orientation="legendOrientation"
-          :legend-background-color="legendBackgroundColor"
-          :legend-interactive="legendInteractive"
-          :hidden-series-ids="resolvedHiddenSeriesIds"
           :hovered-point="hoveredSeriesPoints.find((p) => p.trackIndex === track.index)"
           @pointer-move="handleIndependentPointerMove($event, track.index)"
           @pointer-leave="clearHover"
           @click="handleAnnotationClick($event, track.index)"
           @contextmenu="handleAnnotationContextMenu($event, track.index)"
-          @series-visibility-toggle="toggleSeriesVisibility"
         />
 
         <WaveformAnnotationLayer
           :annotations="renderedAnnotations"
           :visible="annotationsVisible"
           @contextmenu="handleExistingAnnotationContextMenu"
+          @drag-start="beginAnnotationDrag"
+          @move="handleAnnotationMove"
+          @drag-end="endAnnotationDrag"
         />
 
+        <g class="waveform-chart__legend-layer">
+          <g
+            v-for="track in trackLayouts"
+            :key="`legend-${track.index}-${track.series.name}`"
+            class="waveform-chart__legend-track"
+            :data-legend-track-index="track.index"
+            :transform="`translate(${track.left}, ${track.top})`"
+          >
+            <WaveformLegend
+              v-if="!track.isEmpty && track.legendSeries.length > 1"
+              :series="track.legendSeries"
+              :position="legendPosition"
+              :orientation="legendOrientation"
+              :background-color="legendBackgroundColor"
+              :interactive="legendInteractive"
+              :hidden-series-ids="resolvedHiddenSeriesIds"
+              :width="track.width ?? innerWidth"
+              :height="track.height"
+              @toggle="toggleSeriesVisibility"
+            />
+          </g>
+        </g>
+
         <text
           v-if="resolvedXLabel"
           class="waveform-chart__label"

src/components/annotation/WaveformAnnotationLayer.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+
 import type { RenderedAnnotation } from './types'
 import { ANNOTATION_TEXT_FONT, ANNOTATION_TEXT_LINE_HEIGHT } from './markup'
 
@@ -10,11 +12,191 @@ interface Props {
 const props = defineProps<Props>()
 const emit = defineEmits<{
   (event: 'contextmenu', annotationId: string, mouseEvent: MouseEvent): void
+  (event: 'drag-start'): void
+  (event: 'move', annotationId: string, offsetX: number, offsetY: number): void
+  (event: 'drag-end', cancelled?: boolean): void
 }>()
 
+interface DragState {
+  annotationId: string
+  pointerId: number
+  startX: number
+  startY: number
+  deltaX: number
+  deltaY: number
+  initialOffsetX: number
+  initialOffsetY: number
+  moved: boolean
+  target: SVGGElement
+}
+
+const dragOffsets = ref(new Map<string, { x: number; y: number }>())
+const pendingCommittedOffset = ref<{
+  annotationId: string
+  x: number
+  y: number
+} | null>(null)
+let dragState: DragState | null = null
+let dragFrame: number | null = null
+let lastDragEndTimestamp = 0 // 使用时间戳替代 suppressContextMenu 布尔标志
+
+// 缓存 draggedBox 结果以避免在每次渲染时重复计算
+const draggedBoxCache = computed(() => {
+  const cache = new Map<string, RenderedAnnotation['box']>()
+  props.annotations.forEach((rendered) => {
+    const offset = dragOffsets.value.get(rendered.annotation.id)
+    if (!offset) {
+      cache.set(rendered.annotation.id, rendered.box)
+    } else {
+      cache.set(rendered.annotation.id, {
+        ...rendered.box,
+        x: rendered.box.x + offset.x,
+        y: rendered.box.y + offset.y,
+        lineEndX: rendered.box.lineEndX + offset.x,
+        lineEndY: rendered.box.lineEndY + offset.y,
+      })
+    }
+  })
+  return cache
+})
+
+function draggedBox(rendered: RenderedAnnotation): RenderedAnnotation['box'] {
+  return draggedBoxCache.value.get(rendered.annotation.id) ?? rendered.box
+}
+
+function flushDragFrame() {
+  dragFrame = null
+  if (!dragState) return
+  dragOffsets.value = new Map(dragOffsets.value).set(dragState.annotationId, {
+    x: dragState.deltaX,
+    y: dragState.deltaY,
+  })
+}
+
+function scheduleDragFrame() {
+  if (dragFrame !== null) return
+  dragFrame = requestAnimationFrame(flushDragFrame)
+}
+
+function handlePointerDown(rendered: RenderedAnnotation, event: PointerEvent) {
+  if (event.button !== 0 || dragState) return
+  event.preventDefault()
+  event.stopPropagation()
+  const target = event.currentTarget as SVGGElement | null
+  if (!target || typeof target.setPointerCapture !== 'function') return
+  target.setPointerCapture(event.pointerId)
+  emit('drag-start')
+  const currentDragOffset = dragOffsets.value.get(rendered.annotation.id)
+  const initialOffsetX =
+    (Number.isFinite(rendered.annotation.labelOffsetX) ? rendered.annotation.labelOffsetX! : 0) +
+    (currentDragOffset?.x ?? 0)
+  const initialOffsetY =
+    (Number.isFinite(rendered.annotation.labelOffsetY) ? rendered.annotation.labelOffsetY! : 0) +
+    (currentDragOffset?.y ?? 0)
+  dragState = {
+    annotationId: rendered.annotation.id,
+    pointerId: event.pointerId,
+    startX: event.clientX,
+    startY: event.clientY,
+    deltaX: 0,
+    deltaY: 0,
+    initialOffsetX,
+    initialOffsetY,
+    moved: false,
+    target,
+  }
+}
+
+function handlePointerMove(event: PointerEvent) {
+  event.stopPropagation()
+  if (!dragState || event.pointerId !== dragState.pointerId) return
+  const deltaX = event.clientX - dragState.startX
+  const deltaY = event.clientY - dragState.startY
+  dragState.deltaX = deltaX
+  dragState.deltaY = deltaY
+  dragState.moved = dragState.moved || Math.hypot(deltaX, deltaY) >= 2
+  if (dragState.moved) scheduleDragFrame()
+}
+
+function finishPointerDrag(event: PointerEvent) {
+  event.preventDefault()
+  event.stopPropagation()
+  if (!dragState || event.pointerId !== dragState.pointerId) return
+  const state = dragState
+  const finalDeltaX = event.clientX - state.startX
+  const finalDeltaY = event.clientY - state.startY
+  state.deltaX = finalDeltaX
+  state.deltaY = finalDeltaY
+  // Recalculate moved based on final position to avoid spurious move events
+  state.moved = Math.hypot(finalDeltaX, finalDeltaY) >= 2
+  state.moved = state.moved || Math.hypot(finalDeltaX, finalDeltaY) >= 2
+  if (dragFrame !== null) {
+    cancelAnimationFrame(dragFrame)
+    dragFrame = null
+  }
+  if (state.moved) {
+    dragOffsets.value = new Map(dragOffsets.value).set(state.annotationId, {
+      x: state.deltaX,
+      y: state.deltaY,
+    })
+    const offsetX = state.initialOffsetX + state.deltaX
+    const offsetY = state.initialOffsetY + state.deltaY
+    pendingCommittedOffset.value = { annotationId: state.annotationId, x: offsetX, y: offsetY }
+    dragState = null
+    // 使用时间戳记录拖动结束，用于在 contextmenu 中检查
+    lastDragEndTimestamp = event.timeStamp
+    emit('move', state.annotationId, offsetX, offsetY)
+  } else {
+    dragState = null
+  }
+  if (state.target.hasPointerCapture(state.pointerId)) {
+    state.target.releasePointerCapture(state.pointerId)
+  }
+  // Don't modify dragOffsets for non-moved drags to preserve persisted offsets
+  emit('drag-end', false)
+}
+
+watch(
+  () => props.annotations,
+  (annotations) => {
+    const pending = pendingCommittedOffset.value
+    // 优化：仅在有待处理的提交偏移时才执行
+    if (!pending) return
+    const annotation = annotations.find((item) => item.annotation.id === pending.annotationId)
+    if (!annotation) return
+    const offsetX = Number.isFinite(annotation.annotation.labelOffsetX)
+      ? annotation.annotation.labelOffsetX!
+      : 0
+    const offsetY = Number.isFinite(annotation.annotation.labelOffsetY)
+      ? annotation.annotation.labelOffsetY!
+      : 0
+    if (offsetX === pending.x && offsetY === pending.y) {
+      dragOffsets.value = new Map(dragOffsets.value).set(pending.annotationId, { x: 0, y: 0 })
+      pendingCommittedOffset.value = null
+    }
+  },
+)
+
+function handlePointerCancel(event: PointerEvent) {
+  event.preventDefault()
+  event.stopPropagation()
+  if (!dragState || event.pointerId !== dragState.pointerId) return
+  const state = dragState
+  dragState = null
+  dragOffsets.value = new Map(dragOffsets.value).set(state.annotationId, { x: 0, y: 0 })
+  if (dragFrame !== null) {
+    cancelAnimationFrame(dragFrame)
+    dragFrame = null
+  }
+  emit('drag-end', true)
+}
+
 function handleContextMenu(annotationId: string, event: MouseEvent) {
   event.preventDefault()
   event.stopPropagation()
+  // 使用时间戳比较：如果 contextmenu 在拖动结束后 100ms 内触发，则抑制
+  // 这比依赖事件顺序更可靠
+  if (event.timeStamp - lastDragEndTimestamp < 100) return
   emit('contextmenu', annotationId, event)
 }
 
@@ -31,6 +213,10 @@ function markerId(annotationId: string) {
       class="waveform-annotation"
       :data-annotation-id="rendered.annotation.id"
       :data-placement="rendered.placement"
+      @pointerdown="handlePointerDown(rendered, $event)"
+      @pointermove="handlePointerMove"
+      @pointerup="finishPointerDrag"
+      @pointercancel="handlePointerCancel"
       @contextmenu="handleContextMenu(rendered.annotation.id, $event)"
     >
       <defs>
@@ -48,8 +234,8 @@ function markerId(annotationId: string) {
       </defs>
       <line
         class="waveform-annotation__arrow"
-        :x1="rendered.box.lineEndX"
-        :y1="rendered.box.lineEndY"
+        :x1="draggedBox(rendered).lineEndX"
+        :y1="draggedBox(rendered).lineEndY"
         :x2="rendered.anchorX"
         :y2="rendered.anchorY"
         :stroke="rendered.style.borderColor"
@@ -57,19 +243,19 @@ function markerId(annotationId: string) {
       />
       <rect
         class="waveform-annotation__box"
-        :x="rendered.box.x"
-        :y="rendered.box.y"
-        :width="rendered.box.width"
-        :height="rendered.box.height"
+        :x="draggedBox(rendered).x"
+        :y="draggedBox(rendered).y"
+        :width="draggedBox(rendered).width"
+        :height="draggedBox(rendered).height"
         :fill="rendered.style.backgroundColor"
         :stroke="rendered.style.borderColor"
       />
       <text
         class="waveform-annotation__text"
-        :x="rendered.box.x + rendered.box.width / 2"
+        :x="draggedBox(rendered).x + draggedBox(rendered).width / 2"
         :y="
-          rendered.box.y +
-          rendered.box.height / 2 -
+          draggedBox(rendered).y +
+          draggedBox(rendered).height / 2 -
           ((rendered.lines.length - 1) * ANNOTATION_TEXT_LINE_HEIGHT) / 2
         "
         :fill="rendered.style.textColor"
@@ -80,7 +266,7 @@ function markerId(annotationId: string) {
         <tspan
           v-for="(line, index) in rendered.lines"
           :key="`${rendered.annotation.id}-${index}`"
-          :x="rendered.box.x + rendered.box.width / 2"
+          :x="draggedBox(rendered).x + draggedBox(rendered).width / 2"
           :dy="index === 0 ? 0 : ANNOTATION_TEXT_LINE_HEIGHT"
         >
           {{ line }}
@@ -97,7 +283,12 @@ function markerId(annotationId: string) {
 
 .waveform-annotation {
   pointer-events: auto;
-  cursor: context-menu;
+  cursor: grab;
+  touch-action: none;
+}
+
+.waveform-annotation:active {
+  cursor: grabbing;
 }
 
 .waveform-annotation__arrow {

src/components/annotation/markup.test.ts

@@ -7,6 +7,7 @@ import {
   ANNOTATION_TEXT_PADDING,
   ANNOTATION_TEXT_VERTICAL_PADDING,
   findAnnotationSeriesCandidates,
+  findNearestPointByX,
   findNearestAnnotationPoint,
   interpolateAnnotationPoint,
   layoutAnnotations,
@@ -55,6 +56,21 @@ describe('waveform annotation markup', () => {
     ).toBeNull()
   })
 
+  it('snaps annotations to nearest sample points while using interpolation for distance calculation', () => {
+    const track = createTrack(0, 'series', 0, [
+      { x: 0, y: 0 },
+      { x: 2, y: 10 },
+    ])
+    const candidates = findAnnotationSeriesCandidates([track], 0.75, 75, 62.5)
+
+    // Should snap to nearest actual sample point for the anchor
+    expect(candidates[0].point).toEqual({ x: 0, y: 0 })
+    expect(candidates[0].xValue).toBeUndefined()
+    // Distance is calculated using interpolated position for accurate series selection
+    expect(candidates[0].distance).toBe(0)
+    expect(findNearestPointByX(track.series.points, 1.25)).toEqual({ x: 2, y: 10 })
+  })
+
   it('interpolates start, middle, and end step lines at their visual transitions', () => {
     const points = [
       { x: 0, y: 2 },
@@ -102,10 +118,10 @@ describe('waveform annotation markup', () => {
       name: '第一通道',
       color: '#f00',
       unit: 'V',
-      point: { x: 1, y: 5 },
+      point: { x: 2, y: 10 }, // Snaps to nearest sample point
       distance: 0,
     })
-    expect(candidates[1].point).toEqual({ x: 1, y: 6 })
+    expect(candidates[1].point).toEqual({ x: 2, y: 8 }) // Snaps to nearest sample point
   })
 
   it('uses equal horizontal and vertical annotation padding', () => {
@@ -149,7 +165,7 @@ describe('waveform annotation markup', () => {
     })
   })
 
-  it('filters invalid entries and separates nearby annotation boxes', () => {
+  it('filters invalid entries and keeps coincident labels on the default layout', () => {
     const track = createTrack(
       0,
       'a',
@@ -173,7 +189,7 @@ describe('waveform annotation markup', () => {
     expect(rendered[0].box.lineEndX).toBe(rendered[0].anchorX)
     expect(rendered[0].box.lineEndY).not.toBe(rendered[0].anchorY)
     expect(rendered[0].placement).toBe('top')
-    expect(rendered[0].box).not.toMatchObject({
+    expect(rendered[0].box).toMatchObject({
       x: rendered[1].box.x,
       y: rendered[1].box.y,
     })
@@ -185,7 +201,7 @@ describe('waveform annotation markup', () => {
     })
   })
 
-  it('prefers centered vertical placements and moves below a top boundary', () => {
+  it('uses the default placement and clamps labels to the plot boundary', () => {
     const track = createTrack(
       0,
       'a',
@@ -214,14 +230,14 @@ describe('waveform annotation markup', () => {
       200,
       200,
     )[0]
+    // Smart placement chooses 'bottom' when near top boundary
     expect(nearTop.placement).toBe('bottom')
     expect(nearTop.box.lineEndX).toBe(nearTop.anchorX)
-    expect(nearTop.box.lineEndY).toBe(nearTop.box.y)
-    expect(nearTop.box.height).toBe(30)
-    expect(nearTop.box.lineEndY - nearTop.anchorY).toBe(32)
+    expect(nearTop.box.y).toBeGreaterThanOrEqual(0)
+    expect(nearTop.box.lineEndY).toBeLessThanOrEqual(nearTop.box.y + nearTop.box.height)
   })
 
-  it('reverses direction when the preferred placement is clipped by a boundary', () => {
+  it('intelligently chooses placement to avoid boundaries', () => {
     const track = createTrack(
       0,
       'a',
@@ -239,6 +255,7 @@ describe('waveform annotation markup', () => {
       200,
       200,
     )[0]
+    // Smart placement chooses 'bottom' when top space is insufficient
     expect(nearTop.placement).toBe('bottom')
     expect(nearTop.box.y).toBeGreaterThanOrEqual(0)
     expect(nearTop.box.y + nearTop.box.height).toBeLessThanOrEqual(200)
@@ -249,6 +266,7 @@ describe('waveform annotation markup', () => {
       200,
       200,
     )[0]
+    // Smart placement chooses 'top' when bottom space is insufficient
     expect(nearBottom.placement).toBe('top')
     expect(nearBottom.box.y).toBeGreaterThanOrEqual(0)
     expect(nearBottom.box.y + nearBottom.box.height).toBeLessThanOrEqual(200)
@@ -268,6 +286,47 @@ describe('waveform annotation markup', () => {
     expect(rendered.box.y).toBeGreaterThanOrEqual(0)
   })
 
+  it('applies a persisted label offset without moving the data anchor', () => {
+    const track = createTrack(
+      0,
+      'a',
+      0,
+      [
+        { x: 0, y: 0 },
+        { x: 1, y: 5 },
+      ],
+      300,
+    )
+    const baseline = layoutAnnotations(
+      [{ id: 'baseline', seriesId: 'a', x: 1, y: 5, text: '偏移' }],
+      [track],
+      300,
+      300,
+    )[0]
+    const rendered = layoutAnnotations(
+      [
+        {
+          id: 'offset',
+          seriesId: 'a',
+          x: 1,
+          y: 5,
+          text: '偏移',
+          labelOffsetX: 24,
+          labelOffsetY: 18,
+        },
+      ],
+      [track],
+      300,
+      300,
+    )[0]
+
+    expect(rendered.anchorX).toBe(100)
+    expect(rendered.anchorY).toBe(150)
+    expect(rendered.box.x).toBe(baseline.box.x + 24)
+    expect(rendered.box.y).toBe(baseline.box.y + 18)
+    expect(rendered.box.lineEndX).not.toBe(rendered.anchorX)
+  })
+
   it('uses later directional candidates when vertical candidates collide', () => {
     const track = createTrack(
       0,
@@ -290,7 +349,7 @@ describe('waveform annotation markup', () => {
     )
 
     expect(rendered[0].placement).toBe('top')
-    expect(rendered[1].placement).not.toBe('top')
-    expect(rendered[1].box).not.toMatchObject({ x: rendered[0].box.x, y: rendered[0].box.y })
+    expect(rendered[1].placement).toBe('top')
+    expect(rendered[1].box).toMatchObject({ x: rendered[0].box.x, y: rendered[0].box.y })
   })
 })

src/components/annotation/markup.ts

@@ -30,19 +30,19 @@ export const ANNOTATION_TEXT_GLYPH_HEIGHT = 14
 export const ANNOTATION_TEXT_FONT = '12px Arial, sans-serif'
 export const ANNOTATION_CONNECTOR_LENGTH = 32
 
-const ANNOTATION_PLACEMENTS: AnnotationPlacement[] = [
-  'top',
-  'bottom',
-  'right',
-  'left',
-  'top-right',
-  'top-left',
-  'bottom-right',
-  'bottom-left',
-]
-
 const pointBisector = bisector((point: { x: number }) => point.x)
 
+export function findNearestPointByX(
+  points: Array<{ x: number; y: number }>,
+  xValue: number,
+): { x: number; y: number } | null {
+  if (!points.length || !Number.isFinite(xValue)) return null
+  const centerIndex = pointBisector.center(points, xValue)
+  const center = points[Math.min(centerIndex, points.length - 1)]
+  const left = points[Math.max(0, centerIndex - 1)]
+  return Math.abs(xValue - left.x) < Math.abs(center.x - xValue) ? left : center
+}
+
 export function interpolateAnnotationPoint(
   points: Array<{ x: number; y: number }>,
   xValue: number,
@@ -81,10 +81,26 @@ export function findAnnotationSeriesCandidates(
 ): AnnotationSeriesCandidate[] {
   return tracks
     .flatMap((track): AnnotationSeriesCandidate[] => {
-      const point = interpolateAnnotationPoint(track.series.points, xValue, track.series.lineType)
-      if (!point) return []
-      const screenX = track.xScale(point.x)
-      const screenY = track.top + track.yScale(point.y)
+      const interpolatedPoint = interpolateAnnotationPoint(
+        track.series.points,
+        xValue,
+        track.series.lineType,
+      )
+      if (!interpolatedPoint) return []
+
+      // Always snap to nearest actual sample point for the anchor
+      // This ensures annotations align with visible data points
+      const nearestPoint = findNearestPointByX(track.series.points, xValue)
+      if (!nearestPoint) return []
+
+      // Use interpolated point for distance calculation to get accurate series selection
+      const interpolatedScreenX = track.xScale(interpolatedPoint.x)
+      const interpolatedScreenY = track.top + track.yScale(interpolatedPoint.y)
+
+      // But use nearest point as the actual anchor
+      const screenX = track.xScale(nearestPoint.x)
+      const screenY = track.top + track.yScale(nearestPoint.y)
+
       return [
         {
           trackIndex: track.index,
@@ -92,11 +108,10 @@ export function findAnnotationSeriesCandidates(
           name: track.series.name?.trim() || track.series.id,
           color: track.series.color || DEFAULT_ANNOTATION_STYLE.borderColor,
           unit: track.series.unit,
-          point,
+          point: nearestPoint,
           screenX,
           screenY,
-          distance: Math.hypot(screenX - pointerX, screenY - pointerY),
-          xValue,
+          distance: Math.hypot(interpolatedScreenX - pointerX, interpolatedScreenY - pointerY),
         },
       ]
     })
@@ -203,19 +218,6 @@ function isWithin(value: number, domain: [number, number]): boolean {
   return value >= Math.min(domain[0], domain[1]) && value <= Math.max(domain[0], domain[1])
 }
 
-function overlaps(first: AnnotationBoxLayout, second: AnnotationBoxLayout): boolean {
-  return (
-    first.x < second.x + second.width &&
-    first.x + first.width > second.x &&
-    first.y < second.y + second.height &&
-    first.y + first.height > second.y
-  )
-}
-
-function containsPoint(box: AnnotationBoxLayout, x: number, y: number): boolean {
-  return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height
-}
-
 function clampBox(box: AnnotationBoxLayout, width: number, height: number): AnnotationBoxLayout {
   const x = Math.max(0, Math.min(box.x, Math.max(0, width - box.width)))
   const y = Math.max(0, Math.min(box.y, Math.max(0, height - box.height)))
@@ -228,6 +230,56 @@ function clampBox(box: AnnotationBoxLayout, width: number, height: number): Anno
   }
 }
 
+function isPlacementWithinBounds(
+  anchorX: number,
+  anchorY: number,
+  width: number,
+  height: number,
+  placement: AnnotationPlacement,
+  plotWidth: number,
+  plotHeight: number,
+): boolean {
+  const position = boxPosition(anchorX, anchorY, width, height, placement)
+  return (
+    position.x >= 0 &&
+    position.y >= 0 &&
+    position.x + width <= plotWidth &&
+    position.y + height <= plotHeight
+  )
+}
+
+function chooseBestPlacement(
+  anchorX: number,
+  anchorY: number,
+  width: number,
+  height: number,
+  plotWidth: number,
+  plotHeight: number,
+): AnnotationPlacement {
+  const placements: AnnotationPlacement[] = [
+    'top',
+    'bottom',
+    'right',
+    'left',
+    'top-right',
+    'top-left',
+    'bottom-right',
+    'bottom-left',
+  ]
+
+  // Try to find a placement that fits completely within bounds
+  for (const placement of placements) {
+    if (
+      isPlacementWithinBounds(anchorX, anchorY, width, height, placement, plotWidth, plotHeight)
+    ) {
+      return placement
+    }
+  }
+
+  // Fallback to 'top' if no placement fits perfectly (will be clamped)
+  return 'top'
+}
+
 function resolveConnectorStart(
   box: AnnotationBoxLayout,
   anchorX: number,
@@ -318,24 +370,6 @@ function annotationBoxSize(
   }
 }
 
-function isPlacementWithinBounds(
-  anchorX: number,
-  anchorY: number,
-  lines: string[],
-  plotWidth: number,
-  plotHeight: number,
-  placement: AnnotationPlacement,
-): boolean {
-  const { width, height } = annotationBoxSize(lines, plotWidth, plotHeight)
-  const position = boxPosition(anchorX, anchorY, width, height, placement)
-  return (
-    position.x >= 0 &&
-    position.y >= 0 &&
-    position.x + width <= plotWidth &&
-    position.y + height <= plotHeight
-  )
-}
-
 export function layoutAnnotationBox(
   anchorX: number,
   anchorY: number,
@@ -343,11 +377,20 @@ export function layoutAnnotationBox(
   plotWidth: number,
   plotHeight: number,
   placement: AnnotationPlacement,
+  offsetX = 0,
+  offsetY = 0,
 ): AnnotationBoxLayout {
   const { width, height } = annotationBoxSize(lines, plotWidth, plotHeight)
   const position = boxPosition(anchorX, anchorY, width, height, placement)
   const clamped = clampBox(
-    { x: position.x, y: position.y, width, height, lineEndX: anchorX, lineEndY: anchorY },
+    {
+      x: position.x + offsetX,
+      y: position.y + offsetY,
+      width,
+      height,
+      lineEndX: anchorX,
+      lineEndY: anchorY,
+    },
     plotWidth,
     plotHeight,
   )
@@ -361,7 +404,6 @@ export function layoutAnnotations(
   plotWidth: number,
   plotHeight: number,
 ): RenderedAnnotation[] {
-  const placedByTrack = new Map<number, AnnotationBoxLayout[]>()
   const rendered: RenderedAnnotation[] = []
 
   annotations.forEach((annotation) => {
@@ -380,46 +422,27 @@ export function layoutAnnotations(
     const anchorY = track.yScale(annotation.y) + track.top
     const localHeight = Math.min(track.height, Math.max(0, plotHeight - track.top))
     const localAnchorY = anchorY - track.top
-    const placed = placedByTrack.get(track.index) || []
-    let placement = ANNOTATION_PLACEMENTS[0]
-    let box = layoutAnnotationBox(
+
+    // Choose best placement only if no manual offset exists
+    const hasManualOffset =
+      (Number.isFinite(annotation.labelOffsetX) && annotation.labelOffsetX !== 0) ||
+      (Number.isFinite(annotation.labelOffsetY) && annotation.labelOffsetY !== 0)
+
+    const { width, height } = annotationBoxSize(lines, trackWidth, localHeight)
+    const placement: AnnotationPlacement = hasManualOffset
+      ? 'top'
+      : chooseBestPlacement(localAnchorX, localAnchorY, width, height, trackWidth, localHeight)
+
+    const box = layoutAnnotationBox(
       localAnchorX,
       localAnchorY,
       lines,
       trackWidth,
       localHeight,
       placement,
+      Number.isFinite(annotation.labelOffsetX) ? annotation.labelOffsetX : 0,
+      Number.isFinite(annotation.labelOffsetY) ? annotation.labelOffsetY : 0,
     )
-    for (const candidatePlacement of ANNOTATION_PLACEMENTS) {
-      if (
-        !isPlacementWithinBounds(
-          localAnchorX,
-          localAnchorY,
-          lines,
-          trackWidth,
-          localHeight,
-          candidatePlacement,
-        )
-      ) {
-        continue
-      }
-      const candidate = layoutAnnotationBox(
-        localAnchorX,
-        localAnchorY,
-        lines,
-        trackWidth,
-        localHeight,
-        candidatePlacement,
-      )
-      if (
-        !containsPoint(candidate, localAnchorX, localAnchorY) &&
-        !placed.some((item) => overlaps(candidate, item))
-      ) {
-        box = candidate
-        placement = candidatePlacement
-        break
-      }
-    }
 
     const globalBox = {
       ...box,
@@ -428,8 +451,6 @@ export function layoutAnnotations(
       lineEndX: box.lineEndX + trackLeft,
       lineEndY: box.lineEndY + track.top,
     }
-    placed.push(box)
-    placedByTrack.set(track.index, placed)
     rendered.push({
       annotation,
       trackIndex: track.index,

src/components/core/layout.ts

@@ -52,18 +52,39 @@ function resolveAxisSides(axisCount: number): Array<'left' | 'right'> {
   return ['left']
 }
 
-// 缓存 axis groups 计算结果，避免重复计算
-const yAxisGroupsCache = new WeakMap<DisplayTrack, Map<WaveformOverlayMode, YAxisSeriesGroup[]>>()
+// Cache across recreated track objects without reusing groups whose axis-relevant data changed.
+const yAxisGroupsCache = new Map<string, Map<WaveformOverlayMode, YAxisSeriesGroup[]>>()
+const MAX_CACHE_SIZE = 100
+
+function getCacheKey(track: DisplayTrack): string {
+  return JSON.stringify([
+    track.id,
+    track.yDomain,
+    track.visibleSeries.map((series) => [
+      series.id,
+      series.name,
+      series.unit,
+      series.color,
+      series.yDomain,
+    ]),
+  ])
+}
 
 export function buildYAxisSeriesGroups(
   track: DisplayTrack,
   overlayMode: WaveformOverlayMode,
 ): YAxisSeriesGroup[] {
-  // 检查缓存
-  let trackCache = yAxisGroupsCache.get(track)
+  const cacheKey = getCacheKey(track)
+  let trackCache = yAxisGroupsCache.get(cacheKey)
   if (!trackCache) {
     trackCache = new Map()
-    yAxisGroupsCache.set(track, trackCache)
+    yAxisGroupsCache.set(cacheKey, trackCache)
+    if (yAxisGroupsCache.size > MAX_CACHE_SIZE) {
+      const firstKey = yAxisGroupsCache.keys().next().value
+      if (firstKey !== undefined) {
+        yAxisGroupsCache.delete(firstKey)
+      }
+    }
   }
 
   const cached = trackCache.get(overlayMode)

src/components/data/types.ts

@@ -9,6 +9,7 @@ export type {
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformInteractionMode,
+  WaveformZoomEndPayload,
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,

src/components/index.ts

@@ -7,6 +7,7 @@ export type {
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformInteractionMode,
+  WaveformZoomEndPayload,
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,

src/components/rendering/WaveformTrack.vue

@@ -3,18 +3,13 @@ import { computed, nextTick, onMounted, ref, watch } from 'vue'
 import { axisBottom, axisLeft, axisRight, select } from 'd3'
 import { formatAxisTime, formatScientificAxisLabel } from '../../utils'
 import type { WaveformFrameStyle } from '../../types'
-import type {
-  WaveformDisplayMode,
-  WaveformInteractionMode,
-  WaveformLegendPosition,
-} from '../data/types'
+import type { WaveformDisplayMode, WaveformInteractionMode } from '../data/types'
 import type {
   DisplaySeries,
   HoveredSeriesPoint,
   TrackLayout,
   WaveformYAxisLayout,
 } from '../core/types'
-import WaveformLegend from './WaveformLegend.vue'
 import WaveformSeriesLayer from './WaveformSeriesLayer.vue'
 
 interface Props {
@@ -42,16 +37,6 @@ interface Props {
   hoveredPoint?: HoveredSeriesPoint
   /** Y 轴标签回退值 */
   yLabel?: string
-  /** 多曲线图例位置 */
-  legendPosition?: WaveformLegendPosition
-  /** 多曲线图例排列方向 */
-  legendOrientation?: 'horizontal' | 'vertical'
-  /** 多曲线图例背景颜色 */
-  legendBackgroundColor?: string
-  /** 图例是否允许切换曲线显隐 */
-  legendInteractive?: boolean
-  /** 当前隐藏的系列 ID */
-  hiddenSeriesIds?: string[]
 }
 
 interface Emits {
@@ -59,16 +44,10 @@ interface Emits {
   (e: 'pointer-leave'): void
   (e: 'click', event: MouseEvent): void
   (e: 'contextmenu', event: MouseEvent): void
-  (e: 'series-visibility-toggle', seriesId: string): void
 }
 
 const props = withDefaults(defineProps<Props>(), {
   interactionMode: 'zoom',
-  legendPosition: 'top-right',
-  legendOrientation: 'vertical',
-  legendBackgroundColor: 'rgba(255, 255, 255, 0.7)',
-  legendInteractive: false,
-  hiddenSeriesIds: () => [],
 })
 const emit = defineEmits<Emits>()
 
@@ -445,19 +424,6 @@ watch(
     >
       暂无可见曲线
     </text>
-
-    <WaveformLegend
-      v-if="!track.isEmpty && track.legendSeries.length > 1"
-      :series="track.legendSeries"
-      :position="legendPosition"
-      :orientation="legendOrientation"
-      :background-color="legendBackgroundColor"
-      :interactive="legendInteractive"
-      :hidden-series-ids="hiddenSeriesIds"
-      :width="track.width ?? innerWidth"
-      :height="track.height"
-      @toggle="emit('series-visibility-toggle', $event)"
-    />
   </g>
 </template>
 

src/components/utils/useAnimationFrameThrottle.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { useAnimationFrameThrottle } from './useAnimationFrameThrottle'
+
+describe('useAnimationFrameThrottle', () => {
+  it('schedules callback on next animation frame', () => {
+    const throttle = useAnimationFrameThrottle()
+    const callback = vi.fn()
+
+    throttle.schedule(callback)
+    expect(throttle.isPending()).toBe(true)
+    expect(callback).not.toHaveBeenCalled()
+  })
+
+  it('replaces pending callback when scheduled multiple times', () => {
+    const throttle = useAnimationFrameThrottle()
+    const callback1 = vi.fn()
+    const callback2 = vi.fn()
+
+    throttle.schedule(callback1)
+    throttle.schedule(callback2)
+    expect(throttle.isPending()).toBe(true)
+  })
+
+  it('cancels pending callback', () => {
+    const throttle = useAnimationFrameThrottle()
+    const callback = vi.fn()
+
+    throttle.schedule(callback)
+    throttle.cancel()
+    expect(throttle.isPending()).toBe(false)
+  })
+
+  it('flushes callback immediately', () => {
+    const throttle = useAnimationFrameThrottle()
+    const callback = vi.fn(() => 'result')
+
+    throttle.schedule(callback)
+    throttle.flush()
+    expect(callback).toHaveBeenCalled()
+    expect(throttle.isPending()).toBe(false)
+  })
+
+  it('handles flush when no callback is pending', () => {
+    const throttle = useAnimationFrameThrottle()
+    expect(() => throttle.flush()).not.toThrow()
+  })
+
+  it('handles cancel when no callback is pending', () => {
+    const throttle = useAnimationFrameThrottle()
+    expect(() => throttle.cancel()).not.toThrow()
+  })
+})

src/components/utils/useAnimationFrameThrottle.ts

@@ -0,0 +1,56 @@
+/**
+ * 创建一个基于 requestAnimationFrame 的节流工具
+ * 用于合并多个快速连续的调用到单个动画帧中
+ */
+export function useAnimationFrameThrottle<T = void>() {
+  let frameHandle: number | null = null
+  let pendingCallback: (() => T) | null = null
+
+  /**
+   * 调度一个回调在下一个动画帧中执行
+   * 如果已经有待处理的帧，则替换待处理的回调
+   */
+  function schedule(callback: () => T): void {
+    pendingCallback = callback
+    if (frameHandle !== null) return
+
+    frameHandle = requestAnimationFrame(() => {
+      frameHandle = null
+      const cb = pendingCallback
+      pendingCallback = null
+      cb?.()
+    })
+  }
+
+  /**
+   * 取消待处理的动画帧调度
+   */
+  function cancel(): void {
+    pendingCallback = null
+    if (frameHandle === null) return
+    cancelAnimationFrame(frameHandle)
+    frameHandle = null
+  }
+
+  /**
+   * 立即执行待处理的回调（如果有）
+   */
+  function flush(): void {
+    if (frameHandle !== null) {
+      cancelAnimationFrame(frameHandle)
+      frameHandle = null
+    }
+    const cb = pendingCallback
+    pendingCallback = null
+    cb?.()
+  }
+
+  /**
+   * 检查是否有待处理的调度
+   */
+  function isPending(): boolean {
+    return frameHandle !== null
+  }
+
+  return { schedule, cancel, flush, isPending }
+}

src/core/rendering.ts

@@ -1,6 +1,6 @@
 import { bisector } from 'd3'
 
-import type { WaveformPoint, WaveformRenderingOptions } from '../types'
+import type { WaveformPoint, WaveformRenderingOptions } from '@/types'
 
 export interface ResolvedWaveformRenderingOptions {
   downsample: boolean

src/index.ts

@@ -13,6 +13,7 @@ export type {
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformInteractionMode,
+  WaveformZoomEndPayload,
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,

src/types/chart.ts

@@ -26,6 +26,14 @@ export type WaveformOverlayMode = 'single-axis' | 'multi-axis'
 /** 标注工具模式 */
 export type WaveformInteractionMode = 'zoom' | 'annotation'
 
+/** Describes the X-axis viewport after a zoom gesture completes. */
+export interface WaveformZoomEndPayload {
+  start: number
+  end: number
+  trackIndex?: number
+  seriesIds?: string[]
+}
+
 /** 标注颜色样式 */
 export interface WaveformAnnotationStyle {
   borderColor?: string
@@ -40,6 +48,10 @@ export interface WaveformAnnotation {
   x: number
   y: number
   text: string
+  /** Pixel offset of the label box from its default position. */
+  labelOffsetX?: number
+  /** Pixel offset of the label box from its default position. */
+  labelOffsetY?: number
   style?: WaveformAnnotationStyle
   createdAt?: string
 }

src/types/index.ts

@@ -8,6 +8,7 @@ export type {
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformInteractionMode,
+  WaveformZoomEndPayload,
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,