YPPF

Last commit GitHub forks

如何运行

环境要求

我们提供了搭建好的 Dev Container 开发环境，并强烈建议开发者和使用VSCode的初学者使用它。此外，我们也提供了在本地进行环境搭建的方法。

使用 VSCode Dev Container 进行开发

需要安装 Docker 和 VSCode 的 devcontainer 扩展。Linux 用户需要额外安装 docker compose。

在 VSCode 中，将主侧栏视图切换至远程资源管理器-开发容器，打开项目根目录。若 devcontainer 启动正常，可以看到：

vscode ➜ /workspace

至此，devcontainer 中相当于一个配置好的 Python 环境，并且无需自行配置 MySQL。

本地环境搭建

安装Python，在项目根目录启动终端
创建虚拟环境
```
python -m venv .env
```
其中.env可以是任何名称，该命令将生成.env文件夹作为虚拟环境，请勿重命名该文件夹。

激活虚拟环境

Windows

 > .env\Scripts\activate
 # 左侧出现(.env)表明成功激活，可通过以下方式检验
 (.env) > where python
 .env\Scripts\python.exe
 (.env) > py -0p # 安装pylauncher的检验方式
 Installed Pythons found by py Launcher for Windows
 (venv)         .env\Scripts\python.exe *

Linux/macOS

 $ source .env/bin/activate
 # 左侧出现(.env)表明成功激活，可通过以下方式检验
 (.env) $ which python
 .env/bin/python

VSCode快捷激活

确认右下角Python环境切换到虚拟环境，如3.10.x('.env': venv)，并启动终端

安装环境依赖

(.env) $ pip install --require-virtualenv -r requirements.txt

初始化配置

创建数据库

CREATE DATABASE yppf CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

创建配置文件

我们使用config.json管理配置项。config_template.json是其完整模板，包含所有可选配置。

复制模板并重命名为config.json，在bash终端中，你也可以运行scripts/default_config.sh。
更新数据库配置

配置项含义示例

NAME 数据库名称 yppf

USER 数据库用户 root

PASSWORD 用户密码（空）

HOST 数据库主机 127.0.0.1

PORT 数据库端口 3306

更新配置文件中django的数据库部分，更多配置项请参考各应用的config.py文件。

配置项	含义	示例
NAME	数据库名称	yppf
USER	数据库用户	root
PASSWORD	用户密码	（空）
HOST	数据库主机	127.0.0.1
PORT	数据库端口	3306

更新和迁移

在每次拉取项目代码后（包括初次下载），你都需要迁移数据库，使其与模型一致。

更新迁移文件
```
python manage.py makemigrations
```
这将在每个具有模型的应用的migrations文件夹生成一些迁移文件，请不要删除它们。
如果你怀疑某个应用（即文件夹）没有更新迁移文件，可以手动检查并更新它，直到不再变化：
```
$ python manage.py makemigrations xxx_app
No change detected
```
执行迁移
```
python manage.py migrate
```
如果迁移失败，数据库将很可能难以恢复，此时最简单的办法是删库重建，执行scripts/remove_migrations.sh，并重新进行更新和迁移。

运行

# http://localhost:8000
python manage.py runserver
# http://localhost
python manage.py runserver 80
python manage.py runserver 0:80
python manage.py runserver 127.0.0.1:80
# http://ip:port
python manage.py runserver ip:port

执行任意一种命令以启动，直到你以Ctrl-C退出或关闭终端。启动后，便能通过对应网址访问，访问http://localhost:8000试试吧~

高级功能

生产/调试模式

在boot/config.py中，将DEBUG常量设为True以启用调试模式。

调试模式便于使用，除非你打算在生产环境部署本项目，否则请设置为调试模式。
管理员

运行python manage.py createsuperuser，根据指示创建管理员账号。

管理员账号可用于登录后台/admin，试着访问http://localhost:8000/admin吧。
交互式执行（Django终端）
```
python manage.py shell
```
安装IPython后使用更便捷：
```
pip install ipython --require-virtualenv
```

常见问题

缺少模块，无法运行：ModuleNotFoundError: 'module_name'

可能因为缺少环境依赖，安装对应模块即可:
```
pip install module_name --require-virtualenv
```
如果使用requirement.txt安装后依然缺少，欢迎提出issue。
缺少环境变量，无法运行

通常提示os.environ找不到键，本项目的生产模式需要设置环境变量以保证安全，请切换到调试模式。
无法连接数据库：django.db.utils.OperationalError: (2003, "Can’t connect to MySQL server on ‘xxx’
- 配置错误：检查已经更新数据库配置并正确设置了config.json
- 若MySQL未启动，请先启动对应服务。
Django配置错误：ImproperlyConfigured

配置文件设置有误，请检查对应配置的config文件并修改。
缺少字段：Unknown column 'xx.xxx' in 'field list'

未执行迁移或模型变动未检出，请参考更新和迁移。必要时可以删库重建。

加入我们

您可以通过多种方式为本项目做出贡献，例如加入项目组、帮助改进代码或编写文档。即使您对编程一无所知，也能做出有意义的贡献，我们十分欢迎您向我们报告错误或提出改进建议。

报告错误和改进建议

若您在使用时遇到错误，或者有设计新功能的想法，请通过issue告诉我们。

若您在使用过程中遇到bug，可以详细描述触发错误的场景和操作，最好保证该错误可以复现。

若在运行代码时发生异常，请在报告中包含错误的traceback上下文信息，并尽量添加该文件的链接，以便查找问题。如有可能，提供能复现错误的代码片段是最直观的方法。

在提出任何建议前，我们希望您能查看是否已有类似提议，避免重复讨论。我们鼓励更具体明确的提案，这比泛泛而谈的交流更高效可行。

贡献代码

您应该使用Git管理代码。fork本仓库，并基于develop分支提交commit，最终提交拉取请求(PR, pull request)。你的任何说明信息都应优先使用中文。

你的 PR 必须满足以下要求，否则将不予受理：

标题清晰
查找并链接关联issue（如果存在）
通过自动化测试：python manage.py test
为每个新增接口编写文档

若您的 PR 品质良好，我们会保留您的详细提交信息，并欢迎您成为协作者。

贡献优质的Pull Request

好的 PR 在提交历史、代码质量、PR信息三方面都表现优秀，具体来说有以下特征：

线性历史：不含merge commit。若与最新的develop分支冲突，请使用rebase代替merge。
原子化提交：每个commit在功能上不可拆分，而非将大量修改堆砌到同一个commit中。
不含零碎修改：极小的修改应该被合并至相关commit中，而非单独提交。
commit信息有意义且易读
符合代码规范，如Google风格指南
代码可读性良好，注释和文档数量适宜
为新增接口编写测试，并提供导出信息（__all__）
同步更新环境说明文件和配置文件
为影响他人的改动申请 PR 标签：如删除、模型修改、环境和配置文件修改等。

致谢

贡献/参与者

感谢所有参与本项目的同学们和朋友们，是大家的帮助让 YPPF 越来越好！

如果觉得本项目对你有帮助，帮忙点个 Star 吧 ~

Yuanpei-Intelligence / YPPF

readme