update docs

Author: wu-clan

docs/.vuepress/navbar.ts

@@ -28,9 +28,14 @@ export const myNavbar = defineNavbarConfig([
         icon: 'fluent-emoji-high-contrast:unicorn',
         link: 'https://github.com/fastapi-practices/fastapi_best_architecture/issues'
     },
+    {
+        text: '插件市场',
+        icon: 'clarity:plugin-solid',
+        link: '/plugins'
+    },
     {
         text: '授权',
-        icon: 'ri:key-2-fill',
+        icon: 'fluent:person-key-20-filled',
         link: '/guide/summary/why.md#承诺'
     },
     {

docs/guide/reference/RBAC.md

@@ -2,12 +2,15 @@
 title: RBAC
 ---
 
-我们通过两个自定义依赖组件，实现了 RBAC 的轻松集成，在 Java 或其他语言中，常见的方式可能是注解，但在 fastapi 中，依赖是它的亮点，也是核心
+我们通过两个自定义依赖组件，实现了 RBAC 的轻松集成，在 Java 或其他语言中，常见的方式可能是注解，但在 FastAPI 中，依赖是它的亮点，也是核心
 
 ## RBAC
 
-RBAC 提供了两种解决方案，第一种【角色菜单】可能更加常见，它可以设置按钮级别的控制规则，另外一种是【Casbin】，它非常灵活，可以通过模型定义多种
-控制规则（我认为它很好，性能也很出色）
+RBAC 提供了两种解决方案，分别为【角色菜单】、【Casbin】
+
+【角色菜单】是各类语言 web 开发中比较常见的解决方案，它可以设置按钮级别的控制规则
+
+【Casbin】是 Go 语言中比较流行的解决方案，它非常灵活，可以通过模型定义多种控制规则
 
 ### 角色菜单
 
@@ -26,35 +29,37 @@ RBAC 提供了两种解决方案，第一种【角色菜单】可能更加常见
 
 2. 添加接口依赖
 
-   只有在接口中填加此依赖时，才能自动应用此鉴权方式
+   只有在接口中填加以下相关依赖时，才能自动应用此鉴权方式
 
     ```py{5-6}
     @router.post(
         '',
         summary='xxx',
         dependencies=[
-            Depends(RequestPermission('sys:api:add')),
+            Depends(RequestPermission('sys:api:add')),  # 通常为 xxx:xxx:xxx
             DependsRBAC,
         ],
     )
     ```
 
 3. 在菜单中添加权限标识
 
-   我们在接口依赖中可以看到 `sys:api:add` 之类的值，这些值正是对应着菜单中的权限标识，只有它们完全一致，并且用户拥有菜单时，才会获得相应的操作权限
-   :::
+   我们在接口依赖中可以看到 `sys:api:add` 之类的值，这些值正是对应着菜单中的权限标识，
+   只有它们完全一致，并且用户拥有对应的菜单时，才会获得相应的操作权限
+
+:::
 
 ### Casbin
 
-Casbin 在 Go web 中应用更加广泛， 我们在最初架构设计时，参考了 go-admin，gin-vue-admin... 等优秀的开源项目，同时引入了
-Casbin，它在众多 python web 开源项目中可能是极为罕见的，并且，它的学习成本相对较高，如果你对此感兴趣，可以通过
-[Casbin 官网](https://casbin.org/docs/get-started) 进行学习，另外，可参考视频教程 （
+我们在最初架构设计时，参考了 go-admin，gin-vue-admin... 等优秀的开源项目，同时引入了
+Casbin，它在众多 python web 开源项目中可能是极为罕见的，并且，它的学习成本非常高，如果你对此感兴趣，可以通过
+[Casbin 官网](https://casbin.org/docs/get-started) 进行学习，另外，可参考视频教程
 [半小时彻底弄懂Casbin基础模型](https://www.bilibili.com/video/BV1qz4y167XP/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)、
 [Casbin的代码使用、api调用、自定义比较方法](https://www.bilibili.com/video/BV13r4y1M7AC/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)
-）
+，讲的是非常好
 
-通过以上学习之后，我们再来看规则（不学习规则可能是天书），
-你可以通过此[编辑器](https://github.com/casbin/casbin-editor)进行规则验证
+通过以上学习之后，我们再来看内置规则（不学习 == 天书），
+你可以通过[编辑器](https://casbin.org/zh/docs/online-editor)进行模型规则验证
 
 模型：
 
@@ -88,5 +93,27 @@ g 策略 (**依赖 p 策略**)：
 - 如果在 p 策略中添加了基于角色的访问权限, 则还需要在 g 策略中添加基于用户组的访问权限, 才能真正拥有访问权限<br>
   **格式**: 用户 uuid + 角色 role
 
-- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限<br>
-  但是拥有的不是用户角色的所有权限, 而只是单一的对应的 p 策略所添加的访问权限
+- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限，但是拥有的不是用户角色的所有权限,
+  而只是单一的对应的 p 策略所添加的访问权限
+
+## 解耦
+
+在实际项目开发中，不可能同时存在两种 RBAC 解决方案，我们可以通过以下方式删除其中一种集成
+
+### 角色菜单
+
+- 删除 `backend/common/security/permission.py` 文件中的 `RequestPermission` 类及所有类调用
+- 删除 `backend/core/conf.py` 文件中的 `PERMISSION_MODE` 和 `RBAC_ROLE_MENU_EXCLUDE`
+- 删除 `backend/common/security/rbac.py` 文件中 `rbac_verify` 方法里面的 `if settings.PERMISSION_MODE == 'role-menu':`
+  条件及相关代码
+
+### Casbin
+
+- 删除 `backend/app/admin/api/v1/sys/casbin.py`、`backend/app/admin/crud/crud_casbin.py`、
+  `backend/app/admin/model/casbin_rule.py`、`backend/app/admin/schema/casbin_rule.py`、
+  `backend/app/admin/service/casbin_service.py` 文件
+- 删除 `backend/core/conf.py` 文件中的 `RBAC_CASBIN_EXCLUDE`
+- 删除 `backend/common/security/rbac.py` 文件中 `enforcer` 方法
+- 删除 `backend/common/security/rbac.py` 文件中 `rbac_verify` 方法里面的 `if settings.PERMISSION_MODE == 'role-menu':`
+  条件和 else 条件中的相关代码
+- 删除 casbin 相关依赖包

docs/guide/reference/db.md

@@ -2,12 +2,12 @@
 title: 切换数据库
 ---
 
-FBA 支持 MySQL、PostgreSQL 两种数据库，默认配置使用 MySQL
-
 ::: tip
 此教程仅适用于 pg 用户
 :::
 
+FBA 支持 MySQL、PostgreSQL 两种数据库，默认配置使用 MySQL
+
 如果本地未安装 pg，你可以使用以下命令创建 Docker 镜像
 
 ```shell
@@ -28,19 +28,19 @@ DATABASE_USER='postgres'
 DATABASE_PASSWORD='123456'
 ```
 
-## 注意事项
+## 解耦
 
-FBA 在模型中使用 `with_variant` 尽可能兼容 MySQL 和 PostgreSQL，例如：
+在实际项目开发中，几乎不会存在同时兼容多种数据库的情况，我们在模型中使用 `with_variant` 尽可能的兼容 MySQL 和
+PostgreSQL，例如：
 
-```python
+```python:no-line-numbers
 # [!code word:with_variant]
 remark: Mapped[str | None] = mapped_column(LONGTEXT().with_variant(TEXT, 'postgresql'))
 ```
 
-兼容性代码涉及的其他地方：
-
-- 代码生成
-- 创建数据库链接
-- docker-compose.yml
-
-如果你只使用其中一种数据库，可直接修改为数据库对应类型
+- 删除 `with_variant` 相关代码并且仅保留数据库对应的类型
+- 删除 `backend/core/conf.py` 文件中的 `DATABASE_TYPE` 及其相关的调用代码
+- 删除 `.env_example` 和 `.env` 文件中的 `DATABASE_TYPE`
+- 更新 `backend/templates/py/model.jinja` 文件中的 `database_type` 相关代码
+- 删除 `backend/sql` 目录中的 `mysql` 或 `postgresql` 文件夹
+- 删除 `docker-compose.yml` 文件中的 `fba_mysql` 或 `fba_postgres` 容器脚本

docs/guide/summary/fsm.md

@@ -2,10 +2,12 @@
 title: 精简版本
 ---
 
-我们有一些简化版本的 fastapi 三层架构脚手架，但是它们的更新可能并不同步，这意味着，你可能无法及时在便捷版中获得新功能支持和问题修复
+::: warning
+FastAPI 三层架构脚手架精简版的更新可能并不同步，你可能无法及时的在这些版本中获得新功能支持和问题修复
+:::
 
 > [!IMPORTANT]
-> 我们积极寻找这些版本仓库的维护人员，如果你对此感兴趣，请直接在对应仓库创建 ISSUES 或通过 Discord 与我们联系
+> 我们在积极寻找这些版本的维护人员，如果你对此感兴趣，请直接在对应仓库创建 ISSUES 或通过 Discord 与我们联系
 
 ## SQLAlchemy
 

docs/guide/summary/quick-start.md

@@ -2,8 +2,15 @@
 title: 快速开始
 ---
 
+::: caution
+==FBA 仅适用于资深 Python 后端开发人员==，如果您是非资深用户，请使用 [精简版](../summary/fsm.md)
+:::
+
 > [!IMPORTANT]
-> 请一字不落的认真对待此文档，并严格按照本文档的顺序启动项目，否则你有很大几率在启动过程中遇到各种问题
+> 我们建议新手用户从一些基础和简单的内容入手，这不仅是对自身学习的一种负责态度，也是为将来能够顺利掌握这一架构所奠定的坚实基础，欢迎加入我们的
+> Discord 社区进行讨论
+>
+> 最后，请认真对待此文档，并严格按照本文档的顺序启动项目，否则你有很大几率在启动过程中遇到各种问题
 
 ## 本地开发
 
@@ -68,17 +75,16 @@ title: 快速开始
    ```
 
 7. 按需修改配置文件 `core/conf.py` 和 `.env`
-
-   ::: info   
-   默认情况下，首次启动不需要修改
-   :::
-
 8. 创建数据库表（三选一）
 
     - 直接启动后端项目（自动创建）
     - 数据库迁移 [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html)
 
-      ::: details
+      :::: details
+      ::: warning
+      此方法暂不适用于 PostgreSQL 用户，详情请查看：[#1584](https://github.com/sqlalchemy/alembic/discussions/1584)
+      :::
+
       生成迁移文件
 
       ```shell
@@ -90,10 +96,10 @@ title: 快速开始
       ```shell
       alembic upgrade head
       ```
-      :::
+      ::::
     - 执行 `backend/sql/` 目录下对应数据库的 `create_tables.sql` 脚本
 
-9. ==（可选）== 启动 celery worker, beat 和 flower
+9. 启动 celery worker, beat 和 flower ==（可选）==
 
    Celery 应用程序
 

docs/guide/summary/why.md

@@ -6,16 +6,10 @@ title: 为什么选择我们？
 import NpmBadge from 'vuepress-theme-plume/features/NpmBadge.vue'
 </script>
 
-::: caution
-==FBA 仅适用于资深 Python 后端开发人员==，如果您是非资深用户，请查看 [精简版](#精简版)
-
-我们建议新手用户从一些基础和简单的内容入手，这不仅是对自身学习的负责态度，也为将来能够顺利掌握这一架构奠定坚实的基础
-:::
-
 ::: note
 我们不会去和其他架构做比较，我们认为每个架构都有自己的特点，适合不同的场景
 
-我们的目标是提供一个最佳架构，让开发者可以快速上手，专注于业务逻辑的开发，所以我们只会不断完善和优化我们的架构，为开发者带来更好的体验
+我们的目标是提供一个最佳架构，让开发者可以快速上手，能够专注于业务逻辑的开发，所以我们只会不断完善和优化我们的架构，为开发者带来更好的体验
 :::
 
 ## 承诺

docs/plugins.md

@@ -0,0 +1,5 @@
+---
+title: 插件市场
+---
+
+我们正在积极调研此功能，它将提供类似于 gin-vue-admin 中插件功能