# quant-platform-d1

**Repository Path**: asialiu66/quant-platform-d1

## Basic Information

- **Project Name**: quant-platform-d1
- **Description**: d1量化平台，配合d1框架（目前开源版已停更）
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 3
- **Created**: 2026-05-12
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# D1 量化交易平台

面向 `quant-test-d1-pro` 的本地量化研究与交易管理平台。前端使用 Vue 3、TypeScript 和 Vite，后端使用 FastAPI；平台负责工作流编排、策略构建、回测分析、代码库管理、实盘与数据服务控制。

## 文档导航

| 文档 | 用途 |
| --- | --- |
| [CHANGELOG.md](./CHANGELOG.md) | 版本变更记录 |
| [CONTRIBUTING.md](./CONTRIBUTING.md) | 贡献者开发指南（环境、命令、规范、提交流程） |
| [SECURITY.md](./SECURITY.md) | 安全模型与已实现的安全机制 |
| [backend/README.md](./backend/README.md) | 后端架构、启动流程、配置与数据存储详解 |
| [AGENTS.md](./AGENTS.md) | AI 编码代理的工作约定 |

## 核心能力

- **工作流**：编排因子计算、选股、回测等步骤，通过 SSE 实时展示状态、进度和日志。
- **回测分析**：查看绩效指标、净值曲线、年度/月度收益、交易记录和个股买卖点，并对比多个策略。
- **策略构建器**：使用可视化向导或 CodeMirror 编辑器创建、配置和回测策略。
- **策略库**：浏览、搜索和维护因子、财务因子、选股策略及择时/风控信号。
- **数据服务监控**：连接独立运行的 QMT / DuckDB 服务，查看实时链路、回补工作流和问题诊断；可选由平台托管外部进程。
- **数据浏览器**：通过 DuckDB Flight 执行受限的只读 SQL，独立浏览行情表和查询结果。
- **工具库数据浏览器**：在白名单根目录（数据、因子、策略缓存、回测结果）下浏览与分页预览数据文件。
- **实盘交易**：连接 QMT 实盘采集与 DuckDB 查询代理，提供实盘服务托管、账户与策略收益、历史清仓盈亏、指数分钟 K 线和执行滑点分析；可选由平台托管外部进程。
- **运行设置**：配置量化项目、Python 解释器、数据服务、远程访问令牌和界面主题。

## 技术栈

| 层面 | 技术 |
| --- | --- |
| 前端 | Vue 3.5+、TypeScript 5.7+、Vite 6+ |
| 状态与路由 | Pinia 2+、Vue Router 4+ |
| UI 与图表 | Element Plus 2.9+、ECharts 6.1+、CodeMirror 6 |
| 后端 | FastAPI、Polars、SQLite、Alembic |
| 测试 | Vitest、jsdom、Pytest |

## 环境要求

- Node.js 与 npm（版本应满足 `package.json` 中依赖的安装要求）。
- Conda 环境 `quantpy312`；也可以在设置中显式指定兼容的 Python 解释器。
- 可访问的 `quant-test-d1-pro` 项目目录。

## 快速开始

1. 安装前后端依赖：

   ```powershell
   npm install
   conda run -n quantpy312 python -m pip install -r backend/requirements.lock.txt
   ```

2. 检查 `backend/settings.json`，至少确认 `quant_proj` 指向本机的 `quant-test-d1-pro` 根目录。可参考 `backend/settings.example.json` 配置其他机器相关路径。

3. 启动前后端：

   ```powershell
   npm run dev:all
   ```

   也可以在两个终端中分别运行 `npm run dev:backend` 和 `npm run dev`。这些开发命令会重启已登记（或经命令行确认属于本项目）的旧实例；若端口被未知程序占用，会拒绝终止并报告 PID。如遇权限不足，请使用拥有该进程权限的终端运行 `npm run dev:stop`。重启后端会终止其子任务，因此不要在回测或工作流运行时执行。

4. 打开前端开发地址 [http://localhost:5188](http://localhost:5188)。后端默认监听 `http://127.0.0.1:5180`，API 文档位于 [Swagger UI](http://localhost:5180/docs) 和 [ReDoc](http://localhost:5180/redoc)。

后端首次启动时会从量化项目的 `config.py` / `.env` 安全解析 `data_dir` 等路径。`backend/start_server.py` 使用 `backend/data/backend.pid` 和进程锁防止重复启动，不提供自动重载。

### 局域网开发访问

局域网访问必须显式开启，并配置高强度访问令牌。将 `backend/settings.json` 中的 `server_host` 设为 `0.0.0.0`，为 `api_token` 设置随机令牌，并设置允许访问的 IPv4 网段，例如：

```json
{
  "server_host": "0.0.0.0",
  "api_token": "<高强度随机令牌>",
  "lan_allowed_cidrs": ["192.168.2.0/24"]
}
```

随后使用：

```powershell
npm run dev:lan:all
```

其他设备只需访问 `http://<本机内网-IP>:5188`。开发服务器仅接受 `lan_allowed_cidrs` 内的 HTTP 和 WebSocket 来源，并在服务端读取 `D1_API_TOKEN` 或 `backend/settings.json` 中的 `api_token`，为同源 `/api` 请求代管认证；令牌不会写入浏览器。后端直连仍保留令牌保护，Windows 防火墙应仅开放前端端口并限制允许的来源网段。

## 常用命令

| 命令 | 用途 |
| --- | --- |
| `npm run dev` | 重启并启动前端开发服务器（端口 5188，自动打开浏览器） |
| `npm run dev:backend` | 重启并在 `quantpy312` 环境启动后端（端口 5180） |
| `npm run dev:stop` | 安全关闭已确认属于 D1 的前后端开发进程 |
| `npm run dev:all` | 重启前后端后并发启动；任一进程退出时清理另一进程 |
| `npm run build` | 执行 TypeScript 检查并构建到 `dist/` |
| `npm run preview` | 预览前端构建产物 |
| `npm run type-check` | 仅执行 Vue / TypeScript 类型检查 |
| `npm run lint` | 执行 ESLint 只读检查 |
| `npm run lint:ci` | 执行 ESLint，并阻止警告数超过当前基线 |
| `npm run lint:fix` | 执行 ESLint 并自动修复可修复问题 |
| `npm run format` | 使用 Prettier 格式化 `src/` 下的前端文件 |
| `npm run test` | 以 Vitest 交互模式运行前端测试 |
| `npm run test:run` | 单次运行全部前端测试 |
| `npm run test:coverage` | 运行前端测试并验证覆盖率阈值 |
| `npm run test:backend` | 运行后端 Pytest |
| `npm run check` | 依次执行类型、Lint、前后端测试和生产构建 |

运行单个前端测试：

```powershell
npx vitest run src/stores/__tests__/ui.test.ts
```

## 配置与安全

机器相关配置保存在 `backend/settings.json`。主要字段如下：

| 字段 | 说明 |
| --- | --- |
| `quant_proj` | `quant-test-d1-pro` 项目根目录 |
| `quant_python_path` | 量化任务、数据服务和实盘服务共用的 Python 解释器；留空时自动查找 `quantpy312` |
| `duckdb_query_host` / `duckdb_query_port` | DuckDB Flight 查询服务地址 |
| `data_service_project` | 手动配置的 `quant-data-d1-duckdb` 项目根目录；外部 Flight 服务不可达时用于托管 `start.py` |
| `live_trading_project` / `live_trading_entry_script` | 实盘项目根目录与项目内入口脚本 |
| `server_host` | 后端监听地址，默认 `127.0.0.1` |
| `api_token` | 远程访问 API 与 SSE 时使用的令牌 |
| `lan_allowed_cidrs` | Vite 内网开发代理允许的 IPv4 CIDR 列表 |
| `cors_origins` | 允许访问后端的前端来源列表 |

`D1_HOST`、`D1_API_TOKEN` 环境变量可覆盖同名运行设置。例如：

```powershell
$env:D1_HOST = '0.0.0.0'
$env:D1_API_TOKEN = '请替换为高强度随机令牌'
python backend/main.py
```

前端开发服务器和后端默认仅监听回环地址。本机开发可以不设置令牌；远程访问必须显式配置监听地址和令牌。不要把真实令牌或仅适用于本机的敏感路径提交到 Git。

## 系统架构

```text
浏览器（Vue 3 / Pinia）
  ├─ HTTP API ───────────────┐
  ├─ SSE 日志与进度 ─────────┤
                              ▼
                     FastAPI 后端（5180）
                      ├─ services / TaskManager
                      ├─ Polars 文件分析
                      ├─ SQLite 回测与任务缓存
                      ├─ quant-test-d1-pro 子进程
                      └─ 外部 QMT / DuckDB Flight 服务（手工运行或平台托管独立进程）
```

开发环境中，Vite（5188）把 `/api` 请求代理到 FastAPI（5180）。生产构建后，FastAPI 直接托管 `dist/` 中的 Vue SPA，并为 HTML5 History 路由提供回退页面。

前端调用链为 `pages → stores → api → request.ts`；后端调用链为 `main.py → routers → services`。任务状态和日志通过 SSE 推送，工作流定义保存在量化项目的 `workflows/` 目录，平台数据库位于 `backend/data/quant_platform.db`。

## 目录结构

```text
src/
├─ api/                 Axios API 封装
├─ assets/help/         页面帮助内容
├─ assets/styles/       全局样式和主题变量
├─ components/          通用、编辑器和布局组件
├─ composables/         SSE、参数持久化和代码编辑逻辑
├─ pages/               workflow、backtest、builder、library、live、live-trading、data-service、toolkit、settings
├─ router/              路由与页面标题守卫
├─ stores/              Pinia 状态管理
├─ types/               TypeScript 类型
└─ utils/               日期、ECharts 和编辑器主题工具

backend/
├─ routers/             API 路由薄层
├─ services/            工作流、任务、回测、缓存、数据与实盘服务
├─ services/nodes/      工作流节点实现
├─ middleware/          鉴权、异常、请求 ID 和日志处理
├─ alembic/             SQLite 迁移
├─ tests/               后端测试
├─ config.py            运行配置与路径解析
├─ main.py              FastAPI 应用入口
└─ start_server.py      单实例启动入口
```

## 主要 API

| 前缀 | 用途 |
| --- | --- |
| `/api/workflows`、`/api/simplified-workflows` | 工作流 CRUD、执行、状态与日志 |
| `/api/backtest` | 回测任务、结果、指标、对比和 K 线交易标记 |
| `/api/builder`、`/api/strategies` | 策略构建、配置和文件管理 |
| `/api/factors`、`/api/financial-factors`、`/api/selection`、`/api/timing` | 策略库内容管理 |
| `/api/kline` | K 线行情数据与交易标记 |
| `/api/data-service`、`/api/duckdb` | 外部数据服务监控、可选进程托管与只读 SQL 查询 |
| `/api/live-trading` | 实盘服务托管、监控，以及账户、策略、历史盈亏、指数分钟 K 线等只读可视化 |
| `/api/toolkit` | 数据文件浏览器（白名单根目录下的浏览与分页预览） |
| `/api/settings`、`/api/platform`、`/api/logs` | 平台设置、缓存、项目概览与日志查询 |

## 开发约定

- Vue、Router、Pinia API 与 Element Plus 组件由插件自动导入；动态字符串图标在 `src/main.ts` 注册。
- TypeScript 使用 strict 模式，路径别名 `@/` 指向 `src/`。
- API 响应拦截器自动解包 `response.data`；失败时抛出包含 `code`、`statusCode` 和 `detail` 的 `ApiError`。
- 代码格式遵循 `.prettierrc`；提交信息遵循 Conventional Commits。
- 主题为 `dark`、`light`、`eye-care`，偏好保存在 `localStorage` 的 `d1-theme` 键中。
- Vitest 全局覆盖率阈值为 60%，分支覆盖率阈值为 50%。