股票预测平台

基于AI的智能股票预测和任务管理系统，采用现代化的微服务架构，集成先进的机器学习模型和实时数据处理能力。

🚀 项目概述

本项目是一个完整的股票预测解决方案，包含：

• 后端服务: 基于FastAPI的高性能API服务
• 前端应用: 基于Next.js + React的现代化Web界面
• 机器学习: 集成Qlib量化框架和多种深度学习模型
• 数据管理: 支持本地和远程数据源的统一管理
• 实时通信: WebSocket支持的任务状态实时更新

🏗️ 技术架构

后端技术栈

• 框架: FastAPI + SQLAlchemy
• 数据库: SQLite (开发) / PostgreSQL (生产)
• 机器学习: Qlib + PyTorch + XGBoost
• 数据存储: Parquet文件格式
• 异步处理: Celery + Redis
• API文档: 自动生成的OpenAPI文档

前端技术栈

• 框架: Next.js 14 (App Router)
• UI库: Ant Design Pro
• 状态管理: Zustand
• 图表库: ECharts + TradingView
• 实时通信: Socket.IO Client
• 类型安全: TypeScript

机器学习模型

• 传统模型: XGBoost, LSTM
• 现代模型: Transformer, TimesNet, PatchTST, Informer
• 集成学习: 模型ensemble和在线学习
• 回测引擎: Vectorbt集成

📁 项目结构

stock-prediction-platform/
├── backend/                    # Python后端服务
│   ├── app/                   # 应用核心代码
│   │   ├── api/              # API路由
│   │   ├── services/         # 业务逻辑服务
│   │   ├── models/           # 数据模型
│   │   ├── middleware/       # 中间件
│   │   └── core/            # 核心配置
│   ├── tests/               # 测试文件
│   ├── data/               # 数据存储目录
│   └── requirements.txt    # Python依赖
├── frontend/               # React前端应用
│   ├── src/               # 源代码
│   │   ├── app/          # Next.js页面
│   │   ├── components/   # React组件
│   │   ├── services/     # API服务
│   │   └── stores/       # 状态管理
│   ├── public/           # 静态资源
│   └── package.json      # Node.js依赖
├── data/                 # 共享数据目录
├── .kiro/               # 项目规范和任务管理
│   └── specs/           # 功能规范文档
└── README.md            # 项目说明文档

🚀 快速开始

环境要求

• Python: 3.9+
• Node.js: 18+
• tmux: 用于本地开发编排
• Git: 最新版本

🎯 推荐开发启动方式（当前默认）

当前仓库优先采用“本地原生进程 + tmux 编排”的开发流，而不是把安装、杀端口、启动全部塞进一个万能脚本里。

统一入口说明见：STARTUP.md

默认开发端口：

• Backend: 127.0.0.1:18082
• Frontend: 127.0.0.1:13000
• Data API: 127.0.0.1:5002
• Metrics: 127.0.0.1:19090

四服务拓扑、健康检查和常见问题见：docs/guides/LOCAL_DEVELOPMENT_SERVICES.md。

推荐命令：

# 1. 克隆项目
git clone <repository-url>
cd stock-prediction-platform

# 2. 检查环境
make doctor

# 3. 安装依赖（首次执行）
make setup

# 4. 启动开发环境（tmux 会话）
make dev
# 或 ./start.sh

# 5. 查看状态
./status.sh

# 6. 停止开发环境
./stop.sh

说明：

• make dev / ./start.sh 会创建 tmux 会话 stock-platform-dev
• backend / frontend / data-api / worker 会拆到独立 tmux window
• 当前 worker 仍是占位窗口，任务调度随 backend 生命周期运行
• 不会自动 kill 8000/3000 等其他项目端口
• 如果目标端口被占用，脚本会直接报错并显示占用者

📱 访问应用

启动成功后访问：

• 前端界面: http://127.0.0.1:13000
• API文档: http://127.0.0.1:18082/api/v1/docs
• API管理: http://127.0.0.1:18082/api/v1/redoc
• 数据服务健康检查: http://127.0.0.1:5002/api/data/health

🧰 常用开发命令

# 环境检查
make doctor

# 单独准备后端 / 前端
make setup-backend
make setup-frontend

# 启动开发环境
make dev

# 单独启动服务（前台）
make dev-backend
make dev-frontend

# 查看运行状态
./status.sh

# 查看日志
./scripts/logs.sh backend
./scripts/logs.sh frontend
./scripts/logs.sh data-api
./scripts/logs.sh worker
./scripts/logs.sh all

# 停止开发环境
make stop

🏭 生产态 / 常驻运行（systemd）

如果你要在这台机器上做本地常驻运行，而不是临时开发，当前推荐路径是 systemd：

# 1. 准备依赖
make setup

# 2. 构建前端生产产物
make prod-build

# 3. 安装 systemd unit
sudo ./scripts/install-systemd.sh

# 4. 启动服务
./scripts/prod-up.sh

# 5. 查看状态
./scripts/prod-status.sh

停止服务：

./scripts/prod-down.sh

说明：

• backend 使用 backend/.env
• frontend 使用 frontend/.env.local
• frontend 的 systemd 服务运行 npm run start，所以 prod-up 前要先 prod-build
• 当前 worker 仍是占位 unit，任务生命周期主要仍由 backend 承担

🐳 Docker 启动（仅保留历史兼容）

仓库里仍保留一些历史 Docker/简单启动脚本，但它们已经 deprecated，只作为兼容层存在，不再是推荐的开发或维护路径。

请优先使用：

• 开发态：make dev
• 生产态：make prod-build + ./scripts/install-systemd.sh + ./scripts/prod-up.sh

🛠️ 手动启动（高级用户）

后端设置

cd backend

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 建议开发端口
export HOST=127.0.0.1
export PORT=18082
export METRICS_PORT=19090

# 运行后端服务
python run.py

前端设置

cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev -- --hostname 127.0.0.1 --port 13000

⚠️ 历史脚本说明

以下脚本仍在仓库中，但已经被降级为兼容层：

• scripts/simple-start.sh
• scripts/stop-simple.sh
• scripts/quick-start.sh
• scripts/start.sh
• scripts/stop.sh

它们会输出 deprecated 提示，并引导到新的开发态或生产态入口。

🔧 开发指南

后端开发

# 一键准备 backend 质量环境并输出快照
cd backend
./scripts/quality.sh snapshot

# 运行完整测试
python -m pytest

# 单独执行静态检查
./scripts/quality.sh flake8
./scripts/quality.sh mypy

前端开发

# 运行测试
cd frontend
npm test

# 类型检查
npm run type-check

# 代码格式化
npm run lint

# 构建生产版本
npm run build

📊 功能特性

✅ 已实现功能

• 项目基础架构: 完整的前后端项目搭建
• 数据服务层: 支持本地和远程数据源
• 技术指标计算: MA、RSI、MACD、布林带等
• 数据库存储: SQLite数据库和Parquet文件管理
• 任务管理: 完整的任务生命周期管理
• 机器学习: 多种模型训练和评估
• 预测引擎: 多时间维度预测和风险评估
• API网关: 完整的RESTful API和文档
• 前端架构: React应用和状态管理

🚧 开发中功能

• 任务管理界面: 任务创建和监控界面
• 数据可视化: 图表和技术指标展示
• 回测分析: 策略回测和性能分析
• 系统监控: 实时状态监控和告警

🔮 计划功能

• 用户认证: 多用户支持和权限管理
• 模型市场: 预训练模型分享和下载
• 实时交易: 模拟交易和实盘对接
• 移动端: React Native移动应用

🧪 测试

项目包含完整的测试套件：

• 单元测试: 核心业务逻辑测试
• 属性测试: 基于Property-Based Testing的正确性验证
• 集成测试: API端到端测试
• 前端测试: React组件和服务测试

# 运行所有测试
cd backend && python -m pytest
cd frontend && npm test

📈 性能优化

• 后端: 异步处理、数据库连接池、缓存策略
• 前端: 代码分割、懒加载、状态优化
• 数据: Parquet格式、增量更新、并行计算
• 模型: GPU加速、模型量化、批处理推理

🔒 安全考虑

• API安全: 请求限流、输入验证、错误处理
• 数据安全: 敏感信息加密、访问控制
• 前端安全: XSS防护、CSRF保护
• 部署安全: HTTPS、环境变量管理

📝 开发规范

• 代码风格: 遵循PEP8 (Python) 和ESLint (JavaScript)
• 提交规范: 使用Conventional Commits格式
• 分支策略: Git Flow工作流
• 文档要求: 代码注释和API文档

🤝 贡献指南

1. Fork项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建Pull Request

📄 许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

• 项目维护者: [Your Name]
• 邮箱: [your.email@example.com]
• 项目链接: [https://github.com/yourusername/stock-prediction-platform]

🙏 致谢

感谢以下开源项目的支持：

• Qlib - 量化投资平台
• FastAPI - 现代Python Web框架
• Next.js - React生产框架
• Ant Design - 企业级UI设计语言

---

注意: 本项目仅用于学习和研究目的，不构成投资建议。投资有风险，入市需谨慎。

📂 项目目录规范

为了保持项目整洁，请严格遵守以下目录存放规则：

1. 文档归档 (docs/)

• 所有项目相关的 .md 文档必须归档至 docs/ 下的对应分类子目录中。
• docs/README.md 是所有文档的索引。
• 分类包括：guides/ (指南), mobile/ (移动端优化), backtest/ (回测), qlib/ (模型算法), mlops/ (运维管理), quality/ (质量规范), reports/ (阶段总结), fixes/ (修复记录)。

2. 测试与工具脚本 (tests/)

• 严禁在根目录存放临时的 .py, .js, .sh 等脚本。
• tests/integration/: 用于集成测试和数据验证。
• tests/scripts/: 用于任务管理、状态修复等实用工具。
• tests/manual/: 用于手动验证 API 或通信的工具。

3. 核心开发目录

• backend/: FastAPI 后端代码。
• frontend/: Next.js 前端代码。
• back_test_data_service/: 独立回测数据服务。

4. 系统环境与配置

• nginx/, monitoring/, systemd/, scripts/: 分别存放代理、监控、服务和系统安装脚本。

---

以后新增任何文件，请根据上述规则放入对应目录。