"""报表服务模块 负责业绩统计报表的查询和导出。 支持按月、按季、按年三种统计维度，可导出为 CSV 或 XLSX 格式。 导出时自动关联附件管理和审计日志。 被调用方：reports 路由（业绩报表查询、报表导出接口）。 """ from collections import defaultdict from datetime import datetime from sqlalchemy import select from sqlalchemy.exc import SQLAlchemyError from sqlalchemy.orm import Session from backend.app.core.error_codes import ErrorCode from backend.app.core.exceptions import AppException from backend.app.models.business import PerformanceStatCache from backend.app.repositories.report_repository import ReportRepository from backend.app.services.audit_service import audit_service from backend.app.services.export_service import export_service from backend.app.services.file_service import file_service from backend.app.services.storage_service import storage_service class ReportService: """业绩报表业务服务。 依赖： - ReportRepository：报表数据查询 - ExportService：构建导出文件 - StorageService：文件上传发布 - FileService：附件记录保存 - AuditService：操作审计日志 """ def __init__(self) -> None: self.repository = ReportRepository() def performance_report(self, filters: dict, session: Session | None = None) -> dict: """查询业绩统计报表数据。 根据统计类型（月/季/年）和筛选条件，聚合订单行数据生成报表。 支持缓存：命中缓存直接返回，未命中则查库后写入缓存。 参数： filters: 筛选条件字典，包含 stat_type、start_date、end_date、category_id、salesman_id 等。 session: 数据库会话，不可为 None。 返回： 包含 stat_type、list、cache_state 等信息的字典。 """ stat_type = self._normalize_stat_type(filters.get("stat_type")) parsed_filters = self._parse_filters(filters, stat_type) if session is not None: try: # 尝试读取缓存（仅简单查询时使用缓存） use_cache = ( not parsed_filters.get("start_date") and not parsed_filters.get("end_date") and not parsed_filters.get("category_id") and not parsed_filters.get("salesman_id") ) if use_cache: cached = self._load_cache(session, stat_type) if cached is not None: return cached rows = self.repository.list_performance_rows(session, parsed_filters) report_list = self._build_report_list(rows, stat_type) if use_cache: self._save_cache(session, stat_type, report_list) return { "stat_type": stat_type, "list": report_list, "cache_state": "实时生成", "cache_expired": False, } except SQLAlchemyError as exc: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) def export_performance_report(self, filters: dict, session: Session | None = None) -> dict: """导出业绩统计报表为文件（CSV 或 XLSX）。 先查询报表数据，再调用 ExportService 生成文件，最后上传到存储服务并记录附件和审计日志。 参数： filters: 筛选条件字典，额外需要 export_format 字段。 session: 数据库会话，不可为 None。 返回： 包含 file_url、file_name、object_key 等文件信息及报表元数据的字典。 被调用方：reports 路由（报表导出接口）。 """ report = self.performance_report(filters, session) export_format = self._normalize_export_format(filters.get("export_format")) export_meta = export_service.build_performance_export(report, export_format) publish_meta = storage_service.publish_local_file(export_meta["file_path"], export_meta["object_key"]) attachment_payload = { "biz_type": "performance_report", "biz_id": int(datetime.now().strftime("%Y%m%d%H%M%S")), "file_name": export_meta["file_name"], "file_url": publish_meta["file_url"], "file_type": export_meta["content_type"], "file_size": export_meta["file_size"], } attachment_result = file_service.save_attachment(attachment_payload, session) if session is not None else { "file_url": publish_meta["file_url"], "file_name": export_meta["file_name"], "attachment_id": 0, "object_key": publish_meta["object_key"], } if session is not None: audit_service.write_log( session, { "operate_type": "report_export", "biz_type": "performance_report", "biz_id": attachment_result.get("attachment_id", 0), "before_value": None, "after_value": { "file_name": export_meta["file_name"], "stat_type": report["stat_type"], "export_format": export_format, "total_periods": len(report["list"]), }, "remark": "导出业绩统计报表", }, ) session.commit() return { "file_url": attachment_result["file_url"], "file_name": export_meta["file_name"], "object_key": publish_meta["object_key"], "storage_provider": publish_meta["storage_provider"], "bucket_name": publish_meta["bucket_name"], "stat_type": report["stat_type"], "export_format": export_format, "total_periods": len(report["list"]), "filters": { "start_date": filters.get("start_date"), "end_date": filters.get("end_date"), "category_id": filters.get("category_id"), }, } def audit_report(self, filters: dict, session: Session | None = None) -> dict: """查询报表核对数据。 在业绩报表基础上，动态计算异常项和真实剔除数。 """ stat_type = self._normalize_stat_type(filters.get("stat_type")) parsed_filters = self._parse_filters(filters, stat_type) if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) rows = self.repository.list_performance_rows(session, parsed_filters) report_list = self._build_report_list(rows, stat_type) issues = [] for item in report_list: period = item["stat_period"] order_count = item["order_count"] order_amount = item["order_amount"] commission = item["commission_amount"] if order_count > 0 and order_amount == 0: issues.append({"title": f"{period} 金额异常", "stat_period": period, "description": f"该周期有 {order_count} 笔订单但金额为零。", "type": "amount_zero"}) if order_amount > 0: rate = commission / order_amount if rate > 0.15: issues.append({"title": f"{period} 提成比例偏高", "stat_period": period, "description": f"提成比例 {rate:.1%} 超过 15% 阈值。", "type": "commission_high"}) elif rate < 0.01: issues.append({"title": f"{period} 提成比例偏低", "stat_period": period, "description": f"提成比例 {rate:.2%} 低于 1%。", "type": "commission_low"}) excluded_count = 0 if filters.get("exclude_ecommerce"): excluded_count = self.repository.count_excluded_orders(session, parsed_filters) return { "stat_type": stat_type, "list": report_list, "issues": issues, "excluded_count": excluded_count, } def _load_cache(self, session: Session, stat_type: str) -> dict | None: """从缓存表加载业绩统计数据。 按 stat_type 匹配最近一条缓存记录，若 created_at 超过 24 小时视为过期。 """ import json from datetime import timedelta as td cutoff = datetime.now() - td(hours=24) stmt = ( select(PerformanceStatCache) .where(PerformanceStatCache.stat_type == stat_type, PerformanceStatCache.created_at >= cutoff) .order_by(PerformanceStatCache.created_at.desc()) ) rows = list(session.execute(stmt).scalars().all()) if not rows: return None latest = rows[0] return { "stat_type": stat_type, "list": [ { "stat_period": r.stat_period, "order_count": r.order_count, "order_amount": float(r.order_amount), "commission_amount": float(r.commission_amount), "total_profit": float(r.total_profit), "category_amounts": json.loads(r.category_amounts_json) if r.category_amounts_json else [], } for r in rows ], "cache_state": "缓存命中", "cache_updated_at": str(latest.created_at), "cache_expired": False, } def _save_cache(self, session: Session, stat_type: str, report_list: list) -> None: """将报表结果写入缓存表（先清旧数据再写入）。""" import json from sqlalchemy import delete session.execute(delete(PerformanceStatCache).where(PerformanceStatCache.stat_type == stat_type)) for item in report_list: cache = PerformanceStatCache( stat_type=stat_type, stat_period=item["stat_period"], order_count=item["order_count"], order_amount=item["order_amount"], commission_amount=item["commission_amount"], total_profit=item.get("total_profit", 0), category_amounts_json=json.dumps(item.get("category_amounts", []), ensure_ascii=False), ) session.add(cache) session.flush() def _normalize_stat_type(self, stat_type: str | None) -> str: """校验并归一化统计类型参数。 参数： stat_type: 原始统计类型值，支持 'month'、'quarter'、'year'，默认 'month'。 返回： 归一化后的统计类型字符串。 异常： 参数不合法时抛出 AppException（PARAM_ERROR）。 """ value = (stat_type or "month").strip().lower() if value not in {"month", "quarter", "year"}: raise AppException(code=ErrorCode.PARAM_ERROR, message="统计类型不支持", status_code=400) return value def _normalize_export_format(self, export_format: str | None) -> str: """校验并归一化导出格式参数。 参数： export_format: 原始导出格式值，支持 'csv'、'xlsx'，默认 'csv'。 返回： 归一化后的导出格式字符串。 """ value = (export_format or "csv").strip().lower() if value not in {"csv", "xlsx"}: raise AppException(code=ErrorCode.PARAM_ERROR, message="导出格式仅支持 csv 或 xlsx", status_code=400) return value def _parse_filters(self, filters: dict, stat_type: str) -> dict: """解析前端传入的筛选条件为内部可用的过滤参数。 参数： filters: 原始筛选字典。 stat_type: 已归一化的统计类型。 返回： 包含 stat_type、start_date、end_date、category_id、exclude_ecommerce 的字典。 """ parsed = { "stat_type": stat_type, "start_date": self._parse_date(filters.get("start_date"), "开始日期格式错误"), "end_date": self._parse_date(filters.get("end_date"), "结束日期格式错误"), "category_id": filters.get("category_id"), "exclude_ecommerce": bool(filters.get("exclude_ecommerce")), "salesman_id": filters.get("salesman_id"), } if parsed["start_date"] and parsed["end_date"] and parsed["start_date"] > parsed["end_date"]: raise AppException(code=ErrorCode.PARAM_ERROR, message="开始日期不能晚于结束日期", status_code=400) return parsed def _parse_date(self, value: str | None, error_message: str) -> datetime | None: """将日期字符串解析为 datetime 对象。 参数： value: 日期字符串，格式为 'YYYY-MM-DD'，空值时返回 None。 error_message: 解析失败时的错误提示信息。 返回： datetime 对象或 None。 """ if value is None or not str(value).strip(): return None try: return datetime.strptime(str(value).strip(), "%Y-%m-%d") except ValueError as exc: raise AppException(code=ErrorCode.PARAM_ERROR, message=error_message, status_code=400) from exc def _build_report_list(self, rows: list, stat_type: str) -> list[dict]: """将原始订单行数据按统计周期分组聚合，生成报表列表。 参数： rows: 数据库查询返回的订单行列表。 stat_type: 统计类型（month/quarter/year），决定周期分组方式。 返回： 按时间顺序排列的统计周期汇总列表，每个元素包含 order_count、order_amount、 category_amounts、commission_amount 等。 """ grouped: dict[str, dict] = {} period_order: list[str] = [] for row in rows: created_at = row.created_at if created_at is None: continue stat_period = self._format_stat_period(created_at, stat_type) if stat_period not in grouped: grouped[stat_period] = { "stat_period": stat_period, "order_ids": set(), "order_amount": 0.0, "commission_by_order": {}, "sale_price_by_order": {}, "cost_price_by_order": {}, "profit_by_order": {}, "category_amounts": defaultdict(lambda: {"category_id": 0, "category_name": "未分类", "amount": 0.0}), } period_order.append(stat_period) period_data = grouped[stat_period] line_amount = float(row.quantity or 0) * float(row.sale_price or 0) period_data["order_amount"] += line_amount period_data["order_ids"].add(row.order_id) if row.order_id not in period_data["commission_by_order"]: period_data["commission_by_order"][row.order_id] = float(row.commission_amount or 0) if row.order_id not in period_data["sale_price_by_order"]: period_data["sale_price_by_order"][row.order_id] = float(row.sale_price_total or 0) if row.order_id not in period_data["cost_price_by_order"]: period_data["cost_price_by_order"][row.order_id] = float(row.cost_price_total or 0) if row.order_id not in period_data["profit_by_order"]: period_data["profit_by_order"][row.order_id] = float(row.profit_total or 0) category_key = row.category_id or 0 category_item = period_data["category_amounts"][category_key] category_item["category_id"] = row.category_id or 0 category_item["category_name"] = row.category_name or "未分类" category_item["amount"] += line_amount result: list[dict] = [] for stat_period in period_order: period_data = grouped[stat_period] category_amounts = sorted( ( { "category_id": item["category_id"], "category_name": item["category_name"], "amount": round(item["amount"], 2), } for item in period_data["category_amounts"].values() ), key=lambda item: (-item["amount"], item["category_id"]), ) total_sale_price = sum(period_data["sale_price_by_order"].values()) total_cost_price = sum(period_data["cost_price_by_order"].values()) total_profit = sum(period_data["profit_by_order"].values()) total_commission = sum(period_data["commission_by_order"].values()) result.append( { "stat_period": stat_period, "order_count": len(period_data["order_ids"]), "order_amount": round(period_data["order_amount"], 2), "category_amounts": category_amounts, "commission_amount": round(total_commission, 2), "total_sale_price": round(total_sale_price, 2), "total_cost_price": round(total_cost_price, 2), "total_profit": round(total_profit, 2), "total_profit_rate": round(total_sale_price and (total_profit / total_sale_price * 100) or 0, 2), } ) return result def _format_stat_period(self, dt: datetime, stat_type: str) -> str: """将日期按统计类型格式化为统计周期标识字符串。 参数： dt: 日期时间对象。 stat_type: 统计类型，'year' 返回 'YYYY'，'quarter' 返回 'YYYY-QN'，'month' 返回 'YYYY-MM'。 返回： 统计周期标识字符串。 """ if stat_type == "year": return dt.strftime("%Y") if stat_type == "quarter": quarter = ((dt.month - 1) // 3) + 1 return f"{dt.year}-Q{quarter}" return dt.strftime("%Y-%m") report_service = ReportService()