完善开发文档与合并 admin_log 文件

docs/source/function/admin.rst

@@ -0,0 +1,49 @@
+:mod:`admin` -- 后台函数模块
+=======================================
+
+:mod:`admin` 模块源代码在文件夹 `applications/common/admin.py` 下，主要集结了一些常用的后台需要频繁调用的函数。
+
+.. module:: admin
+
+函数
+-------------
+
+.. function:: get_captcha()
+
+   生成验证码图片及其对应的验证码字符串。
+
+   :return: 返回验证码图片的响应对象和验证码字符串。
+
+
+.. function:: normal_log(method, url, ip, user_agent, desc, uid, is_access)
+
+   记录通用日志信息到数据库。
+
+   :param method: 请求方法（如 GET、POST）。
+   :param url: 请求的 URL。
+   :param ip: 客户端的 IP 地址。
+   :param user_agent: 客户端的 User-Agent 信息。
+   :param desc: 日志描述信息。
+   :param uid: 用户 ID。
+   :param is_access: 是否成功访问（True 或 False）。
+   :return: 返回日志记录的 ID。
+
+
+.. function:: login_log(request, uid, is_access)
+
+   记录用户登录日志。
+
+   :param request: Flask 请求对象。
+   :param uid: 用户 ID。
+   :param is_access: 是否成功登录（True 或 False）。
+   :return: 返回日志记录的 ID。
+
+
+.. function:: admin_log(request, is_access, desc=None)
+
+   记录管理员操作日志。
+
+   :param request: Flask 请求对象。
+   :param is_access: 是否成功操作（True 或 False）。
+   :param desc: 日志描述信息（可选）。如果未提供，则从请求数据中提取。
+   :return: 返回日志记录的 ID。

docs/source/function/index.rst

@@ -2,6 +2,17 @@
 
 目录索引
 
+公共函数
+------------
+
+.. toctree::
+    :maxdepth: 1
+
+    admin
+
+辅助函数
+------------
+
 .. toctree::
     :maxdepth: 1
 

docs/source/function/utils/index.rst

@@ -1,5 +1,3 @@
-.. module:: applications.common.utils
-
 .. title:: 辅助函数
 
 目录索引

docs/source/function/utils/validate.rst

@@ -1,7 +1,7 @@
 :mod:`validate` -- 效验模块
 ==================================
 
-:mod:`validate` 模块源代码在文件夹 `applications/common/utils/rights.py` 下，主要用于数据效验与过滤。
+:mod:`validate` 模块源代码在文件夹 `applications/common/utils/validate.py` 下，主要用于数据效验与过滤。
 
 .. module:: validate
 

docs/source/welcome/migration.rst

@@ -94,5 +94,20 @@
     你会注意到修改之后的 layui-btn-primary 属性添加在了 “重置” 按钮上，而不是 “查询” 按钮上，
     这是因为 layui-btn-primary 是默认白色的，而不加 layui-btn-primary 属性是跟随主题色的。这里需要特别注意一下。
 
+合并日志模块
+~~~~~~~~~~~~~~~~~~~~
+
+为了减少冗余，将 applications/common/admin_log.py 与 applications/common/admin.py 合并，仅留下 applications/common/admin.py 。
 
 
+例如：
+
+.. code-block:: python
+
+    from applications.common.admin_log import admin_log
+
+改为：
+
+.. code-block:: python
+
+    from applications.common.admin import admin_log

docs/source/welcome/update.rst

@@ -38,6 +38,8 @@
 * 增加后台消息接口
 * 系统监控中对硬盘的获取，如果是在 docker 中就获取根目录的数据
 * 更正登录之后重定向由于路由更改从而设置错误的问题
+* 将 applications/common/admin_log.py 与 applications/common/admin.py 合并，仅留下 applications/common/admin.py
+* 优化代码结构，新增函数 `normal_log` 减少代码复用
 
 已知问题以及解决方式
 ~~~~~~~~~~~~~~~~~~~~~~~