update docs

wu-clan · wu-clan · commit f3a62c630f8c · 2025-11-03T13:24:31.000+08:00
diff --git a/docs/.vuepress/data/plugin.ts b/docs/.vuepress/data/plugin.ts
@@ -5,50 +5,50 @@ export const pluginItems: PluginItem[] = [
         icon: "fa6-regular:file-code",
         title: "代码生成",
         description: "生成通用业务代码",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "fe:notice-active",
         title: "通知公告",
         description: "发布系统内部通知、公告",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "fluent-mdl2:dictionary",
         title: "数据字典",
         description: "通常用于约束前端工程数据传输/展示",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "icon-park-outline:config",
         title: "参数配置",
         description: "通常用于动态配置系统参数/前端工程数据展示",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "logos:oauth",
         title: "OAuth 2.0",
         description: "通过 OAuth 2.0 的方式登录系统",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "ic:twotone-email",
         title: "Email",
         description: "发送电子邮件，例如验证码、通知等",
-        tags: ["mysql", "pgsql", "后端", "前端"],
+        tags: ["pgsql", "mysql", "后端", "前端"],
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
     {
         icon: "charm:shield-keyhole",
         title: "Casbin-RBAC",
         description: "基于 Casbin 实现的 RBAC 权限",
         label: '官方',
-        tags: ["mysql", "pgsql", "后端"],
+        tags: ["pgsql", "mysql", "后端"],
         link: "https://github.com/fastapi-practices/casbin_rbac",
         image: "https://avatars.githubusercontent.com/u/27810343?s=200&v=4",
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
@@ -58,7 +58,7 @@ export const pluginItems: PluginItem[] = [
         title: "MCP 服务器管理",
         description: "提供了 MCP 服务器管理功能，并添加了可调用 MCP 的 AI 聊天接口",
         label: '官方',
-        tags: ["mysql", "pgsql", "后端"],
+        tags: ["pgsql", "mysql", "后端"],
         link: "https://github.com/fastapi-practices/mcp",
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
     },
@@ -67,7 +67,7 @@ export const pluginItems: PluginItem[] = [
         title: "阿里云 oss",
         description: "阿里云 oss 文件上传",
         label: '官方',
-        tags: ["mysql", "pgsql", "后端"],
+        tags: ["pgsql", "mysql", "后端"],
         link: "https://github.com/fastapi-practices/aliyun_oss",
         image: "https://registry.npmmirror.com/@lobehub/icons-static-png/latest/files/dark/alibabacloud-color.png",
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
@@ -97,7 +97,7 @@ export const pluginItems: PluginItem[] = [
         title: "Casdoor SSO",
         description: "通过 Casdoor 实现 SSO 单点登录集成",
         label: '官方',
-        tags: ["unfree", "mysql", "pgsql", "后端"],
+        tags: ["unfree", "pgsql", "mysql", "后端"],
         link: "https://github.com/fastapi-practices/casdoor_sso",
         image: "https://casdoor.org/zh/img/casdoor.png",
         logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
@@ -107,7 +107,7 @@ export const pluginItems: PluginItem[] = [
         title: "LDAP",
         description: "通过 LDAP 登录系统并授权",
         label: '第三方',
-        tags: ["mysql", "pgsql", "后端"],
+        tags: ["pgsql", "mysql", "后端"],
         link: "https://github.com/dividduang/ldap_auth",
         image: "https://www.cleo.com/sites/default/files/2023-12/ldap-integration.png",
         logo: 'https://avatars.githubusercontent.com/u/110005582?v=4',
@@ -117,7 +117,7 @@ export const pluginItems: PluginItem[] = [
         title: "腾讯云 sms",
         description: "通过腾讯云短信服务发送短信验证码",
         label: '第三方',
-        tags: ["mysql", "pgsql", "后端"],
+        tags: ["pgsql", "mysql", "后端"],
         link: "https://github.com/RanY-Luck/fba_plugin_sms",
         image: "https://registry.npmmirror.com/@lobehub/icons-static-png/latest/files/dark/tencentcloud-color.png",
         logo: 'https://avatars.githubusercontent.com/u/67427627?v=4',
diff --git a/docs/backend/reference/CORS.md b/docs/backend/reference/CORS.md
@@ -43,15 +43,3 @@ CORS_ALLOWED_ORIGINS: list[str] = [
 ```py
 CORS_ALLOWED_ORIGINS: list[str] = ['*']
 ```
-
-## 注意事项
-
-::: warning
-当将 `CORS_ALLOWED_ORIGINS` 配置为 `['*']` 时，socketio 将无法正常工作，这是由于它们的配置方式不同所导致的
-
-这里有一个相关 PR: [python-engineio/pull/410](https://github.com/miguelgrinberg/python-engineio/pull/410)
-
-虽然它已被合并，但是并没有发布新版本，截至目前，您需要在 `backend/common/socketio/server.py` 文件中修改以下内容：
-
-`cors_allowed_origins=settings.CORS_ALLOWED_ORIGINS` -> `cors_allowed_origins='*'`
-:::
diff --git a/docs/backend/reference/code-generation.md b/docs/backend/reference/code-generation.md
@@ -2,8 +2,13 @@
 title: 代码生成
 ---
 
-> [!WARNING]
-> API 调用无法直观的预览代码生成结果，它必须配合前端项目使用，请查看查看 [效果预览](#效果预览)
+::: tip
+此功能当前仅适用于后端工程，不包含前端代码
+:::
+
+::: warning
+API 调用无法直观的预览代码生成结果，它必须配合前端项目使用，请查看查看 [效果预览](#效果预览)
+:::
 
 ## 概念
 
diff --git a/docs/backend/reference/data-permission.md b/docs/backend/reference/data-permission.md
@@ -2,23 +2,27 @@
 title: 数据权限
 ---
 
-数据权限是为了给数据添加权限而建立的，我们最常见的实现方式是仅本人数据，本部门数据...
+数据权限是为了给数据添加权限而建立的，我们最常见的实现方案是仅本人数据，本部门数据...
 这些就是所谓的数据权限，你可以控制不同的角色拥有不同的数据权限，从而实现用户和数据的隔离
 
-## 弊端
+## 常见方案
 
-如上所述，我们常见的这种数据权限，在大多数情况下，也能够满足日常场景所需，但是，这种常见的方式存在严重的弊端。由于数据权限的数据过滤是通过
-SQL 语句拼接进行实现的，而这些固定权限，直接写死了数据权限的要求，例如：业务表必须包含 dept_id 和 created_by 字段，
-如果没有这些业务字段，你就无法通过 SQL 来控制数据权限，下面是我对这种常规数据权限的实现，仅供参考：
+::: caution
+fba 已删除此集成方式，此代码仅作为示例保留
+:::
 
 @[code python](../../code/data_perm.py)
 
-请注意，当前 fba 中已删除此集成方式，你需要自行更新角色 model、schema，添加数据权限控制标识字段 data_scope 等相关代码
+### 弊端
 
-## 想法
+我们常见的这种数据权限，在大多数情况下，也能够满足日常场景所需，但是，这种方式存在严重的弊端。由于数据权限的数据过滤是通过
+SQL 语句拼接进行实现的，而这些固定权限，直接写死了数据权限的要求
 
-有没有一种更加灵活的方案呢，答案是，当然有，目前，我们在 fba
-中实现的正式超灵活方案，但是相对于常见方案来讲，可配更加复杂，但我们仍有很大的优化空间
+例如：业务表必须包含 dept_id 和 created_by 字段，如果业务表没有这些字段，你就无法通过 SQL 来控制数据权限
 
-你可以直接查看代码源文件 `backend/common/security/permission.py`，其中，filter\_data\_permission
-方法正是我们使用灵活方案，它与常规数据权限使用近乎相同的方式实现数据过滤，但由于其复杂性，下面，我们将通过视频进行讲解： [数据权限管理](https://www.bilibili.com/video/BV13hioY1EQU/?share_source=copy_web\&vd_source=ccb2aae47e179a51460c20d165021cb7)
+## 内置方案
+
+有没有一种更加灵活的方案呢，答案是，当然有，目前，我们在 fba 中实现的正是超灵活方案，但相比于常见方案来讲，配置会更加复杂
+
+你可以直接查看代码源文件 `backend/common/security/permission.py`
+，它与常规方案使用近乎相同的方式实现数据过滤，但由于其复杂性，下面，我们将通过视频进行讲解： [数据权限管理](https://www.bilibili.com/video/BV13hioY1EQU/?share_source=copy_web\&vd_source=ccb2aae47e179a51460c20d165021cb7)
diff --git a/docs/backend/reference/model.md b/docs/backend/reference/model.md
@@ -8,6 +8,8 @@ title: 模型
 
 我们未提供自动主键模式，而是必须通过手动定义的方式进行主键声明
 
+### 自增 ID
+
 ```python
 # 通用 Mapped 类型主键, 需手动添加，参考以下使用方式
 # MappedBase -> id: Mapped[id_key]
@@ -26,6 +28,10 @@ id_key = Annotated[
 ]
 ```
 
+### 雪花 ID
+
+[请移步至 **切换主键**](pk.md){.read-more}
+
 ## Mixin 类
 
 [Mixin](https://en.wikipedia.org/wiki/Mixin) 是一种面向对象编程概念, 使结构变得更加清晰
@@ -34,7 +40,7 @@ id_key = Annotated[
 
 用于集成操作人信息到数据库表
 
-[使用方法请移步至 **操作人**](operator.md){.read-more}
+[请移步至 **操作人**](operator.md){.read-more}
 
 ### 日期时间
 
diff --git a/docs/backend/reference/oauth2.md b/docs/backend/reference/oauth2.md
@@ -3,7 +3,7 @@ title: OAuth 2.0
 ---
 
 我们在 fba 中使用 [fastapi-oauth20](https://github.com/fastapi-practices/fastapi-oauth20) 集成 OAuth 2.0，您可以在
-`backend/app/admin/api/v1/oauth2` 目录中查看我们的官方实现示例
+`backend/plugin/oauth2` 目录中查看我们的官方实现示例
 
 ::: note
 此授权方式适用于第三方平台认证登录，第三方授权成功后，将依据第三方平台信息自动创建本地用户并自动授权登录，用户只需同意第三方授权即可
diff --git a/docs/backend/reference/transaction.md b/docs/backend/reference/transaction.md
@@ -1,5 +1,5 @@
 ---
-title: SQLA 事务
+title: 事务
 ---
 
 默认情况下，如果将数据库引擎参数 `echo` 设置为 True，你将会看到事务总是被开启，即便那是一个查询语句。但这并不是因为我们错误的使用了
@@ -13,10 +13,9 @@ SQLAlchemy，你可以查看 [#6921](https://github.com/sqlalchemy/sqlalchemy/di
 ，详情请查看: [了解 DBAPI 级别的 Autocommit 隔离级别](https://docs.sqlalchemy.org.cn/en/20/core/connections.html#understanding-the-dbapi-level-autocommit-isolation-level)
 :::
 
-## Session 生成器
+## CurrentSession
 
-这是一种类似于官方文档的使用方法，但这种方法并没有真正达到事务的目的，因为它不会自动执行提交，所以，你可以将它理解为仅适用于查询，否则，必须手动执行
-`commit()` 方法
+这是一种类似于官方文档的使用方法，但这种方法并没有真正开启事务，它通常仅用于查询操作
 
 ```python
 async def get_db() -> AsyncGenerator[AsyncSession, None]:
@@ -36,19 +35,35 @@ async def get_pagination_apis(db: CurrentSession) -> ResponseModel:
     ...
 ```
 
+## CurrentSessionTransaction
+
+与 `CurrentSession` 不同，此方法将直接自动开启事务，你可以将它用于增删改操作
+
+```python
+async def get_db_transaction() -> AsyncGenerator[AsyncSession, None]:
+    """获取带有事务的数据库会话"""
+    async with async_db_session.begin() as session:
+        yield session
+
+# Session Annotated
+CurrentSessionTransaction = Annotated[AsyncSession, Depends(get_db_transaction)]
+```
+
+使用方法与 `CurrentSession` 相同
+
+```python
+@router.post('')
+async def get_pagination_apis(db: CurrentSession) -> ResponseModel:
+    ...
+```
+
 ## `begin()`
 
-这种方式由 SQLAlchemy 官方实现，在线程安全方面，由于在同一个函数中，可能存在多次调用，所以没有 Session 生成器严谨
+这种方式由 SQLAlchemy 官方实现，在线程安全方面，由于在同一个函数中，可能存在多次调用，所以没有 `CurrentSession` 和
+`CurrentSessionTransaction` 更加严谨，但此方式可以在任意地方使用
 
 ```python{2}
 async def create(*, obj: CreateIns) -> None:
     async with async_db_session.begin() as db:
         await xxx_dao.create(db, obj)
 ```
-
-## 如何选择？
-
-以上两种方法，我们更推荐使用 `begin()`，理由如下：
-
-1. 对于 fba 来说，它更加符合架构风格，并且也能减少千篇一律的接口参数（纯作者强迫症）
-2. 而对于无需使用自动提交的事务，我们只需将 `begin()` 方法去掉，直接使用 `async_db_session()` 即可
diff --git a/docs/backend/summary/fsm.md b/docs/backend/summary/fsm.md
@@ -6,6 +6,10 @@ FastAPI 最佳架构精简版的目标是仅保留最最最简单的架构代码
 
 ## SQLAlchemy
 
+::: caution
+此版本的更新速度并不同步，我们目前正在积极寻找维护人员
+:::
+
 <LinkCard
 title="fastapi_sqlalchemy_mysql"
 description="fastapi + pydantic-v2 + sqlalchemy 2.0 + alembic + mysql + redis"
diff --git a/docs/backend/summary/intro.md b/docs/backend/summary/intro.md
@@ -10,7 +10,7 @@ mvc 架构作为常规设计模式，在 python web 中很常见，但是三层
 
 在 python web 开发中，三层架构的概念并没有通用标准，所以这里我们称之为伪三层架构
 
-！！！但请注意！！！
+！但请注意 ！
 
 我们并没有传统的多 app （微服务）目录结构（django、springBoot...），而是[自以为是的目录结构](#项目结构)
 
diff --git a/docs/backend/summary/quick-start.md b/docs/backend/summary/quick-start.md
@@ -20,8 +20,8 @@ fba 仅适用于资深 Python 后端开发人员，如果您是非资深用户
 
 2. 创建数据库：`fba`
 
-   - PostgreSQL 用户直接创建
-   - MySQL 用户创建时需选择 utf8mb4 编码
+    - PostgreSQL 用户直接创建
+    - MySQL 用户创建时需选择 utf8mb4 编码
 
 3. 启动 Redis
 4. 准备源码 <Badge type="warning" text="二选一" />
@@ -93,42 +93,42 @@ fba 仅适用于资深 Python 后端开发人员，如果您是非资深用户
    ```
    :::
 
-9. 启动 celery worker, beat 和 flower <Badge type="warning" text="此步骤为可选，可直接跳过" />
+9. 启动
 
-   在 `根目录` 打开终端，执行以下命令启动 celery 相关服务
+   在 `根目录` 打开终端，执行以下命令启动 FastAPI 服务
 
-   ::: code-tabs
-   @tab Worker
+   ```shell:no-line-numbers
+   fba run
+   ```
 
-    ```shell:no-line-numbers
-    fba celery worker
-    ```
+10. 启动 celery worker, beat 和 flower <Badge type="warning" text="此步骤为可选，可直接跳过" />
 
-   @tab Beat
+    在 `根目录` 打开终端，执行以下命令启动 celery 相关服务
 
-    ```shell:no-line-numbers
-    fba celery beat
-    ```
+    ::: code-tabs
+    @tab Worker
 
-   @tab Flower
+     ```shell:no-line-numbers
+     fba celery worker
+     ```
 
-    ```shell:no-line-numbers
-    fba celery flower
-    ```
-   :::
+    @tab Beat
 
-   ::: warning
-   如果从未执行过以上命令，任务结果表将缺失，此时，无论从何处调用任务结果相关接口都会直接报错，直到至少启动一次 worker 和
-   beat 服务，相关接口将自动恢复正常
-   :::
+     ```shell:no-line-numbers
+     fba celery beat
+     ```
 
-10. 启动
+    @tab Flower
 
-    在 `根目录` 打开终端，执行以下命令启动 FastAPI 服务
+     ```shell:no-line-numbers
+     fba celery flower
+     ```
+    :::
 
-    ```shell:no-line-numbers
-    fba run
-    ```
+    ::: warning
+    如果从未执行过以上命令，任务结果表将缺失，此时，无论从何处调用任务结果相关接口都会直接报错，直到至少启动一次 worker 和
+    beat 服务，相关接口将自动恢复正常
+    :::
 
 11. 初始化测试数据
 
diff --git a/docs/backend/summary/why.md b/docs/backend/summary/why.md
@@ -20,7 +20,7 @@ import NpmBadge from 'vuepress-theme-plume/features/NpmBadge.vue'
 
 ## 承诺
 
-此仓库作为模板库公开，任何个人或企业均可自由使用！您可以通过 [购买特权](../../price.md) 选择不同版本
+此仓库作为模板库公开，任何个人或企业均可自由使用！您可以通过 [定价页面](../../pricing.md) 选择不同版本
 
 ## 架构
 
diff --git a/docs/group.md b/docs/group.md
diff --git a/docs/sponsors.md b/docs/sponsors.md
diff --git a/package.json b/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
