From 7aac134d5da3b6fcfdc03ad5c2d7cb60b67ff84b Mon Sep 17 00:00:00 2001
From: suyiiyii <suyiiyii@gmail.com>
Date: Mon, 14 Oct 2024 12:32:59 +0800
Subject: [PATCH] =?UTF-8?q?:memo:=20=E6=B5=8B=E8=AF=95mermaid=E7=94=BB?=
 =?UTF-8?q?=E5=9B=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/dev/README.md          |  5 +++
 docs/dev/cookie.md          | 68 +++++++++++++++++++++++++++++++++++++
 docs/usage/cookie.md        |  6 ++--
 nonebot_bison/utils/site.py |  2 +-
 4 files changed, 77 insertions(+), 4 deletions(-)
 create mode 100644 docs/dev/cookie.md

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 361eecd..77c54a5 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -1,3 +1,8 @@
+---
+prev: /usage/install
+next: /dev/cookie
+---
+
 # 基本开发须知
 
 ## 语言以及工具
diff --git a/docs/dev/cookie.md b/docs/dev/cookie.md
new file mode 100644
index 0000000..61dbc5f
--- /dev/null
+++ b/docs/dev/cookie.md
@@ -0,0 +1,68 @@
+# Cookie 开发须知
+
+本项目将大部分 Cookie 相关逻辑提出到了 Site 及 Client Manger 模块中，你只需要继承相关类即可获得使用 Cookie 的能力。
+
+:::tip
+在开发Cookie功能之前，你应该对[基本开发](/dev/#基本开发)有一定的了解。
+:::
+
+## Cookie相关的基本概念
+
+- `nonebot_bison.config.db_model.Cookie`: 用于存储Cookie的实体类，包含了Cookie的名称、内容、状态等信息
+- `nonebot_bison.config.db_model.CookieTarget`: 用于存储Cookie与订阅的关联关系
+- `nonebot_bison.utils.site.CookieClientManager`: 添加了Cookie功能的ClientManager，是Cookie管理功能的核心，调度Cookie的功能就在这里实现
+- `nonebot_bison.utils.site.CookieSite`: 添加了Cookie功能的Site类，根据需求添加了和Site强相关的Cookie功能实现方法
+
+## 快速上手
+
+例如，你现在有一个这样子的 Site 类：
+
+```python
+class WeiboSite(Site):
+  name = "weibo.com"
+  schedule_type = "interval"
+  schedule_setting = {"seconds": 3}
+```
+
+简而言之，要让你的站点获得 Cookie 能力，只需要：
+
+1. 将父类从`Site`改为`CookieSite`
+
+```python {1}
+class WeiboSite(CookieSite):
+    name = "weibo.com"
+    schedule_type = "interval"
+    schedule_setting = {"seconds": 3}
+```
+
+2. 为你的 Site 类添加一个`client_mgr`属性
+
+```python {5}
+class WeiboSite(CookieSite):
+    name = "weibo.com"
+    schedule_type = "interval"
+    schedule_setting = {"seconds": 3}
+    client_mgr = create_cookie_client_manager(name)
+```
+
+至此，你的站点就可以使用 Cookie 了！
+
+## 更好的体验
+
+为了给用户提供更好的体验，你还可以为你的Site重写`validate_cookie`和`get_target_name`方法。
+
+- `async def validate_cookie(cls, content: str) -> bool`该方法将会在Cookie添加时被调用，你可以在这里验证Cookie的有效性
+- `async def get_cookie_name(cls, content: str) -> str`该方法将会在验证Cookie成功后被调用，你可以在这里设置Cookie的名字并展示给用户
+
+## 我要自己调度Cookie
+
+当默认的Cookie调度逻辑无法满足你的需求时，你可以重写`CookieClientManager`的`get_cookie`方法。
+
+目前整体的调度逻辑是：
+
+```mermaid
+graph TD
+    A[获取订阅] --> B[获取订阅的Cookie]
+    B --> C[验证Cookie]
+    C --> D[返回Cookie]
+```
diff --git a/docs/usage/cookie.md b/docs/usage/cookie.md
index b253d64..0ed4766 100644
--- a/docs/usage/cookie.md
+++ b/docs/usage/cookie.md
@@ -46,7 +46,7 @@ Cookie 全局生效，这意味着，通过你的 Cookie 获取到的内容，
 ![add cookie](/images/add-cookie.png)
 
 然后，依次输入平台名称和 Cookie 内容。
-![add cookie 2](/images/add-cookie.png)
+![add cookie 2](/images/add-cookie-2.png)
 
 看到 Bison 的回复之后，Cookie 就添加成功啦！
 
@@ -86,11 +86,11 @@ Cookie 全局生效，这意味着，通过你的 Cookie 获取到的内容，
 
 这是 `添加cookie` 的逆向操作。
 
-## globe_with_meridians: 使用 WebUI 管理 Cookie
+## :globe_with_meridians: 使用 WebUI 管理 Cookie
 
 同样的，Bison 提供了一个网页管理 Cookie 的功能，即 WebUI，你可以在网页上查看、添加、删除 Cookie。
 
-使用方法参见 [使用网页管理订阅](/usage/easy-usage#:globe_with_meridians: \u4f7f\u7528\u7f51\u9875\u7ba1\u7406\u8ba2\u9605)。
+使用方法参见 [使用网页管理订阅](/usage/easy-use#使用网页管理订阅)。
 
 ## :tada: 完成！
 
diff --git a/nonebot_bison/utils/site.py b/nonebot_bison/utils/site.py
index 6977b79..efb53c2 100644
--- a/nonebot_bison/utils/site.py
+++ b/nonebot_bison/utils/site.py
@@ -43,7 +43,7 @@ class DefaultClientManager(ClientManager):
 
 
 class CookieClientManager(ClientManager):
-    _site_name: str
+    _site_name: str  # 绑定的 site_name，需要使用 create_cookie_client_manager 创建 Client_mgr 时绑定
     _default_cd: int = timedelta(seconds=10)
 
     @classmethod