update docs

wu-clan · wu-clan · commit d84bfd7f1621 · 2026-01-21T16:20:32.000+08:00
diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts
@@ -125,7 +125,7 @@ export const myNavbar: ThemeNavItem[] = defineNavbarConfig([
                 items: [
                     {
                         text: '视频课程',
-                        badge: { text: '重制中', type: 'warning' },
+                        badge: { text: '已过时', type: 'danger' },
                         icon: 'ri:bilibili-fill',
                         link: 'https://space.bilibili.com/284237214/lists'
                     },
diff --git a/docs/.vuepress/public/images/cli.png b/docs/.vuepress/public/images/cli.png
diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts
@@ -69,6 +69,7 @@ export const mySidebar: ThemeSidebarMulti = {
             collapsed: false,
             items: [
                 { text: '前言', link: 'before' },
+                { text: '视频讲解', link: 'video' },
             ]
         },
         {
diff --git a/docs/.vuepress/theme.ts b/docs/.vuepress/theme.ts
@@ -57,6 +57,7 @@ export const myTheme: Theme = plumeTheme({
         annotation: true,
         chat: true,
         mermaid: true,
+        bilibili: true,
     },
     codeHighlighter: {
         themes: {
diff --git a/docs/backend/deploy/Docker.md b/docs/backend/deploy/Docker.md
@@ -75,7 +75,7 @@ title: Docker 部署
 
 ### 前端
 
-[请移步至 **前端快速开始**](../../frontend/summary/quick-start.md){.read-more}
+[**快速开始**](../../frontend/summary/quick-start.md){.read-more}
 
 ## 服务器部署
 
@@ -146,7 +146,7 @@ fba 正在使用免费 SSL 证书：[httpsok-SSL](https://httpsok.com/p/4Qjd)，
 
 ### 前端
 
-[请移步至 **前端快速开始**](../../frontend/deploy/docker.md){.read-more}
+[**快速开始**](../../frontend/deploy/docker.md){.read-more}
 
 ## 注意事项
 
diff --git a/docs/backend/deploy/legacy.md b/docs/backend/deploy/legacy.md
@@ -8,7 +8,4 @@ title: 传统部署
 您可以选择我们的 [专业版](../../pricing.md)，以获取作者一对一部署指导
 :::
 
-::: info
-fba 正在使用免费 SSL 证书：[httpsok-SSL](https://httpsok.com/p/4Qjd)，证书自动续期，一行命令，轻松搞定 SSL
-证书自动续签，支持：nginx、通配符证书、七牛云、腾讯云、阿里云、CDN、OSS、LB（负载均衡）
-:::
+@[bilibili](BV1q1KVe3E82)
diff --git a/docs/backend/ide/vscode.md b/docs/backend/ide/vscode.md
@@ -2,7 +2,7 @@
 title: vscode
 ---
 
-[**Visual Studio Code** 官网地址](https://code.visualstudio.com/){.read-more}
+[**Visual Studio Code** 官网](https://code.visualstudio.com/){.read-more}
 
 ## DEBUG
 
diff --git a/docs/backend/reference/apscheduler.md b/docs/backend/reference/apscheduler.md
@@ -3,7 +3,7 @@ title: APScheduler
 ---
 
 我们在最初的框架实现中，使用的是 APScheduler，但后来我们迁移到了
-Celery，详情请查看：[#225](https://github.com/fastapi-practices/fastapi_best_architecture/discussions/225)
+Celery，详情：[#225](https://github.com/fastapi-practices/fastapi_best_architecture/discussions/225)
 
 FastAPI + APScheduler 现已作为独立仓库发行，它的优势在于易用性、灵活性和实时动态任务，如果你没有繁重的任务需求，它将是一个不错的选择
 
diff --git a/docs/backend/reference/celery.md b/docs/backend/reference/celery.md
@@ -79,7 +79,9 @@ Backend，但是，如果你需要查看任务的结果，我们则推荐你这
 进入源码 `backend/app` 目录，其中，task 目录就是我们的 Celery 应用程序，如果你不想使用它，而是使用其他任务应用，可以直接删除此文件夹
 
 进入 task 目录后，其中 `celery.py` 是 Celery 的初始化文件，包含了启动 Celery
-启动的参数配置，此文件无需进行任何修改，下面，我们将通过视频进行详细介绍：[Celery 集成](https://www.bilibili.com/video/BV1KjkmYdE7q/?share_source=copy_web\&vd_source=ccb2aae47e179a51460c20d165021cb7)
+启动的参数配置，此文件无需进行任何修改，下面，我们将通过视频进行详细介绍：
+
+@[bilibili](BV1KjkmYdE7q)
 
 ## 执行池
 
diff --git a/docs/backend/reference/code-generation.md b/docs/backend/reference/code-generation.md
@@ -12,39 +12,39 @@ API 调用无法直观的预览代码生成结果，它必须配合前端项目
 
 ## 概念
 
-代码生成包含【业务】和【模型】两个模块
+代码生成器使用 api 调用实现，包含【业务】和【模型】两个模块
 
 ### 业务
 
-包含代码生成的相关配置，详情请查看：`backend/app/generator/model/gen_business.py`
+包含代码生成的相关配置，详情请查看：`backend/plugin/code_generator/model/gen_business.py`
 
 ### 模型
 
 包含代码生成所需要的模型列信息，就像正常定义模型列一样，目前支持的功能有限
 
-## 工作模式
+## 使（食）用
 
-目前包含两种工作模式，分别为手动和自动
+1. 启动后端服务，打开 swagger 文档直接操作
+2. 通过第三方 api 调试工具发送接口请求
+3. 同时启动前后端，从页面进行操作
 
-### 手动
+接口参数基本都有说明，请注意查看
 
-::: tip
-此方法适用于直接通过前端定义数据库表和列
-:::
+### F. 纯手动模式
+
+不推荐（手动创建业务接口被标记为「已弃用」）
 
 1. 通过创建业务接口手动添加一项业务数据
 2. 通过模型创建接口手动添加模型列
-3. 访问 `preview`（预览）、`generate`（磁盘写入）、`download`（下载）接口
+3. 访问预览、磁盘写入、下载接口，执行代码生成相应工作
 
-### 自动
+### S. 自动模式
 
-::: tip
-此方法适用于已在数据库中定义好数据库表和列
-:::
+推荐
 
-1. 访问 `tables` 接口，自动获取数据库表名列表
-2. 访问 `import` 接口，导入数据库已有的数据库表，自动创建业务数据和模型列数据
-3. 访问 `preview`（预览）、`generate`（磁盘写入）、`download`（下载）接口
+1. 访问 `tables` 接口，获取数据库表名列表
+2. 通过 `imports` 接口，导入数据库已有的数据库表数据（将自动创建业务表数据和模型表数据）
+3. 访问预览、磁盘写入、下载接口，执行代码生成相应工作
 
 ## 效果预览
 
diff --git a/docs/backend/reference/data-permission.md b/docs/backend/reference/data-permission.md
@@ -25,4 +25,6 @@ SQL 语句拼接进行实现的，而这些固定权限，直接写死了数据
 有没有一种更加灵活的方案呢，答案是，当然有，目前，我们在 fba 中实现的正是超灵活方案，但相比于常见方案来讲，配置会更加复杂
 
 你可以直接查看代码源文件 `backend/common/security/permission.py`
-，它与常规方案使用近乎相同的方式实现数据过滤，但由于其复杂性，下面，我们将通过视频进行讲解： [数据权限管理](https://www.bilibili.com/video/BV13hioY1EQU/?share_source=copy_web\&vd_source=ccb2aae47e179a51460c20d165021cb7)
+，它与常规方案使用近乎相同的方式实现数据过滤，但由于其复杂性，下面，我们将通过视频进行讲解：
+
+@[bilibili](BV13hioY1EQU)
diff --git a/docs/backend/reference/i18n.md b/docs/backend/reference/i18n.md
@@ -38,7 +38,7 @@ flowchart TD
 
 ## 语言包
 
-语言包位于 `backend/app/locale/langs` 目录下
+语言包位于 `backend/app/locale` 目录下
 
 ### 命名
 
diff --git a/docs/backend/reference/model.md b/docs/backend/reference/model.md
@@ -30,7 +30,7 @@ id_key = Annotated[
 
 ### 雪花 ID
 
-[请移步至 **切换主键**](pk.md){.read-more}
+[**切换主键**](pk.md){.read-more}
 
 ## Mixin 类
 
@@ -43,7 +43,7 @@ id_key = Annotated[
 ::: warning
 在 fba 中，并没有默认集成操作人员信息到各个数据库表，但是我们提供了非常简易的集成方式
 
-[请移步至 **操作人**](operator.md){.read-more}
+[**操作人**博客](../../blog/operator.md){.read-more}
 :::
 
 ### 日期时间
diff --git a/docs/backend/reference/response.md b/docs/backend/reference/response.md
@@ -174,4 +174,4 @@ pydantic，详情：[pydantic.alias_generators](https://docs.pydantic.dev/latest
 
 ## 国际化
 
-[请移步至 **国际化**](./i18n.md){.read-more}
+[**国际化**](./i18n.md){.read-more}
diff --git a/docs/backend/reference/schema.md b/docs/backend/reference/schema.md
@@ -2,7 +2,7 @@
 title: schema
 ---
 
-在 fba 中，我们为 Schema 进行了大量量身定制，详情请查看源代码：`backend\common\schema.py`
+在 fba 中，我们为 Schema 进行了大量量身定制，详情请查看：`backend\common\schema.py`
 
 ## 类命名
 
@@ -25,4 +25,4 @@ title: schema
 
 ## 驼峰返回
 
-[请移步至 **接口响应**](response.md#驼峰返回){.read-more}
+[**接口响应**](response.md#驼峰返回){.read-more}
diff --git a/docs/backend/reference/socketio.md b/docs/backend/reference/socketio.md
@@ -1,5 +1,5 @@
 ---
-title: socketio
+title: Socketio
 ---
 
 ## 为什么不用 ws
diff --git a/docs/backend/reference/timezone.md b/docs/backend/reference/timezone.md
@@ -48,5 +48,27 @@ sqlalchemy 和所有 python mysql 驱动默认都不处理 mysql 时区信息，
 更具体的：[sqlalchemy/1985](https://github.com/sqlalchemy/sqlalchemy/issues/1985)
 :::
 
-为此，我们使用了第 2 种解决方案，并创建了自定义 TimeZone 类型，位于 `backend/common/model.py` 文件中，我们可以通过 IDE
-点击类名快捷查看使用方式
+为此，我们使用了第 2 种解决方案，并创建了自定义 TimeZone 类型
+
+```python
+class TimeZone(TypeDecorator[datetime]):
+    """PostgreSQL、MySQL 兼容性时区感知类型"""
+
+    impl = DateTime(timezone=True)
+    cache_ok = True
+
+    @property
+    def python_type(self) -> type[datetime]:
+        return datetime
+
+    def process_bind_param(self, value: datetime | None, dialect) -> datetime | None:  # noqa: ANN001
+        if value is not None and value.utcoffset() != timezone.now().utcoffset():
+            # TODO 处理夏令时偏移
+            value = timezone.from_datetime(value)
+        return value
+
+    def process_result_value(self, value: datetime | None, dialect) -> datetime | None:  # noqa: ANN001
+        if value is not None and value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.tz_info)
+        return value
+```
diff --git a/docs/backend/summary/intro.md b/docs/backend/summary/intro.md
@@ -26,9 +26,8 @@ mvc 架构作为常规设计模式，在 python web 中很常见，但是三层
 
 ## 特性
 
-- [x] 全局 PEP 593 Annotated 参数注入
 - [x] 全异步设计（async/await + asgiref）
-- [x] 遵循 RESTful API 规范
+- [x] 遵循 RESTful API 设计规范
 - [x] SQLAlchemy 2.0 现代语法
 - [x] Pydantic v2 全栈数据验证
 - [x] 角色菜单 RBAC 权限控制
diff --git a/docs/backend/summary/quick-start.md b/docs/backend/summary/quick-start.md
@@ -15,8 +15,8 @@ fba 仅适用于资深 Python 后端开发人员，如果您是小白用户，
     - Python 3.10+
     - [安装 uv](https://docs.astral.sh/uv/getting-started/installation/)（推荐最新稳定版）
     - PostgreSQL 16.0 + 或 MySQL 8.0+
-      [雪花主键 ID 用户，请先移步到 **切换主键**](../reference/pk.md){.read-more}
-      [MySQL 用户，请先移步到 **切换数据库**](../reference/db.md){.read-more}
+      [使用**雪花主键 ID**](../reference/pk.md){.read-more}
+      [使用 **MySQL**](../reference/db.md){.read-more}
     - <p>Redis（推荐最新稳定版）</p>
 
 2. 准备源码 <Badge type="warning" text="二选一" />
diff --git a/docs/backend/summary/why.md b/docs/backend/summary/why.md
@@ -12,7 +12,7 @@ import NpmBadge from 'vuepress-theme-plume/features/NpmBadge.vue'
 > [!IMPORTANT]
 > 我们不会去对比任何其他架构，我们认为每个架构都有自己的特点，适用于不同的场景。
 >
-> 但 fba 绝对是开源架构中，==代码最整洁，最规范且最令人赏心悦目的项目之一=={.important}
+> 但 ==fba 绝对是开源架构中，代码最整洁，最规范且最令人赏心悦目的项目之一=={.tip}
 
 ## 目标
 
diff --git a/docs/blog/claude-ai-ecosystem.md b/docs/blog/claude-ai-ecosystem.md
@@ -1,6 +1,7 @@
 ---
 title: Claude 智能体生态系统指南
 createTime: 2026-1-14 13:30
+sticky: true
 tags:
   - AI
 ---
diff --git a/docs/blog/custom-exception.md b/docs/blog/custom-exception.md
@@ -1,5 +1,5 @@
 ---
-title: 如何自定义异常？
+title: FastAPI 如何自定义异常
 createTime: 2025-01-26 16:43
 tags:
   - FastAPI
@@ -34,7 +34,7 @@ def _get_exception_code(status_code: int) -> int:
         return StandardResponseCode.HTTP_400
 ```
 
-异常拦截器还包含：fastapi 数据校验异常，pydantic 数据校验异常，python assert 断言异常，全局未知（未定义）异常，跨域异常，自定义异常，详情请查看源代码：
+异常拦截器还包含：fastapi 数据校验异常，pydantic 数据校验异常，python assert 断言异常，全局未知（未定义）异常，跨域异常，自定义异常，详情请查看：
 `backend/common/exception/exception_handler.py`
 
 ## 后台任务
diff --git a/docs/blog/header-token.md b/docs/blog/header-token.md
@@ -1,7 +1,6 @@
 ---
-title: 如何使用自定义 header token 实现授权？
+title: FastAPI 如何使用自定义 header token 实现授权
 createTime: 2025-03-09 18:00
-sticky: true
 tags:
   - FastAPI
 ---
diff --git a/docs/blog/jwt-middleware.md b/docs/blog/jwt-middleware.md
@@ -1,5 +1,5 @@
 ---
-title: 为什么要用 JWT 认证中间件？
+title: FastAPI 为什么使用 JWT 认证中间件
 createTime: 2025-06-15 17:42
 tags:
   - FastAPI
diff --git a/docs/blog/middleware.md b/docs/blog/middleware.md
@@ -1,5 +1,5 @@
 ---
-title: 如何编写自定义中间件?
+title: FastAPI 如何编写自定义中间件
 createTime: 2024-10-31 18:30
 tags:
   - FastAPI
@@ -68,7 +68,7 @@ async def add_process_time_header(request: Request, call_next):
 
 ## 如何使用
 
-进入 fba 项目 backend 目录下，找到 `core/registrar.py`，在此文件中找到 `register_middleware()` 函数，这是 fba 的中间件注册函数
+进入 fba 项目，找到 `backend/core/registrar.py`，在此文件中找到 `register_middleware()` 函数，这是 fba 的中间件注册函数
 
 在此函数中，==中间件按照从上往下的顺序依次执行==，因此，中间件的顺序非常重要
 
diff --git a/docs/blog/operator.md b/docs/blog/operator.md
@@ -1,13 +1,16 @@
 ---
-title: 操作人
+title: FastAPI 如何添加操作人信息
+createTime: 2024-12-13 12:15
+tags:
+  - FastAPI
 ---
 
 我们常见的后台管理系统中，经常会有一些比如创建人，更新人这类的信息，那这些信息是如何做的呢？下面我们就来讲一讲我们在 fba
 中应该如何集成操作人信息
 
 ## 如何集成？
 
-打开 fba 项目 backend 目录，进入 `common/model.py` 文件中，你会看到 `UserMixin` 类就冰冷冷的站在那里，因为 fba
+打开 fba 项目，进入 `backend/common/model.py` 文件中，你会看到 `UserMixin` 类就冰冷冷的站在那里，因为 fba
 没有使用它，而只是保留它；
 
 ```python
diff --git a/docs/blog/typing-cast.md b/docs/blog/typing-cast.md
@@ -1,9 +1,8 @@
 ---
-title: Typing Cast：静态类型安全的“逃生舱”?
+title: Typing Cast：静态类型安全的“逃生舱”
 createTime: 2025-9-11 12:30
 tags:
   - Python
-  - Typing
 ---
 
 在 Python 3.5 引入类型提示以来，渐进式类型系统让我们的代码更易维护、更易协作。但类型检查器有时太“聪明”了，会因为动态数据或第三方库而迷失方向。
diff --git a/docs/group.md b/docs/group.md
@@ -10,22 +10,28 @@ sponsor_sidebar: true
 Discord 社区是我们的开发技术交流平台，这是一个充满活力的开源社区群组，欢迎来自全球的开发者、爱好者和用户。在这里，
 大家可以自由分享想法、讨论技术、协作项目，或是获取最新的更新与支持。加入我们，一起参与这场开源之旅吧！
 
-:::center
-[点击加入](https://discord.com/invite/yNN3wTbVAC)
-:::
-
 <div align="center">
   <iframe src="https://discord.com/widget?id=1185035164577972344&theme=light" width="350" height="500" allowtransparency="true" frameborder="0" sandbox="allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts"></iframe>
 </div>
 
-## 微信群
+:::center
+<button style="
+padding: 6px 12px;
+background-color: #5865F2;
+border: none;
+border-radius: 8px;">
+<a href="https://discord.com/invite/yNN3wTbVAC" style="color: white; text-decoration: none;">
+点击加入
+</a>
+</button>
+:::
 
-如果您的网络环境受限，可选择此群组 （二维码不定期更新，如遇过期，请通过 Discord 与我们联系）
+## 微信群
 
-此群组由于功能和管理受限，不会发布公告，动态等相关信息
+二维码不定期更新，如遇过期，请通过 Discord 与我们联系
 
 ::: tip
-对于需要提供大量源码或截图的问题，建议 Discord 进行提问，因为 Discord 对代码输入格式化更加友好
+对于需要提供大量源码或截图的问题，建议通过 Discord 进行提问
 :::
 
 <div align="center">
diff --git a/docs/plugin/video.md b/docs/plugin/video.md
@@ -0,0 +1,7 @@
+---
+title: 视频讲解
+---
+
+我们将通过此视频分别介绍 [插件开发](./dev.md)、[插件分享](./share.md)、[插件安装](install.md)
+
+@[bilibili](BV1qaoLYxEXi)

Original file line number	Diff line number	Diff line change
`@@ -125,7 +125,7 @@ export const myNavbar: ThemeNavItem[] = defineNavbarConfig([`
`125`	`125`	`items: [`
`126`	`126`	`{`
`127`	`127`	`text: '视频课程',`
`128`		`- badge: { text: '重制中', type: 'warning' },`
	`128`	`+ badge: { text: '已过时', type: 'danger' },`
`129`	`129`	`icon: 'ri:bilibili-fill',`
`130`	`130`	`link: 'https://space.bilibili.com/284237214/lists'`
`131`	`131`	`},`
Original file line number	Diff line number	Diff line change
`@@ -69,6 +69,7 @@ export const mySidebar: ThemeSidebarMulti = {`
`69`	`69`	`collapsed: false,`
`70`	`70`	`items: [`
`71`	`71`	`{ text: '前言', link: 'before' },`
	`72`	`+ { text: '视频讲解', link: 'video' },`
`72`	`73`	`]`
`73`	`74`	`},`
`74`	`75`	`{`