424 lines
18 KiB
Python
424 lines
18 KiB
Python
"""报表服务模块
|
||
|
||
负责业绩统计报表的查询和导出。
|
||
支持按月、按季、按年三种统计维度，可导出为 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.contract_amount 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()
|