docs(dev): update contribution guide & agent instructions

2025-10-04 06:10:40 +00:00
parent 216d3ab3bf
commit c6058eb0d8
4 changed files with 376 additions and 154 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,9 +54,123 @@ dotnet run --project osu.Server.Spectator --urls "http://0.0.0.0:8086"
 uv sync
 ```

-## 代码质量和代码检查
+## 开发规范

-我们使用 `pre-commit` 在提交之前执行代码质量标准。这确保所有代码都通过 `ruff`（用于代码检查和格式化）和 `pyright`（用于类型检查）的检查。
+### 项目结构
+
+以下是项目主要目录和文件的结构说明：
+
+-   `main.py`: FastAPI 应用的主入口点，负责初始化和启动服务器。
+-   `pyproject.toml`: 项目配置文件，用于管理依赖项 (uv)、代码格式化 (Ruff) 和类型检查 (Pyright)。
+-   `alembic.ini`: Alembic 数据库迁移工具的配置文件。
+-   `app/`: 存放所有核心应用代码。
+    -   `router/`: 包含所有 API 端点的定义，根据 API 版本和功能进行组织。
+    -   `service/`: 存放核心业务逻辑，例如用户排名计算、每日挑战处理等。
+    -   `database/`: 定义数据库模型 (SQLModel) 和会话管理。
+    -   `models/`: 定义非数据库模型和其他模型。
+    -   `tasks/`: 包含由 APScheduler 调度的后台任务和启动/关闭任务。
+    -   `dependencies/`: 管理 FastAPI 的依赖项注入。
+    -   `achievements/`: 存放与成就相关的逻辑。
+    -   `storage/`: 存储服务代码。
+    -   `fetcher/`: 用于从外部服务（如 osu! 官网）获取数据的模块。
+    -   `middleware/`: 定义中间件，例如会话验证。
+    -   `helpers/`: 存放辅助函数和工具类。
+    -   `config.py`: 应用配置，使用 pydantic-settings 管理。
+    -   `calculator.py`: 存放所有的计算逻辑，例如 pp 和等级。
+    -   `log.py`: 日志记录模块，提供统一的日志接口。
+    -   `const.py`: 定义常量。
+    -   `path.py`: 定义跨文件使用的常量。
+-   `migrations/`: 存放 Alembic 生成的数据库迁移脚本。
+-   `static/`: 存放静态文件，如 `mods.json`。
+
+### 数据库模型定义
+
+所有的数据库模型定义在 `app.database` 里，并且在 `__init__.py` 中导出。
+
+如果这个模型的数据表结构和响应不完全相同，遵循 `Base` - `Table` - `Resp` 结构：
+
+```python
+class ModelBase(SQLModel):
+    # 定义共有内容
+    ...
+
+
+class Model(ModelBase, table=True):
+    # 定义数据库表内容
+    ...
+
+
+class ModelResp(ModelBase):
+    # 定义响应内容
+    ...
+
+    @classmethod
+    def from_db(cls, db: Model) -> "ModelResp":
+        # 从数据库模型转换
+        ...
+```
+
+数据库模块名应与表名相同，定义了多个模型的除外。
+
+如果你需要使用 Session，使用 `app.dependencies.database` 提供的 `with_db`，注意手动使用 `COMMIT`。
+
+```python
+from app.dependencies.database import with_db
+
+async with with_db() as session:
+    ...
+```
+
+### Redis
+
+根据你需要的用途选择对应的 Redis 客户端。如果你的用途较为复杂或趋向一个较大的系统，考虑再创建一个 Redis 连接。
+
+- `redis_client` (db0)：标准用途，存储字符串、哈希等常规数据。
+- `redis_message_client` (db1)：用于消息缓存，存储聊天记录等。
+- `redis_binary_client` (db2)：用于存储二进制数据，如音频文件等。
+- `redis_rate_limit_client` (db3)：仅用于 FastAPI-Limiter 使用。
+
+### API Router
+
+所有的 API Router 定义在 `app.router` 里：
+
+- `app/router/v2` 存放所有 osu! v2 API 实现，**不允许添加额外的，原 v2 API 不存在的 Endpoint**
+- `app/router/notification` **存放所有 osu! v2 API 聊天、通知和 BanchoBot 的实现，不允许添加额外的，原 v2 API 不存在的 Endpoint**
+- `app/router/v1` 存放所有 osu! v1 API 实现，**不允许添加额外的，原 v1 API 不存在的 Endpoint**
+- `app/router/auth.py` 存放账户鉴权/登录的 API
+- `app/router/private` 存放服务器自定义 API (g0v0 API)，供其他服务使用
+
+任何 Router 需要满足：
+
+- 使用 Annotated-style 的依赖注入
+- 对于已经存在的依赖注入如 Database 和 Redis，使用 `app.dependencies` 中的实现
+- 需要拥有文档
+- 如果返回需要资源代理，使用 `app.helpers.asset_proxy_helper` 的 `asset_proxy_response` 装饰器。
+- 如果需要记录日志，请使用 `app.log` 提供的 `log` 函数获取一个 logger 实例
+
+### Service
+
+所有的核心业务逻辑放在 `app.service` 里：
+
+- 业务逻辑需要要以类实现
+- 日志只需要使用 `app.log` 中的 `logger` 即可。服务器会对 Service 的日志进行包装。
+
+### 定时任务/启动任务/关闭任务
+
+均定义在 `app.tasks` 里。
+
+- 均在 `__init__.py` 进行导出
+- 对于启动任务/关闭任务，在 `main.py` 的 `lifespan` 调用。
+- 定时任务使用 APScheduler
+
+### 耗时任务
+
+- 如果这个任务来自 API Router，请使用 FastAPI 提供的 [`BackgroundTasks`](https://fastapi.tiangolo.com/tutorial/background-tasks)
+- 其他情况，使用 `app.utils` 的 `bg_tasks`，它提供了与 FastAPI 的 `BackgroundTasks` 类似的功能。
+
+### 代码质量和代码检查
+
+使用 `pre-commit` 在提交之前执行代码质量标准。这确保所有代码都通过 `ruff`（用于代码检查和格式化）和 `pyright`（用于类型检查）的检查。

 ### 设置

@@ -70,19 +184,9 @@ pre-commit install

 pre-commit 不提供 pyright 的 hook，您需要手动运行 `pyright` 检查类型错误。

-## 提交信息指南
+### 提交信息指南

-我们遵循 [AngularJS 提交规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit-message-format) 来编写提交信息。这使得在查看项目历史记录时，信息更加可读且易于理解。
-
-每条提交信息由 **标题**、**主体**和 **页脚** 三部分组成。
-
-```
-<type>(<scope>): <subject>
-<BLANK LINE>
-<body>
-<BLANK LINE>
-<footer>
-```
+遵循 [AngularJS 提交规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit-message-format) 来编写提交信息。

 **类型** 必须是以下之一：

@@ -97,40 +201,16 @@ pre-commit 不提供 pyright 的 hook，您需要手动运行 `pyright` 检查
 *   **ci**：持续集成相关的更改
 *   **deploy**: 部署相关的更改

-**范围** 可以是任何指定提交更改位置的内容。例如 `api`、`db`、`auth` 等等。
+**范围** 可以是任何指定提交更改位置的内容。例如 `api`、`db`、`auth` 等等。对整个项目的更改使用 `project`。

 **主题** 包含对更改的简洁描述。

-## 项目结构
+### 持续集成检查

-以下是项目主要目录和文件的结构说明：
+所有提交应该通过以下 CI 检查：

-   `main.py`: FastAPI 应用的主入口点，负责初始化和启动服务器。
-   `pyproject.toml`: 项目配置文件，用于管理依赖项 (uv)、代码格式化 (Ruff) 和类型检查 (Pyright)。
-   `alembic.ini`: Alembic 数据库迁移工具的配置文件。
-   `app/`: 存放所有核心应用代码。
-    -   `router/`: 包含所有 API 端点的定义，根据 API 版本和功能进行组织。
-    -   `service/`: 存放核心业务逻辑，例如用户排名计算、每日挑战处理等。
-    -   `database/`: 定义数据库模型 (SQLModel) 和会话管理。
-    -   `models/`: 定义非数据库模型和其他模型。
-    -   `scheduler/`: 包含由 APScheduler 调度的后台任务。
-    -   `dependencies/`: 管理 FastAPI 的依赖项注入。
-    -   `achievement.py`: 存放与成就相关的逻辑。
-    -   `storage/`: 存储服务代码。
-    -   `fetcher/`: 用于从外部服务（如 osu! 官网）获取数据的模块。
-    -   `config.py`: 应用配置，使用 pydantic-settings 管理。
-    -   `calculator.py`: 存放所有的计算逻辑，例如 pp 和等级。
-   `migrations/`: 存放 Alembic 生成的数据库迁移脚本。
-   `packages/`: 包含项目相关的独立包。
-    -   `msgpack_lazer_api/`: 基于 Rust 的高性能支持 lazer APIMod 的 MessagePack 解析模块，用于与 osu!lazer 客户端通信。
-   `static/`: 存放静态文件，如 `mods.json`。
-
-## API Router 规范
-
- `app/router/v2` 存放所有 osu! v2 API 实现，不允许添加额外的，原 v2 API 不存在的 Endpoint
- `app/router/notification` 存放所有 osu! v2 API 聊天和通知的实现，不允许添加额外的，原 v2 API 不存在的 Endpoint
- `app/router/v1` 存放所有 osu! v1 API 实现，不允许添加额外的，原 v1 API 不存在的 Endpoint
- `app/router/auth.py` 存放账户鉴权/登录的 API
- `app/router/private` 存放服务器自定义 API，供其他服务使用
+- Ruff Lint
+- Pyright Lint
+- pre-commit

 感谢您的贡献！