pyxr/DEVELOPMENT.md

开发指南

环境要求

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

数据库配置

1. 安装 MongoDB

   • Windows: 参考 https://www.runoob.com/mongodb/mongodb-window-install.html
   • macOS: 使用 Homebrew 安装

     brew tap mongodb/brew
     brew install mongodb-community
     

2. 启动 MongoDB 服务

   # Windows
   mongod --dbpath <你的数据库路径>
   
   # macOS
   brew services start mongodb-community
   

3. 验证 MongoDB 是否正常运行

   mongosh
   use flask_db
   show dbs
   

后端服务启动

1. 安装 Python 依赖

   # 如果使用 poetry
   poetry install
   
   # 如果使用 pip
   pip install -r requirements.txt
   

2. 启动 Flask 服务器

   # 使用 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. 进入前端目录

   cd src/frontend
   

2. 安装依赖

   npm install
   

3. 启动开发服务器

   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. 安装测试依赖

   # 使用 poetry 添加测试依赖
   poetry add pytest --dev
   
   # 如果使用 pip
   pip install pytest
   

2. 运行测试 使用 Poetry 运行测试：

# 运行所有测试
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 未被占用