""" 分类管理服务模块 ============================================================= 该模块实现了分类管理相关的所有业务逻辑。 包括分类的列表查询、详情查询、添加、更新、删除、树形数据获取等功能。 命名规范： - 函数参数使用驼峰命名（如 categoryId, pageNo） - 表单字段使用下划线命名（如 category_name, parent_id）- 与数据库字段保持一致 - 返回数据使用驼峰命名（如 createUser, updateTime）- 与前端规范保持一致 - 私有函数以下划线开头（如 _apply_filters） 功能模块： 1. 列表查询：支持按名称模糊搜索，按sort字段排序 2. 详情查询：根据ID获取单个分类的详细信息 3. 数据维护：分类的添加、更新、删除（支持批量） 4. 树形数据：获取所有分类数据（用于树形展示、下拉选择等场景） 5. 获取子分类：根据父级ID获取子分类列表 6. 获取分类树：构建完整的分类树结构 """ import logging from datetime import datetime, timezone from flask import request from sqlalchemy import and_ from application.forms.category import CategoryForm from application.models.category import Category from extensions import db from utils import R, regular from utils.case_converter import convert_camel_to_snake from utils.request import parse_request_body, parse_id_list, like_contains from utils.model_utils import models_to_list, model_to_dict from utils.security import get_username # 获取日志记录器 logger = logging.getLogger(__name__) # ============================================================ # 分类列表查询 # ============================================================ def get_category_list(): """ 查询分类列表（无分页） 用于分类管理页面的列表展示，支持按名称模糊搜索。 Args: request: Flask request对象，包含查询参数 - category_name: 分类名称（可选，模糊查询） - type: 分类类型（可选，精确查询） Returns: R: 包含分类列表的JSON响应 """ try: # 应用筛选条件 query = _apply_filters() # 查询数据 category_list = query.all() # 转换为字典列表 records = models_to_list(category_list) return R.ok(data=records) except Exception as e: logger.error(f"查询分类列表异常: {str(e)}") return R.failed(msg="查询失败，请稍后重试") def _apply_filters(): """ 应用查询筛选条件 根据请求参数动态构建查询条件： - 自动过滤已删除记录（is_delete == 0） - 支持分类名称模糊查询 - 支持分类类型精确查询 Returns: Query: 应用筛选后的SQLAlchemy查询对象 """ # 基础查询：过滤已删除记录 query = Category.query.filter(Category.is_delete == 0) # 分类名称模糊筛选 category_name = request.args.get('category_name') if category_name: query = query.filter(Category.category_name.like(like_contains(category_name), escape='\\')) # 分类类型精确筛选 type = request.args.get('type') if type: query = query.filter(Category.type == type) # 按排序值升序排列 return query.order_by(Category.sort.asc()) # ============================================================ # 分类详情查询 # ============================================================ def get_category_detail(category_id): """ 根据ID查询分类详情（返回字典格式） 此方法调用 get_info 获取模型对象，然后转换为字典格式返回。 适用于前端接口调用。 Args: category_id: 分类ID Returns: dict/None: 分类详情字典，不存在时返回 None """ try: # 复用 get_info 方法查询分类 category = get_info(category_id) if not category: return None # 转换为字典格式 return model_to_dict(category) except Exception as e: logger.error(f"查询分类详情异常，ID: {category_id}, 错误: {str(e)}") return None # ============================================================ # 分类信息查询（根据ID）- 核心查询方法 # ============================================================ def get_info(category_id: int): """ 根据ID查询分类信息（返回模型对象） 这是一个通用的分类查询方法，返回分类模型对象而非字典。 与 get_category_detail 的区别： - get_category_detail: 返回字典格式，用于前端接口 - get_info: 返回模型对象，用于内部服务调用 此方法被以下方法复用： - get_category_detail: 获取详情字典 - update_category: 验证分类是否存在 - delete_categories: 验证分类是否存在 Args: category_id: 分类ID Returns: Category/None: 分类模型对象，不存在或已删除时返回 None Example: category = get_info(category_id) if category: print(category.category_name) """ # 参数有效性验证 if not category_id or category_id <= 0: return None try: # 查询未删除的分类 category = Category.query.filter( and_(Category.id == category_id, Category.is_delete == 0) ).first() return category except Exception as e: logger.error(f"查询分类信息异常，ID: {category_id}, 错误: {str(e)}") return None # ============================================================ # 分类添加 # ============================================================ def add_category(): """ 添加分类 流程： 1. 解析请求体JSON数据 2. 表单验证（名称唯一性、字段格式等） 3. 创建分类对象并保存到数据库 Returns: R: 操作结果 """ try: # 获取参数 json_data, error = parse_request_body() if error: return R.failed(msg=error) # 表单验证 form = CategoryForm(data=json_data) if not form.validate(): err_msg = regular.get_err(form) return R.failed(msg=err_msg) # 创建分类 category = Category(**form.data) category.create_user = get_username() category.save() return R.ok(msg="添加成功") except Exception as e: logger.error(f"添加分类异常: {str(e)}") return R.failed(msg="添加分类失败，请稍后重试") # ============================================================ # 分类更新 # ============================================================ def update_category(): """ 更新分类 流程： 1. 解析请求体JSON数据 2. 表单验证 3. 验证分类是否存在（复用 get_info） 4. 更新分类信息 Returns: R: 操作结果 """ try: # 获取参数 json_data, error = parse_request_body() if error: return R.failed(msg=error) # 表单验证 form = CategoryForm(data=json_data) if not form.validate(): return R.failed(msg=regular.get_err(form)) # 获取分类ID category_id = form.data.get('id') if not category_id or int(category_id) <= 0: return R.failed("分类ID无效") category_id = int(category_id) # 复用 get_info 方法验证分类是否存在 category = get_info(category_id) if not category: return R.failed("分类不存在") # 更新分类信息（移除ID，避免更新主键） form_data = convert_camel_to_snake(form.data.copy()) form_data.pop('id', None) form_data['update_time'] = datetime.now(tz=timezone.utc) form_data['update_user'] = get_username() result = Category.query.filter_by(id=category_id).update(form_data) if not result: return R.failed("更新失败") return R.ok(msg="更新成功") except Exception as e: logger.error(f"更新分类异常: {str(e)}") return R.failed(msg="更新分类失败，请稍后重试") # ============================================================ # 分类删除 # ============================================================ def delete_categories(category_ids): """ 删除分类（批量删除） 删除 支持逗号分隔的多个ID批量删除。 Args: category_ids: 分类ID字符串，多个ID用逗号分隔，如 "1,2,3" Returns: R: 操作结果 """ if not category_ids: return R.failed("记录ID不存在") # 解析ID列表 id_list = parse_id_list(category_ids) if not id_list: return R.failed("无效的记录ID") # 检查是否有子分类 for category_id in id_list: child_count = Category.query.filter( and_(Category.parent_id == category_id, Category.is_delete == 0) ).count() if child_count > 0: return R.failed("存在子分类，请先删除子分类") return Category.batch_delete_r(category_ids) # ============================================================ # 分类数据获取（用于下拉选择、树形展示） # ============================================================ def get_category_data(): """ 获取分类数据列表（无分页） 用于分类下拉选择框、树形展示等需要全部数据的场景。 按排序值升序排列。 Returns: list: 分类列表，每个元素为分类模型字典，无数据时返回空列表 """ try: # 查询所有未删除的分类 category_list = Category.query.filter( Category.is_delete == 0 ).order_by(Category.sort.asc()).all() # 转换为字典列表 result = models_to_list(category_list) return result except Exception as e: logger.error(f"获取分类数据异常: {str(e)}") return []