update docs

wu-clan · wu-clan · commit 5aa5f2530949 · 2025-03-26T18:23:58.000+08:00
diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts
@@ -20,7 +20,8 @@ export const mySidebar: SidebarMulti = {
             collapsed: false,
             prefix: 'ide/',
             items: [
-                { text: 'Visual Studio Code', link: 'vscode' }
+                { text: 'Visual Studio Code', link: 'vscode' },
+                { text: 'Cursor', link: 'cursor' },
             ]
         },
         {
diff --git a/docs/code/docker-compose.yml b/docs/code/docker-compose.yml
@@ -157,6 +157,8 @@ services:
     restart: always
     depends_on:
       - fba_rabbitmq
+    volumes:
+      - ./deploy/backend/docker-compose/.env.server:/fba/backend/.env
     networks:
       - fba_network
     command:
diff --git a/docs/code/fastapi.mdc b/docs/code/fastapi.mdc
@@ -0,0 +1,54 @@
+您是 FastAPI 和可扩展 API 开发方面的专家，请严格遵守以下编码规则：
+
+## 依赖管理
+
+- 使用 FastAPI 的依赖注入系统管理状态和共享资源
+- 遵循项目的依赖版本要求：
+    - Python 3.10+
+    - FastAPI
+    - Pydantic v2
+    - Pydantic Settings @backend\core\conf.py
+    - SQLAlchemy 2.0（如果使用 ORM 功能）
+    - SQLAlchemy 配置: @backend\database\db.py
+
+## SQLAlchemy 规范
+
+- 模型类文档只需描述它是什么表
+- 模型类中存在关系属性时在文件开头添加 `from __future__ import annotations`
+- 关系属性 Mapped[] 中的类不要使用字符串
+
+## Schema 规范
+
+- schema 类文档只需描述简短几个字
+- 为 schema 属性添加 Field
+
+## 路由处理规范
+
+- 同步操作使用 `def`
+- 异步操作使用 `async def`
+- `api` 目录下的文件自动跳过任何处理
+- 使用异步函数处理 I/O 绑定任务
+- 理解并遵循 @backend\common\response\response_schema.py 的返回模式
+- 保持 API 响应格式的一致性
+
+## 性能优化规范
+
+- 接口函数内的阻塞型事件使用 run_in_threadpool 处理
+- 尽量减少阻塞 I/O 操作
+- 在所有数据库调用和外部 API 请求中使用异步操作
+- 使用 Redis 工具 @backend\database\redis.py，对静态数据和频繁访问的数据实施缓存
+- 优先考虑 API 性能指标（响应时间、延迟、吞吐量）
+
+## 错误处理规范
+
+- 使用 FastAPI 的异常处理机制
+- 统一错误响应格式
+- 根据错误工厂 @backend\common\exception\errors.py 提供清晰的错误信息和错误码
+- 记录关键错误信息到日志系统 @backend\common\log.py
+
+## 数据验证规范
+
+- 使用 Pydantic 模型进行数据验证
+- 定义清晰的请求和响应模型，参考：@backend\app\admin\schema\user.py
+- 不要新增字段验证器
+- 提供有意义的验证错误信息
diff --git a/docs/code/python.mdc b/docs/code/python.mdc
@@ -0,0 +1,80 @@
+您是 Python 3.10+ 方面的专家，请严格遵守以下编码规则：
+
+## 类型注解规范
+
+- 使用 Python 3.10+ 的类型/注解语法
+- 只在必要时使用 `Any` 类型，如果使用了则必须保留
+- 为所有函数参数和返回值添加类型注解，args, kwargs 参数直接忽略注解
+- 为字典返回值添加具体的类型注解（如 `dict[str, Any]`）
+- 为列表返回值添加具体的类型注解（如 `list[dict[str, str]]`）
+
+## 文档注释规范
+
+- 不要在文件开头添加注释
+- 函数文档格式如下：
+    1. 有参数的函数：
+        - 使用多行文档字符串
+        - 跳过第一行
+        - 编写函数文档
+        - 空一行
+        - 参数说明格式为 ":param 参数名: 参数说明"
+        - 返回说明格式为 ":return: 不添加返回说明"
+    2. 无参数的函数：
+        - 使用单行文档字符串
+        - 只写函数描述
+        - 描述和引号在同一行
+    3. 通用要求：
+        - 函数描述要简洁明了
+        - 不需要举例说明
+        - 中英文之间要有空格
+- 参数说明要具体和清晰
+- 如果函数没有入参且描述只有简短文字，那么引号和内容写在同一行
+- 如果函数被 model_validator 或 field_validator 注释，则只需添加函数描述即可
+
+## 代码逻辑规范
+
+- 在保证逻辑清晰的情况下，尽量避免使用多元表达式（如三元运算符）
+- 保持代码的可读性和可维护性
+- 使用提前返回模式简化代码
+- 移除不必要的中间变量
+- 添加适当的空行，提高代码可读性
+- 优先处理错误和边缘案例
+- 只要必要时添加 try
+- 对错误条件使用提前返回，以避免嵌套较深的 if 语句
+- 避免不必要的 else 语句，而应使用 if-return 模式
+- 实施适当的错误记录和用户友好型错误信息
+- 使用自定义错误类型或错误工厂进行一致的错误处理
+
+## 代码格式规范
+
+- 统一代码风格
+- 保持适当的空行
+- 优化长行（超过 120 个字符）的格式
+- 使用括号进行换行
+- 保持一致的缩进
+
+## 代码注释规范
+
+- 每个 py 文件开头都需添加以下内容
+    ```
+    #!/usr/bin/env python3
+    # -*- coding: utf-8 -*-
+    ```
+- 合理的注释，避免不必要的注释
+- 中英文之间应包加空格
+- 注释文字描述应具体和清晰
+- 注释要让人视觉上更清晰
+
+## 命名规范
+
+- 变量名要具有描述性
+- 避免使用单字母变量名（除非是循环变量）
+- 使用下划线命名法（snake_case）
+- 类名使用大驼峰命名法（PascalCase）
+
+## 函数定义规范
+
+- 纯函数使用 `def`
+- 异步操作使用 `async def`
+- 函数尽量单一职责，避免过于复杂的函数，但也不要过于琐碎
+- 不要擅自修改任何参数命名
diff --git a/docs/guide/deploy/Docker.md b/docs/guide/deploy/Docker.md
@@ -54,7 +54,7 @@ title: Docker 部署
 > 此教程以 https 为例，如果你没有相关经验，请自行 Google 进行了解
 
 > [!NOTE]
-> 免费 SSL 证书推荐使用 [httpsok-SSL证书自动续期](https://httpsok.com/p/4Qjd)，一行命令，轻松搞定 SSL
+> 免费 SSL 证书推荐使用 [httpsok-SSL 证书自动续期](https://httpsok.com/p/4Qjd)，一行命令，轻松搞定 SSL
 > 证书自动续签，支持：nginx、通配符证书、七牛云、腾讯云、阿里云、CDN、OSS、LB（负载均衡）
 
 ### 后端
@@ -70,15 +70,22 @@ title: Docker 部署
 
 2. env
 
+   在 `backend` 目录中，创建环境变量文件
+
+   ```shell:no-line-numbers
+   touch .env
+   ```
+
    进入 `deploy/backend/docker-compose` 目录，按需修改 `.env.server` 文件
 
-   ::: note
-   我们在 docker-compose 脚本内通过挂载的方式直接使用此文件作为 fba 环境变量文件，因此，本地修改此文件，将同步更新至 docker
+   ::: tip
+   我们在 docker-compose 脚本内通过挂载的方式使用 `.env.server` 文件作为 fba 环境变量文件，因此，本地修改此文件，将同步更新至 docker
    容器，这意味着，修改环境变量将无需重新 build
    :::
 
    ::: warning
-   如果你需要使用 PostgreSQL 数据库，执行命令前，需修改 `.env.server` 部分配置如下：
+   如果您正在使用 PostgreSQL 数据库，需修改 `.env.server` 部分配置如下：
+
    ```dotenv:no-line-numbers
    # Database
    DATABASE_TYPE='postgresql'
@@ -87,12 +94,13 @@ title: Docker 部署
    DATABASE_USER='postgres'
    DATABASE_PASSWORD='123456'
    ```
+
    :::
 
 3. 按需修改配置文件 `backend/core/conf.py`
 
 4. 更新脚本文件
-   
+
    @[code yml :collapsed-lines=6](../../code/docker-compose.yml)
 
 5. 务必在 `docker-compose.yml` 所在目录打开终端
@@ -126,7 +134,7 @@ title: Docker 部署
 3. 更新 nginx 配置
 
    进入 deploy 目录，修改 `nginx.conf` 文件
-  
+
    @[code nginx :collapsed-lines=6](../../code/nginx.conf)
 
 4. 更新脚本文件
@@ -139,11 +147,11 @@ title: Docker 部署
    networks:
      fba_network:
        external: true
-   
+
    volumes:
      fba_static:
        external: true
-   
+
    services:
      fba_ui:
        build:
diff --git a/docs/guide/ide/cursor.md b/docs/guide/ide/cursor.md
@@ -0,0 +1,31 @@
+---
+title: cursor
+---
+
+官网地址：[cursor](https://www.cursor.com/)
+
+我们在 cursor 中为 fba 定做了一些规则，或许可以帮助您更好的使用 AI 生成代码
+
+::: warning
+我们未对规则进行 token 消耗量测试，请根据实际情况自行抉择
+:::
+
+## 规则
+
+查看 cursor 官方文档：[rules-for-ai](https://docs.cursor.com/context/rules-for-ai)，然后添加以下规则：
+
+### Python
+
+::: note
+此规则可用于任何 Python 3.10+ 项目
+:::
+
+@[code mdc](../../code/python.mdc)
+
+### FastAPI
+
+::: tip
+此规则仅限用于 fba 项目
+:::
+
+@[code mdc](../../code/fastapi.mdc)
diff --git a/docs/guide/summary/quick-start.md b/docs/guide/summary/quick-start.md
@@ -17,7 +17,7 @@ title: 快速开始
 ### 后端
 
 ::: tip
-如果你是 PostgreSQL 用户，请先移步到 [切换数据库](../reference/db.md)
+如果您是 PostgreSQL 用户，请先移步到 [切换数据库](../reference/db.md)
 :::
 
 :::: steps

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,8 @@ export const mySidebar: SidebarMulti = {`
`20`	`20`	`collapsed: false,`
`21`	`21`	`prefix: 'ide/',`
`22`	`22`	`items: [`
`23`		`- { text: 'Visual Studio Code', link: 'vscode' }`
	`23`	`+ { text: 'Visual Studio Code', link: 'vscode' },`
	`24`	`+ { text: 'Cursor', link: 'cursor' },`
`24`	`25`	`]`
`25`	`26`	`},`
`26`	`27`	`{`