update docs

wu-clan · wu-clan · commit da774c6f1f5b · 2025-03-11T18:55:13.000+08:00
diff --git a/docs/.vuepress/bulletin.ts b/docs/.vuepress/bulletin.ts
@@ -1,10 +1,9 @@
 import {BulletinOptions} from "vuepress-theme-plume";
 
 export const myBulletin: BulletinOptions = {
-    layout: 'bottom-right',
     enablePage: true,
     lifetime: 'session',
     contentType: 'markdown',
-    // title: 'Vben Admin Antd',
-    content: '欢迎大家闲聊，分享，提供建议，高频艾特，你们的活跃度是我更新的动力',
+    title: 'FasAPI 最佳架构',
+    content: '欢迎大家闲聊，分享，提供建议，高频艾特，你们的活跃度是我更新的动力 🌹',
 }
diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts
@@ -25,9 +25,9 @@ export const mySidebar: SidebarMulti = {
                 {text: '分页', link: 'pagination'},
                 {text: '自定义异常', link: '/planet', icon: 'fluent-color:receipt-16'},
                 {text: '切换数据库', link: 'db'},
+                {text: '鉴权', link: 'permission'},
                 {text: 'JWT', link: 'jwt'},
                 {text: 'RBAC', link: 'RBAC'},
-                {text: '鉴权', link: 'permission'},
                 {text: '数据规则', link: '/planet', icon: 'fluent-color:video-16'},
                 {text: '代码生成', link: 'code-generation'},
                 {text: '跨域', link: 'CORS'},
diff --git a/docs/guide/deploy/Docker.md b/docs/guide/deploy/Docker.md
@@ -24,13 +24,13 @@ title: Docker 部署
 
    在 `backend` 目录中，创建环境变量文件
 
-   ```shell
+   ```shell:no-line-numbers
    touch .env
    ```
 
    将初始化环境变量配置拷贝到环境变量文件中
 
-   ```shell
+   ```shell:no-line-numbers
    cp .env.example .env
    ```
 
@@ -40,15 +40,15 @@ title: Docker 部署
 
    如果容器要在本地启动，需要将 `.env` 中的 `127.0.0.1` 更改为 `host.docker.internal`
 
-   ```shell
-   docker build -f backend/Dockerfile -t fba_backend_independent .
+   ```shell:no-line-numbers
+   docker build -f Dockerfile -t fba_backend_independent .
    ```
 
 5. 启动容器
 
    由于构建不包含数据库，请确保本地已安装并启动相关数据库（mysql / postgresql、redis）
 
-   ```shell
+   ```shell:no-line-numbers
    docker run -d -p 8000:8000 --name fba_server fba_backend_independent
    ```
 
@@ -85,7 +85,8 @@ title: Docker 部署
 
    ::: warning
    如果你需要使用 PostgreSQL 数据库，执行命令前，需修改 `.env.server` 部分配置如下：
-   ```env
+   ```env:no-line-numbers
+   # Database
    DATABASE_TYPE='postgresql'
    DATABASE_HOST='fba_postgres'
    DATABASE_PORT=5432
@@ -102,8 +103,8 @@ title: Docker 部署
    services:
      fba_server:
        build:
-         context: ../../../
-         dockerfile: backend/Dockerfile
+         context: .
+         dockerfile: Dockerfile
        image: fba_server:latest
        container_name: fba_server
        restart: always
@@ -247,8 +248,8 @@ title: Docker 部署
    
      fba_celery:
        build:
-         context: ../../../
-         dockerfile: backend/Dockerfile
+         context: .
+         dockerfile: Dockerfile
          args:
            - SERVER_TYPE=celery
        image: fba_celery:latest
@@ -298,7 +299,7 @@ title: Docker 部署
 
    命令执行期间遇到镜像拉取问题请自行 Google
 
-   ```shell
+   ```shell:no-line-numbers
    docker-compose up -d --build
    ```
 
@@ -311,14 +312,13 @@ title: Docker 部署
 
 1. 拉取代码到服务器
 2. env
-
-   :::: details Arco Desgin Vue
+   ::: tabs
+   @tab <Icon name="icon-park-outline:new-lark" />Arco Desgin Vue
    修改 `.env.production` 中的 `VITE_API_BASE_URL` 为域名地址
-   ::::
 
-   :::: details Vben Admin Antd
-   即将到来...
-   ::::
+   @tab <Icon name="devicon:antdesign" />Vben Admin Antd
+   生产中...
+   :::
 
 3. 更新 nginx 配置
 
@@ -461,19 +461,19 @@ title: Docker 部署
 
    创建网络
 
-   ```shell
+   ```shell:no-line-numbers
    docker network create fba_network
    ```
 
    构建
 
-   ```shell
+   ```shell:no-line-numbers
    docker-compose build fba_ui
    ```
 
    启动
 
-   ```shell
+   ```shell:no-line-numbers
    docker-compose run fba_ui
    ```
 
@@ -491,18 +491,18 @@ title: Docker 部署
 
 清理未使用的镜像
 
-```shell
+```shell:no-line-numbers
 docker image prune
 ```
 
 清理未使用的容器
 
-```shell
+```shell:no-line-numbers
 docker container prune
 ```
 
 清理所有未使用的镜像、容器、网络和构建缓存
 
-```shell
+```shell:no-line-numbers
 docker system prune
 ```
diff --git a/docs/guide/mixin/CRUD.md b/docs/guide/mixin/CRUD.md
@@ -37,7 +37,7 @@ class DateTimeMixin(MappedAsDataclass):
 
 [MappedAsDataclass](https://docs.sqlalchemy.org/en/20/orm/dataclasses.html#orm-declarative-native-dataclasses)
 
-声明性数据类基类, 它将带有数据类集成, 允许使用更高级配置；此基类适用于==不包含日期时间的模型==
+声明性数据类基类, 它将带有数据类集成, 允许使用更高级配置；此基类适用于==不包含日期时间的模型=={.warning}
 
 ```python
 class DataClassBase(MappedAsDataclass, MappedBase):
diff --git a/docs/guide/reference/CORS.md b/docs/guide/reference/CORS.md
@@ -15,7 +15,8 @@ CORS_ALLOWED_ORIGINS: list[str] = [
 
 ## 服务器
 
-HTTP 部署
+::: code-tabs
+@tab <Icon name="arcticons:http-custom" />HTTP
 
 ```py
 # [!code word:http]
@@ -24,7 +25,7 @@ CORS_ALLOWED_ORIGINS: list[str] = [
   ]
 ```
 
-HTTPS 部署
+@tab <Icon name="ic:outline-https" /> HTTPS
 
 ```py
 # [!code word:https]
diff --git a/docs/guide/reference/RBAC.md b/docs/guide/reference/RBAC.md
@@ -95,8 +95,8 @@ fba 中默认使用此鉴权方式
     ```
 
 3. 了解策略
-
-   p 策略：
+   ::: tabs
+   @tab p 策略
     - 添加基于角色的访问权限（推荐）
 
       需要配合添加 g 策略才能实现用户访问权限，适合配置所有用户接口访问策略，拥有此角色的用户便能拥有相应的访问权限<br>
@@ -109,10 +109,10 @@ fba 中默认使用此鉴权方式
 
       格式：`用户 uuid + 访问路径 path + 访问方法 method`
 
-   g 策略（基于 p 策略）：
-    - 添加基于角色的访问权限
+   @tab g 策略
+   当 p 策略为【添加基于角色的访问权限】时，需要此策略
 
-      格式：`用户 uuid + 角色 role`
+   格式：`用户 uuid + 角色 role`
 
 4. 添加策略
 
diff --git a/docs/guide/reference/apscheduler.md b/docs/guide/reference/apscheduler.md
@@ -10,6 +10,6 @@ FastAPI + APScheduler 现已作为独立仓库发行，它的优势在于其灵
 <RepoCard repo="fastapi-practices/fastapi_scheduler" />
 
 ::: warning
-此仓库 master 分支使用 APScheduler 4.x 版本进行开发，但由于 aps
-迟迟未发布 4.x 版本，所以请切换 apscheduler-3.x 分支，它是目前比较流行的版本分支，也相对比较稳定
+此仓库 master 分支使用 APScheduler 4.x 版本进行开发，但由于 APScheduler 迟迟未发布 4.x 版本，所以请切换 apscheduler-3.x
+分支，它是目前比较流行的版本分支，也相对比较稳定
 :::
diff --git a/docs/guide/reference/db.md b/docs/guide/reference/db.md
@@ -10,7 +10,7 @@ fba 支持 MySQL、PostgreSQL 两种数据库，默认配置使用 MySQL
 
 如果本地未安装 PostgreSQL，你可以使用以下命令创建 Docker 镜像
 
-```shell
+```shell:no-line-numbers
 docker run -d --name fba_postgres --restart always -e POSTGRES_DB='fba' -e POSTGRES_PASSWORD='123456' -e TZ='Asia/Shanghai' -v fba_postgres:/var/lib/postgresql/data -p 5432:5432 postgres:16
 ```
 
@@ -19,7 +19,7 @@ docker run -d --name fba_postgres --restart always -e POSTGRES_DB='fba' -e POSTG
 PostgreSQL 与 MySQL 在用户名、端口号等方面有所不同，如果你使用上面的命令创建了 Docker 镜像，需修改 `.env` 部分配置如下，否则，请根据
 PostgreSQL 配置进行修改
 
-```env
+```env:no-line-numbers
 # Database
 DATABASE_TYPE='postgresql'
 DATABASE_HOST='127.0.0.1'
diff --git a/docs/guide/reference/response.md b/docs/guide/reference/response.md
@@ -19,15 +19,15 @@ class ResponseModel(BaseModel):
 以下是使用此模型进行返回的示例（遵循 FastAPI 官方教程），`response_model` 参数和 `->` 类型我们只需选择其中一种方式即可，因为
 FastAPI 会在内部自动解析并获取最终响应结构
 
-`response_model` 参数
+`response_model` 参数：
 
 ```python{1,3}
 @router.get('/test', response_model=ResponseModel)
 def test():
     return ResponseModel(data={'test': 'test'})
 ```
 
-`->` 类型
+`->` 类型：
 
 ```python{2,3}
 @router.get('/test')
@@ -51,15 +51,15 @@ class ResponseSchemaModel(ResponseModel, Generic[SchemaT]):
 
 这是我们创建的用于 Schema 模式的统一返回模型，它的用法与 `ResponseModel` 基本相似
 
-`response_model` 参数
+`response_model` 参数：
 
 ```python{1,3}
 @router.get('/test', response_model=ResponseSchemaModel[GetApiDetail])
 def test():
     return ResponseSchemaModel[GetApiDetail](data=GetApiDetail(...))
 ```
 
-`->` 类型
+`->` 类型：
 
 ```python{2,3}
 @router.get('/test')
@@ -98,7 +98,8 @@ def test() -> ResponseSchemaModel[GetApiDetail]:
 它们都是同步方法，而不是异步。因为这些返回方法并不涉及 io 操作，所以，定义为异步，不但没有性能提升，反而增加了异步协程的开销
 :::
 
-`success()`
+::: tabs
+@tab <Icon name="ix:success-filled" />`success()`
 
 此方法通常作为默认响应方法使用，默认返回信息如下
 
@@ -110,19 +111,19 @@ def test() -> ResponseSchemaModel[GetApiDetail]:
 }
 ```
 
-`fail()`
+@tab <Icon name="ix:namur-failure-filled" />`fail()`
 
 此方法通常在接口响应信息为失败时使用，默认返回信息如下
 
 ```json
 {
-  "code": 200,
-  "msg": "请求成功",
+  "code": 400,
+  "msg": "请求错误",
   "data": null
 }
 ```
 
-`fast_success()`
+@tab <Icon name="ix:certificate-success-filled" />`fast_success()`
 
 此方法通常仅用于接口返回大型 json 时，可为 json 解析性能带来质的提升，默认返回信息如下
 
@@ -134,6 +135,8 @@ def test() -> ResponseSchemaModel[GetApiDetail]:
 }
 ```
 
+:::
+
 ## 响应状态码
 
 在文件 `backend/common/response/response_code.py` 中内置了多种定义响应状态码的方式，我们可以根据 `CustomResponseCode` 和
diff --git a/docs/guide/reference/transaction.md b/docs/guide/reference/transaction.md
@@ -47,8 +47,7 @@ async def create(*, obj: CreateIns) -> None:
 
 ## 如何选择？
 
-以上两种方法，我们更推荐第二种；
+以上两种方法，我们更推荐使用 `begin()`，理由如下：
 
-对于 fba 来说，它更加符合架构风格，并且也能减少千篇一律的接口参数（纯作者强迫症）
-
-而对于无需使用自动提交的事务，我们只需将 `begin()` 方法去掉，直接使用 `async_db_session()` 即可
+1. 对于 fba 来说，它更加符合架构风格，并且也能减少千篇一律的接口参数（纯作者强迫症）
+2. 而对于无需使用自动提交的事务，我们只需将 `begin()` 方法去掉，直接使用 `async_db_session()` 即可
diff --git a/docs/guide/summary/quick-start.md b/docs/guide/summary/quick-start.md
diff --git a/docs/planet.md b/docs/planet.md
diff --git a/docs/plugin/dev.md b/docs/plugin/dev.md
diff --git a/docs/plugin/market.md b/docs/plugin/market.md
diff --git a/docs/sponsors.md b/docs/sponsors.md
