🇨🇳 简体中文
🇺🇸 English
🇯🇵 日本語

命令行使用指南

本指南介绍 scripts/ 目录下的脚本使用方法。

快速开始

# 1. 安装依赖
./scripts/install.sh

# 2. 启动服务
./scripts/startup.sh

# 3. 访问应用
# 前端: http://localhost:3000
# 后端: http://localhost:8000
# API文档: http://localhost:8000/docs

脚本列表

install.sh - 依赖安装

安装系统运行所需的所有依赖。

功能：

使用：

./scripts/install.sh

startup.sh - 服务启动

启动开发服务器（后端 + 前端）。

功能：

使用：

# 启动所有服务（开发模式）
./scripts/startup.sh

# 仅启动后端
./scripts/startup.sh --backend-only

# 仅启动前端
./scripts/startup.sh --frontend-only

# 停止所有服务
./scripts/startup.sh --stop

# 运行测试套件
./scripts/startup.sh --test

# 查看帮助
./scripts/startup.sh --help

test.sh - 测试运行

运行系统测试。

功能：

重要说明：

使用：

# 运行所有测试
./scripts/test.sh

# 运行单元测试
./scripts/test.sh unit

# 运行集成测试
./scripts/test.sh integration

# 运行 E2E 测试
./scripts/test.sh e2e

# 运行 API 测试
./scripts/test.sh api

# 运行缓存机制测试
./scripts/test.sh cache

# 生成覆盖率报告
./scripts/test.sh coverage

# 详细输出
./scripts/test.sh unit -v

# 快速模式（跳过慢速测试）
./scripts/test.sh -f

# 运行匹配模式的测试
./scripts/test.sh -k test_assets

# 设置测试环境
./scripts/test.sh --setup

# 清理测试环境
./scripts/test.sh --cleanup

手动测试（需要手动激活虚拟环境）：

# 重要：必须先激活虚拟环境
cd backend && source venv/bin/activate

# 运行测试
python -m pytest tests/ -v

# 并行运行单元测试
python -m pytest tests/unit/ -n auto -v

# 生成覆盖率报告
python -m pytest tests/ --cov=. --cov-report=html

常见错误：

# ❌ 错误：未激活虚拟环境
python -m pytest tests/unit/ -v              # 会失败
python3 -m pytest tests/unit/ -v             # 会失败
pytest tests/unit/ -v                        # 可能使用错误的 Python

# ✅ 正确：使用测试脚本或激活虚拟环境
./scripts/test.sh unit                       # 推荐
cd backend && source venv/bin/activate && python -m pytest tests/unit/ -v

lint-fix.sh - 代码质量修复

自动修复代码格式问题。

功能：

使用：

# 修复前后端所有代码
./scripts/lint-fix.sh

# 只修复前端
./scripts/lint-fix.sh --frontend

# 只修复后端
./scripts/lint-fix.sh --backend

generate_docs.sh - 文档生成

自动生成 API 文档、架构图、测试报告等。

功能：

使用：

./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

preview-docs.sh - 文档预览

本地预览文档站点，模拟 CI 构建流程。

功能：

使用：

./scripts/preview-docs.sh

预览地址：

依赖安装

系统要求

文档生成工具（可选）

# 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

文档预览工具（可选）

# Ruby 和 Bundler（用于 Jekyll）
# macOS
brew install ruby
gem install bundler

# Linux (Ubuntu/Debian)
sudo apt-get install ruby ruby-dev
sudo gem install bundler

# 验证安装
ruby --version
bundle --version

注意：

故障排除

端口被占用

# 脚本自动检测并停止冲突服务
# 手动停止：
./scripts/startup.sh --stop

# 手动检查端口占用
lsof -i :8000  # 后端端口
lsof -i :3000  # 前端端口
lsof -i :4000  # 文档预览端口

Redis 连接失败

# 检查 Redis
redis-cli ping  # 应返回 PONG

# 启动 Redis
brew services start redis  # macOS
redis-server &  # 手动启动

# 使用自定义配置启动
redis-server redis.conf --daemonize yes

依赖安装失败

# 检查版本
python --version  # >= 3.13
node --version    # >= 18

# 重新安装
./scripts/install.sh

# 手动安装后端依赖
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

前端构建失败

# 检查 Node.js 版本
node --version

# 清理并重新安装
cd frontend
rm -rf node_modules package-lock.json
npm install

# 检查 TypeScript 类型
npx tsc --noEmit

后端启动失败

# 检查 Python 版本
python --version

# 检查虚拟环境
cd backend && source venv/bin/activate
which python  # 应指向 venv/bin/python

# 检查依赖
pip list

# 检查环境配置
cat .env

测试运行失败

# 设置测试环境
./scripts/test.sh --setup

# 清理测试环境
./scripts/test.sh --cleanup

# 检查测试依赖
cd backend && source venv/bin/activate
pip install pytest pytest-asyncio pytest-cov

文档生成失败

# 检查后端服务是否运行
curl http://localhost:8000/docs

# 手动启动后端服务
./scripts/startup.sh --backend-only

# 检查文档生成工具
python -c "import py2puml, pydeps, mypy"
plantuml -version

代码质量修复失败

# 检查代码质量工具
cd backend && source venv/bin/activate
pip install black isort flake8

# 检查前端工具
cd frontend
npm install
npm run lint:fix

相关文档