命令行使用指南
本指南介绍 scripts/ 目录下的脚本使用方法。
快速开始
# 1. 安装依赖
./scripts/install.sh
# 2. 启动服务
./scripts/startup.sh
# 3. 访问应用
# 前端: http://localhost:3000
# 后端: http://localhost:8000
# API文档: http://localhost:8000/docs
脚本列表
install.sh - 依赖安装
安装系统运行所需的所有依赖。
功能：
- 检查系统要求（Python 3.13+, Node.js 18+, Redis）
- 创建 Python 虚拟环境
- 安装后端依赖（requirements.txt）
- 安装前端依赖（package.json）
- 创建必要目录
使用：
./scripts/install.sh
startup.sh - 服务启动
启动开发服务器（后端 + 前端）。
功能：
- 检查并激活 Python 虚拟环境
- 检查 Redis 状态，自动启动
- 启动 FastAPI 后端（localhost:8000）
- 启动 Vite 前端（localhost:3000）
- 智能停止已运行的服务
- 提供健康检查
使用：
# 启动所有服务
./scripts/startup.sh
# 仅启动后端
./scripts/startup.sh --backend-only
# 仅启动前端
./scripts/startup.sh --frontend-only
# 停止所有服务
./scripts/startup.sh --stop
# 查看帮助
./scripts/startup.sh --help
test.sh - 测试运行
运行系统测试。
功能：
- 支持单元测试、集成测试、E2E 测试
- 支持并行测试执行
- 生成测试覆盖率报告
- 支持特定测试文件运行
使用：
# 运行所有测试
./scripts/test.sh
# 运行单元测试
./scripts/test.sh unit
# 运行集成测试
./scripts/test.sh integration
# 运行 E2E 测试
./scripts/test.sh e2e
# 并行运行测试
./scripts/test.sh --parallel
# 运行特定测试文件
./scripts/test.sh tests/unit/test_fee_calculator.py
# 生成覆盖率报告
./scripts/test.sh --coverage
手动测试：
cd backend && source venv/bin/activate
pytest tests/ -v
# 并行运行单元测试
pytest tests/unit/ -n auto -v
# 生成覆盖率报告
pytest tests/ --cov=. --cov-report=html
lint-fix.sh - 代码质量修复
自动修复代码格式问题。
功能：
- 前端：ESLint 自动修复
- 后端：Black 格式化 + Isort 导入排序
- 自动运行代码检查（Flake8、TypeScript）
使用：
# 修复前后端所有代码
./scripts/lint-fix.sh
# 只修复前端
./scripts/lint-fix.sh --frontend
# 只修复后端
./scripts/lint-fix.sh --backend
generate_docs.sh - 文档生成
自动生成 API 文档、架构图、测试报告等。
功能：
- 自动激活虚拟环境
- 检查/启动后端服务
- 导出 OpenAPI 规范
- 生成 UML 类图（需要 py2puml）
- 生成模块依赖图（需要 pydeps）
- 渲染 PlantUML 图（需要 plantuml）
- 运行测试并生成覆盖率报告
- 运行类型检查
使用：
./scripts/generate_docs.sh
生成内容：
docs/
├── api/
│ ├── openapi.json
│ ├── README.md
│ └── v1/
│ ├── authentication/
│ ├── trading/
│ └── ...
├── architecture/diagrams/
│ ├── *.puml
│ └── *.svg
└── reports/
├── coverage/index.html
└── type-check/index.html
依赖安装
系统要求
- Python 3.13+
- Node.js 18+
- Redis 6.0+
文档生成工具（可选）
# Python 依赖
cd backend && source venv/bin/activate
pip install py2puml pydeps mypy pytest-cov
# PlantUML
# macOS
brew install plantuml
# Linux (Ubuntu/Debian)
sudo apt-get install plantuml
# Linux (CentOS/RHEL)
sudo yum install plantuml
# Windows
choco install plantuml
# 或
scoop install plantuml
# 验证安装
plantuml -version
注意： 如果不安装 PlantUML，仍会生成 .puml 源文件，可使用：
- 在线渲染: https://www.plantuml.com/plantuml/
- VS Code 插件: PlantUML
- IDE 集成: IntelliJ IDEA、PyCharm 等
故障排除
端口被占用
# 脚本自动检测并停止冲突服务
# 手动停止：
./scripts/startup.sh --stop
Redis 连接失败
# 检查 Redis
redis-cli ping # 应返回 PONG
# 启动 Redis
brew services start redis # macOS
redis-server & # 手动启动
依赖安装失败
# 检查版本
python --version # >= 3.13
node --version # >= 18
# 重新安装
./scripts/install.sh
前端构建失败
# 检查 Node.js 版本
node --version
# 清理并重新安装
cd frontend
rm -rf node_modules package-lock.json
npm install
后端启动失败
# 检查 Python 版本
python --version
# 检查虚拟环境
cd backend && source venv/bin/activate
which python # 应指向 venv/bin/python
# 检查依赖
pip list