# stock-chart-workspace

**Repository Path**: etimeman20/stock-chart-workspace

## Basic Information

- **Project Name**: stock-chart-workspace
- **Description**: 股票图表组件仓库：M1 主链路、第一阶段指标与 AI 辅助分析 demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 股票图表组件仓库（M1 + 第一阶段指标 + AI 辅助分析）

基于 `股票图表组件开发文档.md` 落地的 **M1 主链路 + 第一阶段指标版本**。当前仓库已经具备可运行的演示应用、可复用的数据模型、`lightweight-charts` 适配层、框架无关的图表核心层、内置指标引擎，以及面向 React 的组件 / Hook / SDK 入口。

## 当前已实现

- 共享市场数据契约、运行时校验与 K 线 patch 处理
- `lightweight-charts` 适配层与主图 / 副图 pane 编排
- 图表核心控制器：数据更新、可视范围、重置、导图、交互开关、指标生命周期
- 第一阶段内置指标：`MA`、`EMA`、`VOL`、`MACD`、`KDJ`、`RSI`、`BOLL`
- AI 辅助分析：多模型预测线、未来预测 K 线 / 预测量能、历史与未来买卖点
- React 入口：`StockChart`、`createStockChart`、`useStockChart`，均已暴露指标 API
- 确定性 M1 测试 / 演示数据工厂
- 本地 demo（组件 / Hook / SDK 三种接入面 + 指标演示）、基础单测、组件测试和工作区脚本

## 当前范围

### 当前已覆盖

- 主图 K 线渲染
- 初始化数据与增量更新
- 可视范围读取 / 设置
- `reset()` / `resetView()`
- `resize()` / `exportImage()`
- `enableCrosshair` / `enableZoom` / `enablePan`
- `onLoadMore`、`onVisibleRangeChange`、`onCrosshairMove` 等基础事件
- 第一阶段指标引擎与多 pane 渲染
- `setIndicators()` / `addIndicator()` / `updateIndicator()` / `removeIndicator()` / `setPaneConfig()`
- `setPredictions()` / `setForecastCandles()` / `setTradeSignals()`

### 暂未进入本轮

- 绘图工具与交互编辑
- 公式编译器
- 第二阶段及之后的指标目录
- 完整的视觉回归用例矩阵

## 环境要求

- Node.js `>= 20`
- Corepack
- `pnpm@9.15.0`

下文命令统一使用 `corepack pnpm`。

## 快速开始

```bash
corepack enable
corepack pnpm install
corepack pnpm dev
```

默认会启动 `apps/demo`，方便直接查看当前 M1 主链路、第一阶段指标与 AI 辅助分析效果。

## 演示截图

首页直接展示当前 demo 的四个主要接入面和两类高价值场景，方便在仓库页快速预览实际效果。

<p align="center">
  <img src="./docs/images/demo-props-api.png" alt="Props API 演示" width="48%" />
  <img src="./docs/images/demo-hook-api.png" alt="Hook API 演示" width="48%" />
</p>

<p align="center">
  <img src="./docs/images/demo-sdk-api.png" alt="SDK API 演示" width="48%" />
  <img src="./docs/images/demo-ai-signals.png" alt="AI 辅助分析演示" width="48%" />
</p>

<p align="center">
  <img src="./docs/images/chart-with-indicators.png" alt="全指标多 Pane 图表" width="48%" />
  <img src="./docs/images/ai-chart-forecast.png" alt="AI 预测与买卖点叠加" width="48%" />
</p>

更完整的截图说明、API 示例和接入方式说明见 [docs/usage-guide.md](./docs/usage-guide.md)。

## 工作区结构

| 路径 | 说明 |
| --- | --- |
| `apps/demo` | Vite + React 功能展示页，覆盖 `StockChart`、`useStockChart`、`createStockChart` 三种接入面 |
| `packages/market-data-model` | 共享类型、错误模型、运行时校验、K 线 patch 处理 |
| `packages/chart-adapter-lwc` | `lightweight-charts` 适配层、辅助序列和多 pane 渲染 |
| `packages/indicator-engine` | 内置指标注册表、指标计算与渲染模型输出 |
| `packages/chart-core` | 框架无关的图表核心控制器与指标编排 |
| `packages/ui-react` | React 组件、Hook 与命令式创建入口 |
| `packages/test-data-factory` | 确定性的 M1 K 线与实时 patch 夹具 |
| `packages/visual-regression` | 视觉回归基线包，目前仍是骨架形态 |
| `股票图表组件开发文档.md` | 完整产品 / 接口规格文档 |

## 常用命令

| 命令 | 作用 |
| --- | --- |
| `corepack pnpm dev` | 启动 demo |
| `corepack pnpm build` | 构建全部工作区包 |
| `corepack pnpm lint` | 运行全部 ESLint 检查 |
| `corepack pnpm typecheck` | 运行全部 TypeScript 检查 |
| `corepack pnpm test` | 运行全部单元测试 |
| `corepack pnpm test:ct` | 运行 `ui-react` 组件测试 |
| `corepack pnpm test:e2e` | 运行 demo 的 Playwright e2e |
| `corepack pnpm test:visual` | 运行视觉回归包测试 |
| `corepack pnpm test:smoke` | 执行 lint + typecheck + test + component test |
| `corepack pnpm perf` | 运行 demo 性能脚本 |

## 最小使用示例

```tsx
import { StockChart } from 'ui-react'
import { createM1Candles, M1_TIMEFRAME } from 'test-data-factory'

const candles = createM1Candles({
  count: 120,
  seed: 2025,
})

export function Example() {
  return (
    <StockChart
      symbol="600519"
      timeframe={M1_TIMEFRAME}
      data={candles}
      style={{ minHeight: 360 }}
    />
  )
}
```

如果你需要命令式控制，也可以使用 `createStockChart(container, options)` 或 `useStockChart(options)`；三种入口都支持指标、pane 配置，以及 AI 预测 / 买卖点数据注入。

## 深入阅读

- **[📖 使用指南（推荐）](./docs/usage-guide.md)** — 完整的安装、接入、API、指标、AI 预测教程（含演示截图）
- [完整规格文档](./股票图表组件开发文档.md)
- [demo 说明](./apps/demo/README.md)
- [ui-react](./packages/ui-react/README.md)
- [chart-core](./packages/chart-core/README.md)
- [chart-adapter-lwc](./packages/chart-adapter-lwc/README.md)
- [market-data-model](./packages/market-data-model/README.md)
- [test-data-factory](./packages/test-data-factory/README.md)
- [visual-regression](./packages/visual-regression/README.md)

## 当前限制

- 当前仍是 **M1 主链路 + 第一阶段指标 + 第一波 AI 辅助分析**，目标是先打通真实图表主链路、首批常用指标与可落地的预测展示，而不是一次覆盖全部产品功能。
- demo 主要使用 `test-data-factory` 生成的确定性数据，不代表真实行情接入方案已经完成。
- `visual-regression` 包已预留，但还没有形成完整的快照基线与 CI 流程。