## 重大更新
**NTQ 支持 Web UI 展示啦**：核心模块里加入前端（`core/ui/fed`）与 BFF（`core/ui/bff`），可在本机启动后通过浏览器使用策略实验室、策略选股、初始化向导、设置等界面。
> ## ⭐ 支持一下项目
> 如果您对项目有兴趣，并想持续关注，欢迎为仓库点亮一个Star！
> 这是我第一次尝试做开源项目，您的认可就是我前进的最大动力，谢谢您！
## NTQ 是什么？
您是不是心里有一些对股票操作策略的想法需要验证？比如是不是周线的RSI低于20我就可以买入？MACD的金叉银叉会有作用吗？追逐热门股票到底有多大胜率？我能不能把这些想法验证一下制定一个我自己的策略，然后用这个策略去扫描实时行情，找到我的投资机会？
当然可以，在NTQ里，这些都可以实现！
**NTQ**（New Tea Quant）是专门为了验证您的想法而诞生的一个量化策略框架，除了验证您的想法，这套框架还包含了一套完整的研究策略所需要的基础建设，可以单机使用。框架所有核心运算都支持多进程和多线程，只要您的电脑配置不是很低，框架都能高效地为您验证您的策略并且将策略应用的实时行情并把您的策略找到的机会反馈给您。
**特点** 框架不但能帮助您验证想法，并且提供了详细的日志和中间值，用多层方法验证策略的可行性，让您清晰看到策略如果不可行问题在哪里，可行的地方在哪里，让您能够更加精准地定位和调试。任何中间产生的数据都可回溯，结果都能复现。
**请注意** NTQ本身是免费的，但里边有些功能是需要您对接第三方平台的，例如：
- **数据获取**：NTQ包含数据获取的功能，但不包括数据获取的付费/免费认证，您需要在第三方平台购买/注册数据后方可接入NTQ
- **机会通知**：如果您想要把您的策略扫描到的机会以某种方式进行通知、学习、交易等，此框架无法提供功能，需要您对接您的第三方平台（例如短信，邮件，云，交易软件等等）来完成后续动作，框架默认只在命令行里显示结果。
**另外** 此框架需要您有一些轻微的编程基础，或者使用AI辅助您。整个项目使用Python语言和PostgreSQL或者MySQL完成，您需要在您的本机上装有相应的语言和数据库软件（Python，PostgreSQL和MySQL都是免费的）
本项目 **Apache 2.0 开源**，您可以自由学习、改造与扩展。**更完整的教程、概念说明与可视化阅读体验**在官方网站：**[new-tea.cn](https://new-tea.cn)**（中文）。
## 快速安装（5分钟跑起来）
目标：**5 分钟内跑起框架 + 跑通 `example` 策略**。
### 前提条件
- 本机需要有 **Python 3.9 或以上**版本。如果您不知道怎么安装，请参考这篇文档：[安装 Python](https://new-tea.cn/zh-hans/install-python)。
- 本机需要有 **MySQL 或 PostgreSQL** 中的任意一种数据库。如果您不知道如何安装，请参考这篇文档：[安装数据库](https://new-tea.cn/zh-hans/install-database)。
- (仅限于开发，纯使用不需要这个依赖) 本机需要安装 **Node.js**。请在 [Node.js 官网](https://nodejs.org/) 下载安装包并按向导安装（基本上就是一直点下一步）。
### 第 1 步：获取代码
任选其一：
- **Git clone**（推荐）：
```bash
git clone https://github.com/garnet1985/new-tea-quant.git
cd new-tea-quant
```
- **下载 ZIP**：在 GitHub 仓库页选择 **Code → Download ZIP**，解压后进入 **`new-tea-quant`** 根目录（与 `launcher.py` 同级）。
### 第 2 步：在仓库根目录启动安装向导
在**项目根目录**（能看到 `launcher.py`）打开终端，执行其一：
```bash
python launcher.py
```
若系统上 `python` 指向旧版本，可改用：
```bash
python3 launcher.py
```
脚本会：切到仓库根目录、确保虚拟环境、然后**启动 BFF + 前端并打开浏览器**，进入图形化 **Setup 安装向导**（由 BFF setup API 驱动步骤）。
### 第 3 步：在浏览器中按向导完成初始化
按页面提示依次完成即可（数据库连接、用户空间路径、数据导入等以当前向导为准）。以下为界面示意（共 5 张；若与您的版本略有差异，以实际页面为准）：
**图 1**
系统会自动安装需要的依赖包，这一步只需要点击“开始安装”并等待
**图 2**
本步配置 **userspace（用户空间）** 根目录，您可以：
- 使用向导给出的**默认路径**（直接点 **「下一步」**）。
- 或勾选 **「我想自定义 userspace 路径」**，在输入框中填写本机上的其他目录（请确保磁盘空间充足；若目标目录已有内容，向导会按策略提示是否覆盖）。
**图 3**
本步连接 **MySQL** 或 **PostgreSQL**。请事先安装并启动数据库服务，然后按页面填写：
- **数据库类型**（mysql / postgresql）。
- **主机、端口**（默认一般为本机；若使用云库或远程实例请按实际填写）。
- **用户名、密码**（需具备连接及**建库**权限；库不存在时，向导会尝试自动创建目标库）。
- **数据库名**：建议使用**新建或专用的空库**；若指向已有库，初始化会写入/变更表结构，**请勿使用存放重要业务数据的库名**。
连接校验通过后点 **「下一步」** 继续。之后仍可在 **「设置」** 中调整数据库配置。
**图 4**
数据库就绪后会进入 **数据导入** 等后续步骤，页面会显示步骤进度；本阶段可能持续较久，请保持页面打开并耐心等待。
**图 5**
全部步骤完成后，可点击 **「前往策略实验室」** 进入主界面。
### 您也可以通过命令行来运行策略
在仓库根目录执行：
```bash
python start-cli.py -sp
```
看到结果即表示已成功跑起第一个策略。
> **说明**：若您从官网下载了更大的演示数据 ZIP，仍需按后文「数据说明」放入 `setup/init_data/` 后执行 **`python install.py`** 导入；日常仅跑内置小数据时，完成向导 + 上条命令即可。
### 更多常用命令
查看帮助：
```bash
python start-cli.py -h
```
带资金的策略模拟：
```bash
python start-cli.py -sa
```
生成特征标签：
```bash
python start-cli.py -t
```
您也可以修改 `userspace/strategies/` 下的 settings 或 worker，自定义策略算法与目标。
Have fun `^_^`, 更多用法请参考这里 [更多用例](https://new-tea.cn/zh-hans/more-examples)
### 数据说明（请先看）
1. **仓库内置小数据**：只覆盖部分表，用于快速启动和演示。
2. **获取更多(3年)演示数据包**：用于更完整的策略验证/回测，请在 **[new-tea.cn](https://new-tea.cn)** 注册后下载放入setup/init_data后运行 python install.py 安装。（注意需要清空文件夹后再放入你的数据包，文件夹内只能有1个zip包）
3. **自有数据源**：也可自行接入（如 Tushare），详见 [userspace/data_source/README.md](userspace/data_source/README.md)。
## 请注意
当前版本仍然是非正式版本 **v0.x** 框架现阶段不能保证任何API的稳定性，当版本进入1.0之后，API将基本稳定。详见 [CHANGELOG.md](CHANGELOG.md)。
## 文档维护约定
- **根目录 `README.md` 是仓库文档主入口**，用于对外说明项目用法与当前推荐流程。
- **命令入口统一为 `start-cli.py`**；如其他文档出现 `start.py`，以本页与 `python start-cli.py -h` 为准。
- **`docs/development/` 为内部工作区文档**，当前阶段不纳入对外文档整理范围。
- 每次版本发布至少同步更新：
- `README.md`
- `CHANGELOG.md`
## 开源仓库里包含什么？
| 内容 | 说明 |
|------|------|
| **框架代码** | `core/` 与命令行工具，可本地运行 |
| **示例策略** | 仅内置 **`example`** 策略，用于对照配置与接口 |
| **演示行情等数据** | 包含一份可快速启动的小数据；更完整数据可从官网下载 |
| **辅助工具** | `devtools/`：Docker 说明、维护用自动化脚本等（非业务核心，索引见 [docs/README.md](docs/README.md) 中「仓库辅助工具」一节） |
## 如何联系到我？
您可以在以下网址给我留言（不用注册也可）：
**[new-tea.cn/zh-hans/contact](https://new-tea.cn/zh-hans/contact)**
框架是由我一人完成，工程量巨大，如有问题请您包容并及时反馈，谢谢您使用 NTQ。
## 分支策略是什么？
- **master**：最新版本，拒绝任何直接的 PR 或者提交
- **dev**：可从中建立分析，dev 会和 master 同步，到合适时机后会 merge 入 master 并且在 master 上建立 rc 分支用于 release，之后 release 代码会回到 dev
- **bugfix**：请使用 `bugfix/your-change` 的方式命名，否则无法 merge
- **feature**：请使用 `feature/your-change` 的方式命名，否则无法 merge
- **hotfix**：请使用 `hotfix/your-change` 的方式命名，否则无法 merge，分支只能从 rc 分支拉取
**Docker**：可用仓库内 `Dockerfile` 与 `docker-compose.yml` 拉起 PostgreSQL 与运行环境，步骤见 [devtools/docker/README.md](devtools/docker/README.md)。
## 有了新版本如何升级？
下载最新的master到您的本地，保留您本地的userspace文件夹，其他的都替换成新版本的文件即可。
---
## 命令行（`start-cli.py`）
入口脚本：**`start-cli.py`**（无参时默认执行与 `simulate_enum` 等价流程）。
```bash
python start-cli.py -h
```
| 用途 | 命令示例 |
|------|----------|
| 查看帮助 | `python start-cli.py -h` |
| 更新数据（renew） | `python start-cli.py -r` |
| 仅枚举机会 | `python start-cli.py enumerate --strategy example` |
| 枚举器模拟 | `python start-cli.py -se --strategy example` |
| 价格因子模拟 | `python start-cli.py -sp --strategy example` |
| 资金分配模拟 | `python start-cli.py -sa --strategy example` |
| 扫描机会 | `python start-cli.py -c --strategy example` |
| 分析结果摘要 | `python start-cli.py -a` |
| 标签计算 | `python start-cli.py -t` |
**`--strategy`**：未指定时，若只有一个 `is_enabled=True` 的策略会自动选用；多个启用时默认取名称排序第一个并 **告警**，建议显式写 `--strategy`。
**说明**：文档与站点中若仍出现旧命令 `start.py`，请以本仓库 **`start-cli.py`** 为准。
---
## 如何运行测试？
可以通过运行下列代码来实现，如果您要提交一个PR，请务必保证UT能跑过。
```bash
python -m pytest
```
## 依赖管理（Python）
项目使用 `pip-tools` 维护可复现锁定依赖：
- 顶层声明：`requirements.in`、`requirements-dev.in`
- 锁定结果：`requirements.txt`、`requirements-dev.txt`
更新锁文件（在仓库根目录）：
```bash
python3 -m piptools compile --output-file requirements.txt requirements.in
python3 -m piptools compile --output-file requirements-dev.txt requirements-dev.in
```
## 支持、反馈与捐赠
- **文档与会员资源（Demo 数据、扩展策略等）**：[new-tea.cn](https://new-tea.cn)
- **问题反馈、Issue / PR 预期**：[SUPPORT.md](SUPPORT.md)
- **参与贡献**：[CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- **安全披露**：[SECURITY.md](SECURITY.md)
若您希望 **捐赠或商业合作**，请以 **官网** 当前公示的联系方式或页面为准。
---
## 许可证与免责
本项目采用 **Apache License 2.0**，见 [LICENSE](LICENSE)。
**免责声明**：仅供学习与研究，不构成任何投资建议；回测结果不代表未来表现。
---