pyxr/DEVELOPMENT.md

# 开发指南

## 环境要求

- Python 3.x
- Node.js (推荐 v16 或更高版本)
- MongoDB

## 数据库配置

1. 安装 MongoDB
   - Windows: 参考 https://www.runoob.com/mongodb/mongodb-window-install.html
   - macOS: 使用 Homebrew 安装
     ```bash
     brew tap mongodb/brew
     brew install mongodb-community
     ```

2. 启动 MongoDB 服务
   ```bash
   # Windows
   mongod --dbpath <你的数据库路径>
   
   # macOS
   brew services start mongodb-community
   ```

3. 验证 MongoDB 是否正常运行
   ```bash
   mongosh
   use flask_db
   show dbs
   ```

## 后端服务启动

1. 安装 Python 依赖
   ```bash
   # 如果使用 poetry
   poetry install
   
   # 如果使用 pip
   pip install -r requirements.txt
   ```

2. 启动 Flask 服务器
   ```bash
   # 使用 poetry
   poetry run python -m flask --app src.backend.app run --debug
   
   # 直接使用 python
   python -m flask --app src.backend.app run --debug

   # 如果localhost:5000相应api无法访问，但是127.0.0.1:5000可以访问，考虑使用以下命令启动
   poetry run python -m flask --app src.backend.app run --host=0.0.0.0 --debug
   # 在macos系统下，可能要解决端口冲突
   Port 5000 is in use by another program. Either identify and stop that program, or start the server with a different port.
   On macOS, try disabling the 'AirPlay Receiver' service from System Preferences -> General -> AirDrop & Handoff.
   ```

   服务器将在 http://localhost:5000 上运行

## 前端服务启动

1. 进入前端目录
   ```bash
   cd src/frontend
   ```

2. 安装依赖
   ```bash
   npm install
   ```

3. 启动开发服务器
   ```bash
   npm run dev
   ```

   前端服务将在 http://localhost:3000 上运行

## 常见问题

### MongoDB 连接问题

如果遇到 MongoDB 连接错误：
1. 确保 MongoDB 服务正在运行
2. 检查 MongoDB 默认端口 (27017) 是否被占用
3. 确认数据库路径是否正确

### 后端服务启动失败

1. 确保所有依赖都已正确安装
2. 检查 MongoDB 连接是否正常
3. 确保端口 5000 未被占用

### 前端开发服务器问题

1. 确保 Node.js 版本兼容
2. 删除 node_modules 目录并重新安装依赖
3. 确保端口 3000 未被占用

### 运行测试

1. 安装测试依赖
   ```bash
   # 使用 poetry 添加测试依赖
   poetry add pytest --dev
   
   # 如果使用 pip
   pip install pytest
   ```

2. 运行测试
使用 Poetry 运行测试：
```bash
# 运行所有测试
poetry run pytest

# 运行单个测试文件
poetry run pytest tests/test_app.py

# 查看详细的测试输出
poetry run pytest -v

# 显示测试失败的详细信息
poetry run pytest -vv
```

如果测试失败，使用 `-vv` 参数可以查看更详细的错误信息和断言失败的具体原因。
```
   ```bash
   npm run dev
   ```

   前端服务将在 http://localhost:3000 上运行

## 常见问题

### MongoDB 连接问题

如果遇到 MongoDB 连接错误：
1. 确保 MongoDB 服务正在运行
2. 检查 MongoDB 默认端口 (27017) 是否被占用
3. 确认数据库路径是否正确

### 后端服务启动失败

1. 确保所有依赖都已正确安装
2. 检查 MongoDB 连接是否正常
3. 确保端口 5000 未被占用

### 前端开发服务器问题

1. 确保 Node.js 版本兼容
2. 删除 node_modules 目录并重新安装依赖
3. 确保端口 3000 未被占用