dingdanquanliucheng/backend/app/services/export_service.py

"""
业绩报表导出服务模块。

职责：
    将业绩统计数据导出为 CSV 或 Excel（xlsx）格式的文件，供用户下载。
    负责文件命名、格式校验、内容写入和格式美化。

依赖：
    - openpyxl：Excel 文件生成
    - csv：标准库 CSV 写入

被引用方：
    - ReportService.export_performance()：调用本服务生成导出文件
"""

import csv
from datetime import datetime
from pathlib import Path

from openpyxl import Workbook


class ExportService:
    """业绩报表导出服务。

    根据传入的业绩报表数据，生成 CSV 或 Excel 格式的导出文件，
    并返回文件元信息（路径、大小、MIME 类型等）供上层服务上传到 OSS。

    导出文件存储在本地 /tmp/order-flow-exports 目录下。
    """

    def __init__(self) -> None:
        from backend.app.core.config import get_settings
        settings = get_settings()
        # 复用 LOCAL_UPLOAD_DIR 的父目录，保持路径风格一致
        self.export_root = Path(settings.local_upload_dir).parent / "exports"
        self.export_root.mkdir(parents=True, exist_ok=True)

    def build_performance_export(self, report: dict, export_format: str = "csv") -> dict:
        """根据业绩报表数据生成导出文件。

        根据指定的导出格式（csv 或 xlsx），将报表数据写入本地文件，
        并返回文件元信息供上层服务上传到 OSS。

        参数：
            report (dict): 业绩报表数据，包含 stat_type（统计类型）和 list（数据列表）
            export_format (str): 导出格式，支持 "csv" 和 "xlsx"，默认 "csv"

        返回：
            dict: 包含 file_name、file_path、file_size、content_type、
                  object_key、export_format 等字段

        被调用方：
            - ReportService.export_performance() → 业绩报表导出 API
        """
        timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
        suffix = report["stat_type"]
        normalized_format = self._normalize_export_format(export_format)
        file_name = f"performance-{suffix}-{timestamp}.{normalized_format}"
        file_path = self.export_root / file_name

        if normalized_format == "xlsx":
            self._write_xlsx(file_path, report)
            content_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        else:
            self._write_csv(file_path, report)
            content_type = "text/csv"

        return {
            "file_name": file_name,
            "file_path": str(file_path),
            "file_size": file_path.stat().st_size,
            "content_type": content_type,
            "object_key": f"exports/performance/{file_name}",
            "export_format": normalized_format,
        }

    def _normalize_export_format(self, export_format: str) -> str:
        """校验并标准化导出格式。

        将传入的格式字符串转为小写并去除空白，若不在支持的格式列表中
        则默认回退为 csv。

        参数：
            export_format (str): 用户指定的导出格式

        返回：
            str: 标准化后的格式字符串（"csv" 或 "xlsx"）
        """
        normalized = (export_format or "csv").strip().lower()
        if normalized not in {"csv", "xlsx"}:
            return "csv"
        return normalized

    def _write_csv(self, file_path: Path, report: dict) -> None:
        """将报表数据写入 CSV 文件。

        使用 UTF-8-BOM 编码写入，确保 Excel 打开时中文不乱码。
        第一行为表头，后续每行对应一条统计周期数据。

        参数：
            file_path (Path): 目标 CSV 文件路径
            report (dict): 报表数据，包含 list 列表
        """
        with file_path.open("w", encoding="utf-8-sig", newline="") as csvfile:
            writer = csv.writer(csvfile)
            writer.writerow(["统计周期", "订单数", "订单金额", "固定提成", "分类明细"])
            for item in report["list"]:
                writer.writerow(self._build_row(item))
            writer.writerow(self._build_summary_row(report["list"]))

    def _write_xlsx(self, file_path: Path, report: dict) -> None:
        """将报表数据写入 Excel 文件。

        使用 openpyxl 创建工作簿，写入表头和数据行，并对表头加粗、
        列宽做最小可读性优化，避免客户打开后像原始数据转储。

        参数：
            file_path (Path): 目标 xlsx 文件路径
            report (dict): 报表数据，包含 list 列表
        """
        workbook = Workbook()
        sheet = workbook.active
        sheet.title = "业绩统计"
        sheet.append(["统计周期", "订单数", "订单金额", "固定提成", "分类明细"])
        for item in report["list"]:
            sheet.append(self._build_row(item))
        summary = self._build_summary_row(report["list"])
        sheet.append(summary)
        # 给导出表加最小可读性优化，避免客户打开后仍像原始数据转储。
        for cell in sheet[1]:
            cell.font = cell.font.copy(bold=True)
        # 合计行加粗
        last_row = sheet.max_row
        for cell in sheet[last_row]:
            cell.font = cell.font.copy(bold=True)
        sheet.column_dimensions["A"].width = 18
        sheet.column_dimensions["B"].width = 12
        sheet.column_dimensions["C"].width = 16
        sheet.column_dimensions["D"].width = 16
        sheet.column_dimensions["E"].width = 48
        workbook.save(file_path)

    def _build_summary_row(self, items: list) -> list:
        """构建合计行。"""
        total_count = sum(item["order_count"] for item in items)
        total_amount = sum(item["order_amount"] for item in items)
        total_commission = sum(item["commission_amount"] for item in items)
        return [
            "合计",
            total_count,
            f"{total_amount:.2f}",
            f"{total_commission:.2f}",
            "",
        ]

    def _build_row(self, item: dict) -> list:
        """将单条报表数据项转换为表格行。

        将分类明细的金额列表用中文分号连接为可读字符串，
        数值字段格式化为保留两位小数的字符串。

        参数：
            item (dict): 单条报表数据，包含 stat_period、order_count、
                         order_amount、commission_amount、category_amounts

        返回：
            list: 包含 [统计周期, 订单数, 订单金额, 固定提成, 分类明细] 的列表
        """
        category_text = "；".join(
            f"{category['category_name']}:{category['amount']:.2f}"
            for category in item.get("category_amounts", [])
        )
        return [
            item["stat_period"],
            item["order_count"],
            f"{item['order_amount']:.2f}",
            f"{item['commission_amount']:.2f}",
            category_text,
        ]


export_service = ExportService()