股票分析系统 v0.5.0

当前版本: v0.5.0 (统一缓存系统)
更新日期: 2025-12-05
⚠️ Web版已废弃，相关文档已归档至 docs/_archive/

⚠️ 重要警告

部署前必读：

1. backend/app/database.py 包含数据库配置，绝对不能提交到Git！
2. data/*.json 文件包含服务器特定状态，不能覆盖！
3. 所有.md文档说明都应放在 docs/ 目录，保持根目录整洁！
4. 详细说明请阅读：配置文件管理和常见错误

---

📋 项目简介

A股股票数据分析系统，支持多种分析功能和可视化展示。

主要功能

分析功能

• ✅ 最新热点分析（支持前100/200/400/600/800/1000个股票选择）
• ✅ 股票查询
• ✅ 行业趋势分析（支持前1000/2000/3000/5000名选择）
• ✅ 排名跳变（支持搜索）
• ✅ 稳步上升（支持搜索）
• ✅ 板块成分股分析
• ✅ 信号系统

v0.4.0 新增

• 🔐 AES-256-GCM 加密通信
• 🔑 JWT Token 认证
• 🖥️ Electron 桌面客户端
• 📦 本地 SQLite 离线缓存
• 🔄 自动更新功能

v0.5.0 新增

• 🗄️ 统一缓存系统 (三层架构: 内存/Numpy/磁盘)
• ⚡ Write-Behind 异步回写 (会话心跳)
• 🔄 Cache-Aside 旁路缓存 (用户信息)
• 💾 FileStore 磁盘缓存 (API响应/报表)
• 🛡️ 安全熔断装饰器 (缓存异常不影响业务)
• 📊 智能GC (内存阈值触发)

---

🚀 快速开始

本地开发

# 1. 克隆项目
git clone <repository-url>
cd stock_analysis_app

# 2. 配置数据库
cd backend/app
cp database.py.example database.py
nano database.py  # 修改数据库配置

# 3. 启动后端
cd ../..
bash start_all.sh dev

# 4. 访问
# 前端: http://localhost:3000
# 后端: http://localhost:8000

服务器部署

⚠️ 部署前必须先备份服务器配置！

# 1. 备份配置
cp backend/app/database.py ~/database.py.backup
cp data/data_import_state.json ~/data_import_state.json.backup

# 2. 拉取代码
git pull origin main

# 3. 恢复配置（如果需要）
cp ~/database.py.backup backend/app/database.py

# 4. 启动服务
bash start_all.sh  # 默认生产模式

详细部署指南：服务器部署指南

---

📚 文档

必读文档

• 配置文件管理和常见错误 ⭐️ 必读
• 数据管理使用指南 ⭐️ 数据导入必读
• 文档索引 - 完整文档目录

桌面客户端 (v0.4.0+)

• 快速开始指南 ⭐️ 客户端开发入门
• 开发文档-客户端加密系统 - 加密架构设计
• 技术实现细节 - 代码实现参考

部署相关

• 更新日志

---

🔧 配置说明

数据库配置

方法1：使用 database.py（简单）

cd backend/app
cp database.py.example database.py
nano database.py

修改：

DB_HOST = "localhost"              # 数据库地址
DB_PORT = "5432"                   # 端口
DB_NAME = "stock_analysis"         # 数据库名
DB_USER = "postgres"               # 用户名
DB_PASSWORD = "your_password"      # 密码

方法2：使用环境变量（推荐）

cd backend
cat > .env << 'EOF'
DB_HOST=localhost
DB_PORT=5432
DB_NAME=stock_analysis
DB_USER=postgres
DB_PASSWORD=your_password
EOF

---

🛠️ 技术栈

后端

• Python 3.12
• FastAPI
• SQLAlchemy
• PostgreSQL
• Uvicorn

前端

• React 18
• TailwindCSS
• Recharts
• Lucide Icons
• Axios

---

📦 项目结构

stock_analysis_app/
├── backend/              # 后端 FastAPI
│   ├── app/
│   │   ├── auth/             # 🆕 认证模块 (JWT)
│   │   ├── crypto/           # 🆕 加密模块 (AES-256-GCM)
│   │   ├── routers/          # API路由
│   │   ├── services/         # 业务逻辑
│   │   ├── models/           # 数据模型
│   │   ├── database.py.example  # 数据库配置模板 ⚠️
│   │   └── database.py       # 数据库配置（不提交）⚠️
│   └── requirements.txt
├── frontend/             # Web前端 (已废弃)
├── frontend-client/      # 🆕 Electron 桌面客户端
│   ├── electron/         # 主进程
│   └── src/              # 渲染进程 (React)
├── data/                 # 数据文件（不提交）⚠️
├── docs/                 # 文档
│   ├── client/           # 桌面客户端文档
│   └── _archive/         # 归档文档
├── deploy/               # 部署配置
└── README.md

---

🔐 安全注意事项

绝对不能提交到Git的文件

• ❌ backend/app/database.py - 包含数据库密码
• ❌ backend/.env - 环境变量
• ❌ data/*.json - 服务器状态文件
• ❌ logs/ - 日志文件

检查方法

# 部署前检查
git status

# 应该看不到上述文件

---

🐛 故障排查

服务无法启动

# 查看日志
tail -100 logs/backend.log

# 测试数据库连接
cd backend
python3 -c "from app.database import test_connection; test_connection()"

数据库连接失败

1. 检查 backend/app/database.py 配置
2. 测试数据库连接：psql -h <host> -U <user> -d <database>
3. 检查防火墙和网络

---

📄 License

MIT

---

👥 贡献

欢迎提交Issue和Pull Request

---

再次提醒：部署前必读 配置文件管理和常见错误