@quantlife/qlchart 0.0.1

package/doc/guide/architecture.md

@@ -0,0 +1,87 @@
+# 架构总览
+
+QLChart 采用四层架构设计，从底层到上层依次为：
+
+```
+┌─────────────────────────────────────────────┐
+│              Components 层                   │
+│   QLChartProvider / QLChartPanel / QLToolbar │
+├─────────────────────────────────────────────┤
+│               Hooks 层                       │
+│   useChart / useTheme / useDrawingModule     │
+├─────────────────────────────────────────────┤
+│              Core 层                         │
+│   ChartManager / SeriesManager / ThemeManager│
+├─────────────────────────────────────────────┤
+│             Plugins 层                       │
+│   DrawingAdapter / IndicatorRenderer / ...   │
+└─────────────────────────────────────────────┘
+```
+
+## 各层职责
+
+### Core 层（核心引擎）
+
+直接操作 `lightweight-charts` API，提供底层能力。
+
+| 模块 | 职责 |
+|------|------|
+| **ChartManager** | 管理 `IChartApi` 实例的创建、销毁、配置更新 |
+| **SeriesManager** | 管理 Series 的增删改查，支持主序列和叠加序列 |
+| **ThemeManager** | 主题切换，内置暗色/亮色预设 |
+| **PaneManager** | 多窗格管理（主图 + 副图指标） |
+| **DataManager** | 数据转换和缓存 |
+
+### Plugins 层（功能插件）
+
+独立的功能模块，通过 Adapter 模式与 Core 层交互。
+
+| 插件 | 功能 |
+|------|------|
+| **DrawingAdapter** | 21种绘图工具，基于 `lightweight-charts-drawing` |
+| **DrawingPersistence** | 绘图数据后端存储/恢复 |
+| **IndicatorRenderer** | 技术指标渲染（MA/EMA/MACD/RSI/KDJ等） |
+| **ReplayController** | K线回放控制 |
+| **ScreenshotHelper** | 图表截图 |
+
+### Hooks 层（React 绑定）
+
+将 Core + Plugins 封装为 React Hooks，提供响应式状态管理。
+
+| Hook | 功能 |
+|------|------|
+| `useChart` | 创建和管理 Chart 实例 |
+| `useTheme` | 主题状态管理 |
+| `useDrawingModule` | 绘图模块集成 |
+| `useCrosshairSync` | 多面板光标同步 |
+
+### Components 层（UI 组件）
+
+面向使用者的 React 组件，组合 Hooks 和 Plugins。
+
+| 组件 | 功能 |
+|------|------|
+| `QLChartProvider` | 顶层 Provider，提供全局配置 |
+| `QLChartPanel` | 核心图表面板 |
+| `QLToolbar` | 工具栏（周期切换/序列类型/主题） |
+| `QLChartLayout` | 多面板布局容器 |
+| `DrawingModule` | 绘图工具UI |
+| `IndicatorTag` | 指标标签 |
+
+## 状态管理
+
+QLChart 使用 **Zustand** 进行状态管理，分为三个 Store：
+
+- **useChartStore** — 图表全局状态（活跃面板、周期、序列类型等）
+- **useDrawingStore** — 绘图工具状态（当前工具、磁铁、选中绘图）
+- **useIndicatorStore** — 指标状态（活跃指标列表）
+
+## 数据流
+
+```
+用户操作 → Component → Hook → Core/Plugin → lightweight-charts → Canvas渲染
+                ↕                    ↕
+              Store              fetchFn/API
+```
+
+详细数据流参考 [数据流文档](./data-flow)。

package/doc/guide/data-flow.md

@@ -0,0 +1,310 @@
+# 数据流
+
+## 概述
+
+QLChart 的数据流遵循单向数据流原则，支持 v1（Demo/Mock）和 v2（后端就绪后启用）两种数据格式。
+
+```
+[后端API / MockDataService]
+        │
+        ▼
+   fetchFn(params)
+        │
+        ▼
+[QLChartPanel.loadData()]
+        │
+        ├── v1格式? ──→ dataTransformer ──→ SeriesManager.setData()
+        │
+        └── v2格式? ──→ IndicatorDataProcessor.parse()
+                            │
+                            ├── candlestick/volume → SeriesManager
+                            ├── overlayIndicators → IndicatorRenderer (overlay)
+                            └── paneIndicators → IndicatorRenderer (pane)
+                                                                    │
+                                                                    ▼
+                                                           [lightweight-charts Canvas]
+```
+
+---
+
+## 数据格式规范
+
+### v1 格式（当前 Demo 使用）
+
+简单的对象数组，每根K线包含 time（毫秒时间戳）和 OHLCV 字段：
+
+```json
+{
+  "data": [
+    {
+      "time": 1718424000000,
+      "open": 42000.5,
+      "high": 42150.2,
+      "low": 41980.1,
+      "close": 42120.8,
+      "volume": 12500
+    },
+    {
+      "time": 1718427600000,
+      "open": 42120.8,
+      "high": 42200.0,
+      "low": 42050.3,
+      "close": 42180.5,
+      "volume": 9800
+    }
+  ]
+}
+```
+
+**特点：**
+- `time` 为**毫秒级** UNIX 时间戳
+- 数据转换器 `transformCandlestickData` 会自动转为 lightweight-charts 所需的**秒级**时间戳
+- 指标数据由前端 `MockIndicatorService` 本地计算
+
+### v2 格式（新架构，后端就绪后启用）
+
+行列混合紧凑格式，减少传输量，支持后端预计算指标：
+
+```json
+{
+  "timestamps": [1718424000000, 1718427600000],
+  "data": [
+    [42000.5, 42150.2, 41980.1, 42120.8, 12500, 41800.3, 42000.1],
+    [42120.8, 42200.0, 42050.3, 42180.5, 9800, 41900.5, 42100.2]
+  ],
+  "ohlcIndex": { "open": 0, "high": 1, "low": 2, "close": 3, "volume": 4 },
+  "indicators": [
+    {
+      "key": "MA5",
+      "label": "MA(5)",
+      "displayType": "overlay",
+      "lines": [
+        { "key": "ma", "label": "MA5", "dataIndex": 5, "renderType": "line", "color": "#FF6D00" }
+      ]
+    },
+    {
+      "key": "MACD",
+      "label": "MACD(12,26,9)",
+      "displayType": "pane",
+      "lines": [
+        { "key": "dif", "label": "DIF", "dataIndex": 6, "renderType": "line", "color": "#2962FF" },
+        { "key": "dea", "label": "DEA", "dataIndex": 7, "renderType": "line", "color": "#FF6D00" },
+        { "key": "macd", "label": "MACD", "dataIndex": 8, "renderType": "histogram", "color": "#26a69a" }
+      ],
+      "paneHeightRatio": 0.2
+    }
+  ],
+  "version": 2
+}
+```
+
+**特点：**
+- `timestamps` 和 `data` 平行数组，每行对应一个时间点的所有值
+- `ohlcIndex` 映射 OHLCV 字段在 data 行中的列位置
+- `indicators` 定义指标如何从 data 行中提取和渲染
+- `IndicatorDataProcessor` 负责解析 v2 格式并分发到 SeriesManager / IndicatorRenderer
+
+### 版本兼容机制
+
+```
+fetchFn 返回结果
+      │
+      ├── result.version === 2 或 result.timestamps 存在？
+      │     ├── 是 → IndicatorDataProcessor.parse(result)  [v2 路径]
+      │     └── 否 → transformCandlestickData(result.data)  [v1 路径]
+```
+
+两种格式可共存，由返回数据中的 `version` 字段或 `timestamps` 数组自动判断。
+
+---
+
+## 数据流转详解
+
+### 1. K线 + 成交量数据流
+
+```
+QLChartPanel.loadData()
+      │
+      ├── fetchFn({ pairId, product, period })
+      │
+      ▼
+      result.data (CandlestickRawData[])
+      │
+      ├── transformCandlestickData(result.data)  → 毫秒→秒级时间戳
+      │
+      ├── transformVolumeData(result.data)       → 涨跌着色
+      │
+      ▼
+      SeriesManager
+      │
+      ├── addMainSeries(Candlestick) → mainSeries.setData(candlestickData)
+      │
+      └── addOverlaySeries(Histogram, 'volume') → volumeSeries.setData(volumeData)
+                                                     │
+                                                     ▼
+                                              chart.priceScale('volume').applyOptions(
+                                                scaleMargins: { top: 0.8, bottom: 0 }
+                                              )
+```
+
+### 2. 指标数据流
+
+#### v1 路径（前端 Mock）
+
+```
+useIndicatorStore.activeIndicators 变化
+      │
+      ▼
+QLChartPanel effect 触发
+      │
+      ├── MockIndicatorService.generate({ name, count })
+      │
+      ▼
+      IndicatorRenderer.renderIndicator(indicator, mockData)
+      │
+      ├── displayType === 'overlay' → OverlayIndicator → 主图叠加
+      │
+      └── displayType === 'pane'   → PaneIndicator → LWC v5 原生 pane 子图
+```
+
+#### v2 路径（后端预计算）
+
+```
+fetchFn 返回 v2 格式
+      │
+      ▼
+IndicatorDataProcessor.parse(result)
+      │
+      ├── 提取 candlestick/volume → 走 SeriesManager 标准流程
+      │
+      └── 遍历 result.indicators
+            │
+            ├── displayType === 'overlay' → IndicatorRenderer 渲染到主图
+            │
+            └── displayType === 'pane'   → IndicatorRenderer 渲染到 pane 子图
+                                              (paneHeightRatio 控制高度比)
+```
+
+### 3. 绘图持久化数据流
+
+```
+                    ─── 绘制阶段 ──
+用户鼠标操作 → DrawingManager → DrawingAdapter
+                                    │
+                                    ▼
+                          DrawingAdapter.exportDrawings()
+                                    │
+                                    ▼
+                          DrawingPersistence.autoSave()
+                                    │
+                                    ├── apiBaseUrl 存在 → POST /api/drawings/save
+                                    │                     { chartId, drawings[] }
+                                    │
+                                    └── apiBaseUrl 为空 → localStorage
+                                                          key: `qlchart-drawings-${chartId}`
+
+                    ── 加载阶段 ──
+QLChartPanel 数据加载完成 (dataLoaded: true)
+      │
+      ▼
+useDrawingModule effect → DrawingAdapter.attach(chart, series, container)
+      │
+      ▼
+DrawingPersistence.load()
+      │
+      ├── apiBaseUrl 存在 → GET /api/drawings/load?chartId=xxx
+      │
+      └── apiBaseUrl 为空 → localStorage.getItem(...)
+      │
+      ▼
+DrawingAdapter.importDrawings(data)
+      │
+      ▼
+DrawingManager → 恢复所有绘图到 Canvas
+```
+
+### 4. 回放数据流
+
+```
+KlineReplay.load(allData)     ← 预加载完整K线数据
+      │
+      ▼
+KlineReplay.play()            ← 开始回放
+      │
+      ├── series.setData([allData[0]])   ← 只显示第一根
+      │
+      └── setInterval ──→ series.update(allData[i])  ← 逐根追加
+                              │
+                              ▼
+                        onProgress(current, total) → ReplayController 进度更新
+
+KlineReplay.pause()           ← clearInterval，暂停在当前K线
+KlineReplay.next()/prev()     ← 手动单步前进/后退
+KlineReplay.stop()            ← 停止回放，恢复全量数据 setData(allData)
+```
+
+---
+
+## 核心模块职责
+
+| 模块 | 职责 |
+|------|------|
+| **QLChartPanel** | 数据加载编排，协调各模块，管理生命周期 |
+| **DataManager** | 数据缓存、请求去重、参数管理 |
+| **RealtimeDataFeed** | 实时增量数据推送，通过 LWC series.update() 更新图表 |
+| **SeriesManager** | 序列注册/销毁，序列引用管理 |
+| **IndicatorDataProcessor** | v2 格式数据解析，指标数据提取分发 |
+| **IndicatorRenderer** | 指标渲染到主图(overlay)或副图(pane) |
+| **DrawingAdapter** | 绘图创建/选择/拖拽/持久化的桥接层 |
+| **DrawingPersistence** | 绘图数据存储（API/localStorage） |
+| **KlineReplay** | K线逐根回放引擎 |
+| **ThemeManager** | 主题切换，映射到 chart options |
+
+---
+
+## 状态同步机制
+
+Zustand Store 在数据流中扮演协调角色：
+
+| Store | 关键状态 | 作用 |
+|-------|---------|------|
+| **useChartStore** | `activePeriod` | 变化触发 `loadData` 重执行，获取新周期数据 |
+| **useChartStore** | `activeSeriesType` | K线类型切换，影响 `addMainSeries` 参数 |
+| **useChartStore** | `activePanelId` | 多面板布局中标识当前操作目标面板 |
+| **useDrawingStore** | `activeTool` | 变化通过 `useDrawingModule` 传递给 DrawingAdapter |
+| **useDrawingStore** | `selectedDrawingId` | 当前选中绘图，驱动属性面板显示 |
+| **useIndicatorStore** | `activeIndicators` | 变化触发指标重新渲染 |
+| **useReplayStore** | `isReplayMode` | 控制回放控制器显示/隐藏 |
+
+### 数据重载场景
+
+切换周期/品种时：
+
+```
+1. period/seriesType 变化 → loadData useCallback 依赖变化
+2. seriesManager.clearAll()        // 清空旧序列
+3. fetchFn(newParams)              // 获取新数据
+4. addMainSeries() + setData()     // 新序列渲染
+5. DrawingAdapter.updateSeries()   // 同步series引用（防御性修复）
+6. DrawingAdapter.setCandleData()  // 更新磁铁吸附数据
+```
+
+---
+
+## API 接口规范（后端就绪后参考）
+
+### K线数据请求
+
+```
+GET /api/chart/kline?pairId=BTCUSDT&product=digital_currency&period=1h&count=500
+```
+
+### 绘图持久化
+
+```
+POST /api/drawings/save
+Body: { chartId: string, drawings: DrawingPersistData[] }
+
+GET /api/drawings/load?chartId=xxx
+Response: { drawings: DrawingPersistData[] }
+```

package/doc/guide/deployment.md

@@ -0,0 +1,59 @@
+# 部署与发布
+
+## 构建库
+
+```bash
+pnpm build
+# 输出: dist/qlchart.js + dist/style.css + dist/index.d.ts
+```
+
+### 独立构建（用于demo部署）
+
+```bash
+pnpm build:standalone
+```
+
+## 构建文档
+
+```bash
+# 仅 VitePress
+pnpm docs:build
+
+# 仅 TypeDoc API Reference
+pnpm docs:api
+
+# 完整文档（TypeDoc + VitePress）
+pnpm docs:all
+```
+
+文档输出到 `doc/.vitepress/dist/`。
+
+## 本地预览文档
+
+```bash
+pnpm docs:dev    # 开发模式，热更新
+pnpm docs:preview # 预览构建结果
+```
+
+## 发布到 npm
+
+```bash
+# 1. 更新版本号
+npm version patch  # 或 minor / major
+
+# 2. 构建
+pnpm build
+
+# 3. 发布
+npm publish --access public
+```
+
+## Demo 部署
+
+```bash
+# 启动 demo 开发服务器
+pnpm demo
+
+# 构建 demo（用于静态部署）
+pnpm build:standalone
+```

package/doc/guide/drawing-properties.md

@@ -0,0 +1,40 @@
+# 绘图工具属性系统
+
+QLChart 为19种绘图工具定义了差异化的属性模板，用户可通过属性面板修改每种工具的渲染样式。
+
+## 架构
+
+```
+DrawingPropertyTemplates (模板定义)
+    ↓
+getPropertyTemplate(toolType) → PropertyField[]
+    ↓
+DrawingPropertyPanel (动态渲染UI控件)
+```
+
+## 属性字段类型
+
+| 类型 | UI控件 | 说明 |
+|------|--------|------|
+| `color` | Color Picker | 颜色选择 |
+| `range` | Slider | 数值范围 |
+| `toggle` | Checkbox | 开关 |
+| `select` | Dropdown | 下拉选择 |
+
+## 工具属性差异
+
+不同工具有不同的属性组合：
+
+- **线条类**（趋势线/水平线/射线）：线条颜色、线宽、样式、延伸
+- **形状类**（矩形/圆/三角形）：线条颜色、线宽、填充色、透明度
+- **斐波那契**：线条颜色、填充透明度、标签显示
+- **仓位类**（多头/空头）：颜色主题固定（绿/红）、填充透明度
+
+## 使用
+
+```typescript
+import { getPropertyTemplate } from '@quantlife/qlchart'
+
+const template = getPropertyTemplate('rectangle')
+// template.fields = [lineColor, lineWidth, fillColor, fillOpacity, showLabels]
+```

package/doc/guide/getting-started.md

@@ -0,0 +1,94 @@
+# 快速开始
+
+## 安装
+
+```bash
+pnpm add @quantlife/qlchart
+```
+
+### Peer Dependencies
+
+QLChart 依赖以下库，请确保已安装：
+
+```bash
+pnpm add react react-dom lightweight-charts lightweight-charts-drawing zustand
+```
+
+## 最小示例
+
+```tsx
+import { QLChartProvider, QLChartPanel } from '@quantlife/qlchart'
+import '@quantlife/qlchart/dist/style.css'
+
+// 定义数据获取函数
+async function fetchFn(params: { pairId: string; product: string; period: string }) {
+  const res = await fetch(`/api/klines?${new URLSearchParams(params)}`)
+  return res.json()
+}
+
+function App() {
+  return (
+    <QLChartProvider config={{ fetchFn, defaultTheme: 'dark' }}>
+      <QLChartPanel
+        pairId="BTCUSDT"
+        product="digital_currency"
+        period="1h"
+        showToolbar
+      />
+    </QLChartProvider>
+  )
+}
+```
+
+## 数据格式
+
+`fetchFn` 返回的数据格式：
+
+```typescript
+interface CandlestickRawData {
+  time: number      // 毫秒时间戳
+  open: number
+  high: number
+  low: number
+  close: number
+  volume?: number
+}
+
+// 返回格式
+{
+  data: CandlestickRawData[]
+}
+```
+
+## 核心 Props
+
+### QLChartProvider
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `fetchFn` | `(params) => Promise<{ data: CandlestickRawData[] }>` | ✅ | K线数据获取函数 |
+| `defaultTheme` | `'dark' \| 'light'` | ❌ | 默认主题，默认 `'dark'` |
+| `apiBaseUrl` | `string` | ❌ | 绘图持久化API地址 |
+| `cacheEnabled` | `boolean` | ❌ | 是否启用数据缓存，默认 `true` |
+| `cacheTTL` | `number` | ❌ | 缓存TTL（毫秒），默认 `300000`（5分钟） |
+| `realtimeSubscribe` | `RealtimeSubscribeFn` | ❌ | 实时数据订阅函数（WebSocket场景） |
+
+### QLChartPanel
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `pairId` | `string` | ✅ | 交易对ID |
+| `product` | `string` | ✅ | 产品类型 |
+| `period` | `string` | ❌ | K线周期，默认 `'1h'` |
+| `seriesType` | `SeriesType` | ❌ | 图表类型，默认 `Candlestick` |
+| `showToolbar` | `boolean` | ❌ | 是否显示工具栏，默认 `true` |
+| `panelId` | `string` | ❌ | 面板ID（多面板场景必传） |
+
+## 下一步
+
+- [架构总览](./architecture) — 了解QLChart的四层架构
+- [QLChartProvider](../components/qlchart-provider) — Provider配置详解
+- [QLChartPanel](../components/qlchart-panel) — 主面板组件
+- [Standalone JS](../examples/standalone-js) — 纯JS使用方式
+- [实时数据更新](../examples/realtime-data) — WebSocket增量推送
+- [数据格式指南](../examples/data-format-guide) — 时间戳与数据转换

package/doc/guide/pane-system.md

@@ -0,0 +1,47 @@
+# 副图系统
+
+QLChart 使用 lightweight-charts v5 原生 pane 系统支持多面板图表。
+
+## 架构
+
+```
+主Chart (pane 0)
+├── K线序列
+├── 成交量序列 (priceScaleId: 'volume')
+├── Overlay指标 (MA/EMA/BOLL)
+├── 副图pane 1 — MACD
+├── 副图pane 2 — RSI
+└── 共享时间轴
+```
+
+**优势：** 不再使用独立的PaneChartPanel，所有series在同一个Chart实例中，时间轴天然同步。
+
+## 使用
+
+副图指标通过 `IndicatorRenderer` 自动管理：
+
+```typescript
+// 添加MACD指标时，IndicatorRenderer会自动：
+// 1. 分配pane索引（1, 2, 3...）
+// 2. 使用 chart.addSeries(def, opts, paneIndex) 添加到指定pane
+// 3. 设置pane高度比例
+```
+
+## Pane高度调整
+
+使用 `PaneDivider` 组件拖拽调整主图/副图比例：
+
+```tsx
+import { PaneDivider } from '@quantlife/qlchart'
+
+<PaneDivider index={1} onDrag={(delta) => adjustRatio(delta)} />
+```
+
+## PaneManager API
+
+| 方法 | 说明 |
+|------|------|
+| `addIndicatorPane(name, ratio)` | 创建新pane，返回paneIndex |
+| `removePane(index)` | 移除pane |
+| `setPaneHeight(index, ratio)` | 设置pane高度比例 |
+| `getPanes()` | 获取所有pane信息 |

package/doc/guide/theme-switching.md

@@ -0,0 +1,58 @@
+# 主题切换
+
+## 内置主题
+
+QLChart 内置暗色和亮色两种主题。
+
+### 暗色主题（默认）
+
+```tsx
+<QLChartProvider config={{ defaultTheme: 'dark' }}>
+```
+
+### 亮色主题
+
+```tsx
+<QLChartProvider config={{ defaultTheme: 'light' }}>
+```
+
+## 运行时切换
+
+通过 `useTheme` Hook 在运行时切换主题：
+
+```tsx
+import { useTheme } from '@quantlife/qlchart'
+
+function ThemeSwitcher() {
+  const { theme, setTheme } = useTheme()
+
+  return (
+    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+      当前: {theme} → 切换
+    </button>
+  )
+}
+```
+
+## QLToolbar 切换
+
+如果启用了工具栏 (`showToolbar={true}`)，用户可通过工具栏上的主题按钮切换。
+
+## 自定义主题
+
+通过修改 `themePresets.ts` 中的预设配置自定义颜色：
+
+```typescript
+// src/utils/themePresets.ts
+export const darkTheme: DeepPartial<ChartOptions> = {
+  layout: {
+    background: { color: '#131722' },
+    textColor: '#d1d4dc',
+  },
+  grid: {
+    vertLines: { color: '#1e222d' },
+    horzLines: { color: '#1e222d' },
+  },
+  // ... 更多配置
+}
+```