更新文档

applications/common/curd.py

@@ -1,31 +1,39 @@
 import datetime
-
 from marshmallow import Schema
 from marshmallow_sqlalchemy import SQLAlchemyAutoSchema
-
 from applications.extensions import db, ma
 
 
 class LogicalDeleteMixin(object):
     """
-    class Test(db.Model,LogicalDeleteMixin):
-    __tablename__ = 'admin_test'
-    id = db.Column(db.Integer, primary_key=True, comment='角色ID')
+    逻辑删除混入类，为模型提供软删除功能。
 
-    Test.query.filter_by(id=1).soft_delete()
-    Test.query.logic_all()
+    示例：
+        class Test(db.Model, LogicalDeleteMixin):
+            __tablename__ = 'admin_test'
+            id = db.Column(db.Integer, primary_key=True, comment='角色ID')
+
+        # 软删除
+        Test.query.filter_by(id=1).soft_delete()
+
+        # 查询所有未删除的记录
+        Test.query.logic_all()
     """
     create_at = db.Column(db.DateTime, default=datetime.datetime.now, comment='创建时间')
-    update_at = db.Column(db.DateTime, default=datetime.datetime.now, onupdate=datetime.datetime.now, comment='创建时间')
+    update_at = db.Column(db.DateTime, default=datetime.datetime.now, onupdate=datetime.datetime.now, comment='更新时间')
     delete_at = db.Column(db.DateTime, comment='删除时间')
 
 
 def auto_model_jsonify(data, model: db.Model):
     """
-    不需要建立schemas，直接使用orm的定义模型进行序列化
-    基本功能，待完善
-    示例
-    power_data = curd.auto_model_jsonify(model=Dept, data=dept)
+    自动序列化模型数据为 JSON 格式，无需手动定义 Schema。
+
+    示例：
+        power_data = curd.auto_model_jsonify(model=Dept, data=dept)
+
+    :param data: 需要序列化的 SQLAlchemy 查询结果。
+    :param model: SQLAlchemy 模型类。
+    :return: 返回序列化后的 JSON 数据。
     """
     def get_model():
         return model
@@ -33,49 +41,60 @@ def auto_model_jsonify(data, model: db.Model):
     class AutoSchema(SQLAlchemyAutoSchema):
         class Meta(Schema):
             model = get_model()
-            include_fk = True
-            include_relationships = True
-            load_instance = True
+            include_fk = True  # 包含外键
+            include_relationships = True  # 包含关联关系
+            load_instance = True  # 反序列化时加载为模型实例
 
-    common_schema = AutoSchema(many=True)  # 用已继承ma.ModelSchema类的自定制类生成序列化类
+    common_schema = AutoSchema(many=True)  # 支持序列化多个对象
     output = common_schema.dump(data)
     return output
 
 
 def model_to_dicts(schema: ma.Schema, data):
     """
-    :param schema: schema类
-    :param model: sqlalchemy查询结果
-    :return: 返回单个查询结果
+    使用指定的 Schema 序列化 SQLAlchemy 查询结果。
+
+    :param schema: Marshmallow Schema 类。
+    :param data: SQLAlchemy 查询结果。
+    :return: 返回序列化后的数据，返回字典。
     """
-    # 如果是分页器返回，需要传入model.items
-    common_schema = schema(many=True)  # 用已继承ma.ModelSchema类的自定制类生成序列化类
-    output = common_schema.dump(data)  # 生成可序列化对象
+    common_schema = schema(many=True)  # 支持序列化多个对象
+    output = common_schema.dump(data)
     return output
 
 
 def get_one_by_id(model: db.Model, id):
     """
-    :param model: 模型类
-    :param id: id
-    :return: 返回单个查询结果
+    根据 ID 查询单个记录。
+
+    :param model: SQLAlchemy 模型类。
+    :param id: 记录的主键 ID。
+    :return: 返回查询到的记录，如果未找到则返回 None。
     """
     return model.query.filter_by(id=id).first()
 
 
 def delete_one_by_id(model: db.Model, id):
     """
-    :param model: 模型类
-    :param id: id
-    :return: 返回单个查询结果
+    根据 ID 删除单个记录。
+
+    :param model: SQLAlchemy 模型类。
+    :param id: 记录的主键 ID。
+    :return: 返回删除操作影响的行数。
     """
     r = model.query.filter_by(id=id).delete()
     db.session.commit()
     return r
 
 
-# 启动状态
 def enable_status(model: db.Model, id):
+    """
+    启用指定 ID 的记录。
+
+    :param model: SQLAlchemy 模型类。
+    :param id: 记录的主键 ID。
+    :return: 如果操作成功返回 True，否则返回 False。
+    """
     enable = 1
     role = model.query.filter_by(id=id).update({"enable": enable})
     if role:
@@ -84,11 +103,17 @@ def enable_status(model: db.Model, id):
     return False
 
 
-# 停用状态
 def disable_status(model: db.Model, id):
+    """
+    停用指定 ID 的记录。
+
+    :param model: SQLAlchemy 模型类。
+    :param id: 记录的主键 ID。
+    :return: 如果操作成功返回 True，否则返回 False。
+    """
     enable = 0
     role = model.query.filter_by(id=id).update({"enable": enable})
     if role:
         db.session.commit()
         return True
-    return False
+    return False

applications/common/helper.py

@@ -1,112 +1,131 @@
 from sqlalchemy import and_
-
 from applications.extensions import db
 
 
 class ModelFilter:
     """
-    orm多参数构造器
-    """
-    filter_field = {}
-    filter_list = []
+    ORM 多条件查询构造器，支持多种查询条件组合。
 
-    type_exact = "exact"
-    type_neq = "neq"
-    type_greater = "greater"
-    type_less = "less"
-    type_vague = "vague"
-    type_contains = "contains"
-    type_between = "between"
+    示例：
+        mf = ModelFilter()
+        mf.exact('name', 'John')
+        mf.vague('email', 'example.com')
+        query = User.query.filter(mf.get_filter(User))
+    """
+    filter_field = {}  # 存储字段过滤条件
+    filter_list = []   # 存储最终的过滤条件列表
+
+    # 查询类型常量
+    type_exact = "exact"      # 精确匹配
+    type_neq = "neq"          # 不等于
+    type_greater = "greater"  # 大于
+    type_less = "less"        # 小于
+    type_vague = "vague"      # 模糊匹配
+    type_contains = "contains"  # 包含
+    type_between = "between"  # 范围查询
 
     def __init__(self):
+        """初始化过滤条件存储字典和列表。"""
         self.filter_field = {}
         self.filter_list = []
 
     def exact(self, field_name, value):
         """
-        准确查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加精确匹配条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 匹配的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": value, "type": self.type_exact}
 
     def neq(self, field_name, value):
         """
-        不等于查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加不等于条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 不匹配的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": value, "type": self.type_neq}
 
     def greater(self, field_name, value):
         """
-        大于查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加大于条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 大于的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": value, "type": self.type_greater}
 
     def less(self, field_name, value):
         """
-        小于查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加小于条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 小于的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": value, "type": self.type_less}
 
     def vague(self, field_name, value: str):
         """
-        模糊查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加模糊匹配条件（左右模糊）。
+
+        :param field_name: 模型字段名称。
+        :param value: 模糊匹配的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": ('%' + value + '%'), "type": self.type_vague}
 
     def left_vague(self, field_name, value: str):
         """
-        左模糊查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加左模糊匹配条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 左模糊匹配的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": ('%' + value), "type": self.type_vague}
 
     def right_vague(self, field_name, value: str):
         """
-        左模糊查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加右模糊匹配条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 右模糊匹配的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": (value + '%'), "type": self.type_vague}
 
     def contains(self, field_name, value: str):
         """
-        包含查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加包含条件。
+
+        :param field_name: 模型字段名称。
+        :param value: 包含的值。
         """
         if value and value != '':
             self.filter_field[field_name] = {"data": value, "type": self.type_contains}
 
     def between(self, field_name, value1, value2):
         """
-        范围查询字段
-        :param field_name: 模型字段名称
-        :param value: 值
+        添加范围查询条件。
+
+        :param field_name: 模型字段名称。
+        :param value1: 范围起始值。
+        :param value2: 范围结束值。
         """
         if value1 and value2 and value1 != '' and value2 != '':
             self.filter_field[field_name] = {"data": [value1, value2], "type": self.type_between}
 
     def get_filter(self, model: db.Model):
         """
-        获取过滤条件
-        :param model: 模型字段名称
+        获取最终的 SQLAlchemy 过滤条件。
+
+        :param model: SQLAlchemy 模型类。
+        :return: 返回组合后的过滤条件。
         """
         for k, v in self.filter_field.items():
             if v.get("type") == self.type_vague:
@@ -123,4 +142,4 @@ class ModelFilter:
                 self.filter_list.append(getattr(model, k) < v.get("data"))
             if v.get("type") == self.type_between:
                 self.filter_list.append(getattr(model, k).between(v.get("data")[0], v.get("data")[1]))
-        return and_(*self.filter_list)
+        return and_(*self.filter_list)