README.md

---
title: QSSS New
emoji: 📈
colorFrom: gray
colorTo: indigo
sdk: docker
pinned: false
license: mit
---
# A股量化策略选股系统

## 项目简介

QSSS (Quantitative Stock Strategy System) 是一个专为A股市场设计的量化策略选股系统。它提供了一套完整的解决方案，涵盖了从数据获取、策略开发、回测分析到投资组合优化的全流程。系统后端基于Python FastAPI构建，前端采用Next.js，并针对HuggingFace Space的Docker纯内存环境进行了深度优化，确保高效、轻量级的部署和运行。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-green.svg)](https://fastapi.tiangolo.com/)
[![Next.js](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)
[![SQLite](https://img.shields.io/badge/SQLite-Memory-orange.svg)](https://www.sqlite.org/)
[![Redis](https://img.shields.io/badge/Redis-Memory-red.svg)](https://redis.io/)

## 📑 目录

- [项目简介](#项目简介)
- [主要功能](#主要功能)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
  - [Hugging Face部署指南](docs/hf_deployment_guide.md)
- [使用说明](#使用说明)
- [开发指南](#开发指南)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
- [联系方式](#联系方式)

## 🚀 主要功能

### 仪表盘
- 实时指数/新闻/策略概览

### 策略管理
- 创建/编辑/实例监控

### 回测分析
- 参数设置/图表展示

### 选股功能
- 条件筛选/详情查看

## 🔧 技术架构

### 后端技术栈
- **框架**: FastAPI (Python)
- **数据库**: SQLite (纯内存模式)
- **缓存**: FakeRedis (纯内存模式)
- **数据处理**: Pandas, NumPy
- **量化库**: TA-Lib, Backtrader, Empyrical, Pyfolio
- **机器学习**: Scikit-learn, XGBoost, LightGBM

### 前端技术栈
- **框架**: Next.js 14 (App Router)
- **UI组件库**: Shadcn UI (基于Radix UI和Tailwind CSS构建)
- **样式**: Tailwind CSS
- **状态管理**: Zustand
- **数据获取**: React Query
- **可视化**: Recharts

### 数据源
- **股票数据**: Tushare (需配置 `TUSHARE_TOKEN` 环境变量), AKShare
- **财务数据**: Wind, 同花顺 (通过模拟数据或外部API集成)
- **实时行情**: WebSocket推送 (模拟或通过外部API集成)
- **新闻数据**: 新华财经 (通过外部API集成)

## 📁 项目结构

```
qsss_new/
├── .env                     # 环境变量配置文件 (本地使用)
├── .env.example             # 环境变量示例文件
├── backend/                 # 后端服务
│   ├── app/                # 应用主目录
│   │   ├── api/           # API路由
│   │   ├── core/          # 核心配置 (包含内存模式数据库和缓存配置)
│   │   │   └── database_memory.py # 内存模式数据库配置
│   │   │   └── db_selector.py    # 数据库模式选择器
│   │   ├── models/        # 数据模型
│   │   ├── services/      # 业务逻辑
│   │   └── utils/         # 工具函数
│   ├── strategies/         # 量化策略
│   ├── data/              # 数据处理
│   │   └── data_service_memory.py # 内存模式数据服务
│   └── tests/             # 测试文件 (仅包含test_sql_injection.py)
├── qsss-web/                # Next.js前端应用
│   ├── public/            # 静态资源
│   ├── src/               # 源代码
│   │   ├── app/           # App Router 页面和 API 路由
│   │   ├── components/    # UI 组件和共享组件
│   │   ├── lib/           # 工具函数和 API 客户端
│   │   └── types/         # TypeScript 类型定义
│   └── Dockerfile         # Dockerfile for Next.js app
└── docs/                  # 文档
    └── hf_deployment_guide.md  # Hugging Face部署指南
```

## 🚀 快速开始

### HuggingFace部署

系统专为HuggingFace Space免费层优化，采用**纯内存模式**运行，所有数据（包括数据库和缓存）均存储在内存中，不写入本地文件系统，确保了部署的轻量级和高效性。

#### 在HuggingFace Space上部署

1.  创建一个新的Docker Space。
2.  设置环境变量：
    *   `MEMORY_MODE=true`：**必须**设置为 `true` 以启用纯内存模式。
    *   `SECRET_KEY`：**必须**设置为一个强随机字符串，用于JWT令牌签名。建议使用 `openssl rand -hex 32` 生成。
    *   `TUSHARE_TOKEN`：**可选**。如果您需要从Tushare获取实时或历史数据，请在此处设置您的Tushare API Token。如果未设置，系统将使用模拟数据或AKShare等其他数据源。
3.  上传代码到Space仓库。

系统会自动使用项目根目录的`Dockerfile`进行构建和部署。

## 🖥️ 本地部署

您可以在本地环境部署和运行本项目，支持使用 Docker 或直接运行。

### 1. 使用 Docker 构建和运行

如果您已安装 Docker，可以通过以下步骤快速启动项目：

1.  **确保 `.env` 文件存在**：在项目根目录创建 `.env` 文件（如果尚未创建），并根据 `.env.example` 填写必要的环境变量。
    ```bash
    cp .env.example .env
    # 编辑 .env 文件，设置 SECRET_KEY 等
    ```
2.  **构建 Docker 镜像**：在项目根目录执行以下命令构建镜像。
    ```bash
    docker build -t qsss-new .
    ```
3.  **运行 Docker 容器**：
    ```bash
    docker run -d -p 7860:7860 --env-file .env qsss-new
    ```
    *   `-d` 表示在后台运行容器。
    *   `-p 7860:7860` 将容器的 7860 端口映射到主机的 7860 端口。
    *   `--env-file .env` 会将 `.env` 文件中的环境变量加载到容器中。

4.  **访问应用程序**：在浏览器中访问 `http://localhost:7860`。

### 2. 不使用 Docker 直接运行

如果您不希望使用 Docker，可以分别启动后端和前端服务。

#### 后端服务 (Python)

1.  **进入后端目录**：
    ```bash
    cd backend
    ```
2.  **创建并激活 Python 虚拟环境**：
    ```bash
    python3 -m venv backend_venv
    source backend_venv/bin/activate
    ```
    *   **注意**：如果 `python3` 命令不可用，请尝试 `python`。
3.  **安装 Python 依赖**：
    ```bash
    pip install -r requirements.txt
    ```
    *   如果需要开发依赖，可以运行 `pip install -r requirements-dev.txt`。
4.  **启动后端 Uvicorn 服务**：
    ```bash
    uvicorn app.main:app --host 0.0.0.0 --port 8000
    ```
    *   后端服务将在 `http://localhost:8000` 上运行。

#### 前端服务 (Next.js)

1.  **打开新的终端窗口**（或在当前终端中停止后端服务并切换目录）。
2.  **进入前端目录**：
    ```bash
    cd qsss-web
    ```
3.  **安装 Node.js 依赖**：
    ```bash
    npm install
    # 或者如果您使用 pnpm:
    # pnpm install
    ```
4.  **启动 Next.js 开发服务器**：
    ```bash
    npm run dev
    # 或者如果您使用 pnpm:
    # pnpm run dev
    ```
    *   前端服务通常会在 `http://localhost:3000` 上运行。

完成以上步骤后，您应该可以通过浏览器访问 `http://localhost:3000` 来使用应用程序。

## ⚙️ 环境变量配置

本项目支持通过环境变量进行灵活配置。建议在项目根目录创建 `.env` 文件来管理这些参数。

| 环境变量       | 说明                                                              | 默认值             |
| -------------- | ----------------------------------------------------------------- | ------------------ |
| `PORT`         | 应用程序监听的端口。                                              | `7860`             |
| `DATABASE_URL` | 数据库连接URL。在内存模式下，通常为 `sqlite:///:memory:`。        | `sqlite:///:memory:` |
| `REDIS_MODE`   | Redis模式，可选 `memory` (纯内存) 或 `redis` (需要外部Redis服务)。 | `memory`           |
| `SECRET_KEY`   | 用于JWT令牌签名和数据加密的密钥。**生产环境必须设置强随机字符串**。 | `your_secret_key_here` |
| `ENVIRONMENT`  | 应用程序运行环境，可选 `development`, `production`, `testing`。   | `production`       |
| `MEMORY_MODE`  | 是否启用纯内存模式 (数据库和缓存均在内存中)。`true` 或 `false`。 | `true`             |

**示例 `.env` 文件:**
```dotenv
PORT=7860
DATABASE_URL=sqlite:///:memory:
REDIS_MODE=memory
SECRET_KEY=your_strong_random_secret_key
ENVIRONMENT=production
MEMORY_MODE=true
```

## 📊 示例数据

系统会自动生成以下示例数据：

- 股票列表：包含部分A股示例股票
- 行情数据：随机生成的模拟行情数据
- 因子数据：预设的基础因子数据

## 📚 使用说明

### 策略配置

系统提供多种预设策略，可以通过Web界面进行配置和参数调整。

### 回测分析

支持历史数据回测，并提供丰富的性能指标和可视化图表。

### 选股结果

系统会根据策略生成选股结果，并提供详细的选股理由和风险评估。

## 🛠️ 开发指南

### 添加新策略

1.  在`backend/strategies`目录下创建新的策略类。
2.  继承`BaseStrategy`类并实现必要的方法。
3.  在`strategy_manager.py`中注册新策略。

### 自定义数据源

1.  在`backend/data`目录下创建新的数据源适配器。
2.  实现数据获取和处理方法。
3.  在数据服务中集成新的数据源。

## 📄 许可证

本项目采用MIT许可证 - 详情请参阅[LICENSE](LICENSE)文件

## 📞 联系方式

项目维护者 - [MisonL](https://github.com/MisonL)

项目链接: [https://huggingface.co/spaces/misonL/QSSS_new](https://huggingface.co/spaces/misonL/QSSS_new)

## 开发环境配置
```bash
# 运行初始化脚本
chmod +x backend/setup_venv.sh
./backend/setup_venv.sh

# 激活虚拟环境
source backend/.venv/bin/activate
```