update docs

Author: wu-clan

docs/.vuepress/navbar.ts

@@ -5,7 +5,7 @@ export const myNavbar = defineNavbarConfig([
         text: '演示',
         items: [
             {
-                text: 'Arco Design Pro 版本',
+                text: 'Arco Design 版本',
                 link: 'https://fba.xwboy.top/'
             }
         ]

docs/.vuepress/sidebar.ts

@@ -18,16 +18,15 @@ export const mySidebar: SidebarMulti = {
             collapsed: false,
             prefix: 'reference/',
             items: [
-                {text: '登录', link: 'login'},
-                {text: 'OAuth 2.0', link: 'oauth2'},
+                {text: '授权', link: 'oauth'},
                 {text: '跨域', link: 'cors'},
-                {text: '权限', link: 'permission'},
+                {text: 'RBAC', link: 'RBAC'},
                 {text: '事务', link: 'transaction'},
                 {text: '代码生成', link: 'code-generation'},
             ]
         },
         {
-            text: 'MiXin',
+            text: 'Mixin',
             collapsed: false,
             prefix: 'mixin/',
             items: [

docs/guide/mixin/user.md

@@ -1,5 +1,29 @@
 ---
-title: MiXin
+title: Mixin
 ---
 
-## TODO
+我们默认提供的所有模型都是没有操作人员信息的，在很多项目中，可能会添加每条数据的创建人、更新人，
+虽然我们没有实行这一特性，但是，我们提供了非常简易的集成方式
+
+## 如何应用？
+
+在 `common/model.py` 文件中，我们提供了用户 Mixin 类
+
+```py
+class UserMixin(MappedAsDataclass):
+    """用户 Mixin 数据类"""
+
+    create_user: Mapped[int] = mapped_column(sort_order=998, comment='创建者')
+    update_user: Mapped[int | None] = mapped_column(init=False, default=None, sort_order=998, comment='修改者')
+```
+
+通常情况下，你会在自定义模型类中继承 `Base` 父类，要想灵活的应用操作人员信息，你只需在继承 `Base` 父类的同时，也继承
+`UserMixin` 类，这样就将自动添加操作人员列到模型
+
+## 如何使用？
+
+应用操作人员信息后，首先，你要在接口参数中，传递 `request: Request`，并作为第一个参数（在 Django，flask 等框架中，这可能很常见）
+
+然后，在执行创建或更新操作时，可通过 `request.user.id` 直接获取操作人员 id，并进行数据库写入
+
+我们之所以没有默认应用此功能，是因为我们不想所有接口重复调用 `request` 参数（作者强迫症）

docs/guide/reference/RBAC.md

@@ -0,0 +1,91 @@
+---
+title: 权限
+---
+
+我们通过两个自定义依赖组件，实现了 RBAC 的轻松集成，在 Java 或其他语言中，常见的方式可能是注解，但在 fastapi 中，依赖是它的亮点，也是核心
+
+## RBAC
+
+RBAC 提供了两种解决方案，第一种【角色菜单】可能更加常见，它可以设置按钮级别的控制规则，另外一种是【Casbin】，它非常灵活，可以通过模型定义多种
+控制规则（我认为它很好，性能也很出色）
+
+### 角色菜单
+
+要想实现此 RBAC 调用，涉及到三处相关配置
+
+::: steps
+1. 更新 RBAC 鉴权配置
+
+   在 `core/conf.py` 文件中找到以下配置，并更新 `PERMISSION_MODE` 为 `role-menu`
+
+    ```py
+    # Permission (RBAC)
+    PERMISSION_MODE: Literal['casbin', 'role-menu'] = 'role-menu'
+    ```
+
+2. 添加接口依赖
+
+   只有在接口中参加此依赖时，才能自动应用此鉴权
+
+    ```py{5-6}
+    @router.post(
+        '',
+        summary='xxx',
+        dependencies=[
+            Depends(RequestPermission('sys:api:add')),
+            DependsRBAC,
+        ],
+    )
+    ```
+
+3. 在菜单中添加权限标识
+
+   我们在接口依赖中可以看到 `sys:api:add` 之类的值，这些值正是对应着菜单中的权限标识，只有它们完全一致，并且用户拥有菜单时，才有权执行操作
+:::
+
+### Casbin
+
+Casbin 在 Go web 中应用更加广泛， 我们在最初架构设计时，参考了 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)进行规则验证
+
+模型：
+
+```
+[request_definition]
+r = sub, obj, act
+
+[policy_definition]
+p = sub, obj, act
+
+[role_definition]
+g = _, _
+
+[policy_effect]
+e = some(where (p.eft == allow))
+
+[matchers]
+m = g(r.sub, p.sub) && (keyMatch(r.obj, p.obj) || keyMatch3(r.obj, p.obj)) && (r.act == p.act || p.act == "*")
+```
+
+p 策略：
+
+- 推荐添加基于角色的访问权限, 需配合添加 g 策略才能真正拥有访问权限，适合配置全局接口访问策略<br>
+**格式**: 角色 role + 访问路径 path + 访问方法 method
+
+- 如果添加基于用户的访问权限, 不需配合添加 g 策略就能真正拥有权限，适合配置指定用户接口访问策略<br>
+**格式**: 用户 uuid + 访问路径 path + 访问方法 method
+
+g 策略 (**依赖 p 策略**)：
+
+- 如果在 p 策略中添加了基于角色的访问权限, 则还需要在 g 策略中添加基于用户组的访问权限, 才能真正拥有访问权限<br>
+**格式**: 用户 uuid + 角色 role
+
+- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限<br>
+但是拥有的不是用户角色的所有权限, 而只是单一的对应的 p 策略所添加的访问权限

docs/guide/reference/code-generation.md

@@ -2,4 +2,44 @@
 title: 代码生成
 ---
 
-## TODO
+> [!TIP]
+> 当前版本仅包含后端代码生成
+>
+> 代码生成器使用 api 调用实现，包含两个模组，设计可能存在缺陷，相关问题请直接提交 issues
+
+> [!WARNING]
+> 由于 jinja2 在渲染模版时，文本方式输出可能存在格式问题，所以 `preview` 接口可能无法直观预览代码，这是为前端进行的预设
+
+## 概念
+
+### 业务
+
+包含代码生成的相关配置，详情查看：`generator/model/gen_business.py`
+
+### 模型
+
+包含代码生成所需要的模型列信息，就像正常定义模型列一样，目前支持的功能有限
+
+## 使（食）用
+
+1. 启动后端服务，打开 swagger 文档直接操作
+2. 通过第三方 api 调试工具发送接口请求
+3. 同时启动前后端，从页面进行操作
+
+接口参数基本都有说明，请注意查看
+
+### F. 纯手动模式
+
+不推荐（手动创建业务接口被标记为「已弃用」）
+
+1. 通过创建业务接口手动添加一项业务数据
+2. 通过模型创建接口手动添加模型列
+3. 访问 `preview`（预览），`generate`（磁盘写入），`download`（下载）接口，执行后端代码生成相应工作
+
+### S. 自动模式
+
+推荐
+
+1. 访问 `tables` 接口，获取数据库表名列表
+2. 通过 `import` 接口，导入数据库已有的数据库表数据，将自动创建业务表数据和模型表数据
+3. 访问 `preview`（预览），`generate`（磁盘写入），`download`（下载）接口，执行后端代码生成相应工作

docs/guide/reference/login.md

@@ -0,0 +1,23 @@
+---
+title: 授权
+---
+
+::: note
+通过 JWT 中间件实现全局自动授权
+:::
+
+我们编写了自定义的 JWT 授权中间件，使其可以在每次请求发起时，自动调用此中间件实现自动授权，并且，通过 Redis 和 Rust 库对用户信息进行快速缓存，
+使其性能影响尽可能降到最低
+
+## 验证码登录
+
+我们提供了数字验证码方式的登录授权接口，登录成功后，JWT 将包含在接口响应信息中
+
+
+## Swagger 授权
+
+这是一种快捷的授权方式，但仅出于调试目的，在服务启动后，进入 Swagger UI，可通过此调试接口进行快速登录授权（无需验证码）
+
+## OAuth 2.0
+
+这种授权方式通常适用于第三方平台认证登录，第三方授权成功后，将依据第三方平台信息自动创建本地用户并自动授权登录，这一切都是用户无感知的

docs/guide/reference/oauth.md

@@ -2,4 +2,39 @@
 title: 事务
 ---
 
-## TODO
+我们可以通过两种方式实现数据库事务
+
+## session 生成器
+
+这是官方一种比较流行的方法，通过迭代 session 控制隔离，并通过上下文异常进行回滚，最后关闭 session
+
+这种方式应用于接口函数，通过依赖注入实现 session 传递，在 session 应用方面，它被认为是线程安全的
+
+```py{3}
+@router.get('')
+async def get_pagination_apis(
+  db: CurrentSession
+) -> ResponseModel:
+  ...
+```
+
+## `begin()`
+
+这种方式由 SQLAlchemy 官方实现，相对第一种方式来说，更加原生，在线程安全方面，由于同一个接口中，可能存在多次调用，所以没有第一种方式更加严谨，
+不过呢，对于此架构来说，它更加符合架构风格
+
+```py{2}
+async def create(*, obj: CreateIns) -> None:
+    async with async_db_session.begin() as db:
+        await xxx_dao.create(db, obj)
+```
+
+## 如何选择？
+
+对于两种事务方法，我们更推荐第二种；
+
+通常情况下，第一种方法我们更多用于分页查询接口，理论上来说，查询接口我们无需使用事务，但由于分页查询我们使用了第三方库，并且，为了尊重
+fastapi 官方教程，我们仍将它保留
+
+而第二种，对于无需使用事务的数据库操作，我们只需将 `begin()` 方法去掉，改为 `async with async_db_session() as db:`
+即可，这种方式更加灵活，并且也能减少千篇一律的接口参数（纯作者强迫症），同时，它也是 sqlalchemy 2.0+ 的官方推荐使用方法