spider_work/jiwu_spider/jw_report_excel.py

# -*- coding: utf-8 -*-
# Author : Charley
# Python : 3.12.10
# Date   : 2026/08/19
"""集物星球报表 Excel 样式工具库（openpyxl）：供在售/已售日报复用统一排版。

  提供分区标题条、表头样式、明细表（斑马纹/新品高亮/金额百分比格式/冻结首行/列宽自适应）、
  键值竖排（概览/汇总）等写入函数。金额一律以「元」浮点写入单元格并套 #,##0.00 格式，
  调用方负责把原始金额值 ÷1000000 后传入（1 元 = 1000000）。
  """
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
from openpyxl.utils import get_column_letter

# 配色（沿用参考项目 deca 报表风格）
FILL_SECTION = PatternFill("solid", fgColor="4472C4")    # 分区标题条：蓝底
FILL_HEADER = PatternFill("solid", fgColor="D9E1F2")     # 表头：浅蓝底
FILL_ZEBRA = PatternFill("solid", fgColor="F5F8FC")      # 明细隔行斑马
FILL_SUBTOTAL = PatternFill("solid", fgColor="FCE4D6")   # 汇总数值：浅橙底
FILL_NEWROW = PatternFill("solid", fgColor="FEF2F2")     # 今日新上架高亮：淡红底
FONT_SECTION = Font(color="FFFFFF", bold=True, size=12)  # 分区标题：白字加粗
FONT_HEADER = Font(color="1F3864", bold=True)            # 表头：深蓝字加粗
FONT_LABEL = Font(color="1F3864", bold=True)             # 键值标签
_SIDE = Side(style="thin", color="D6DCE5")
BORDER = Border(left=_SIDE, right=_SIDE, top=_SIDE, bottom=_SIDE)

MONEY_FMT = "#,##0.00"   # 金额（元）
INT_FMT = "#,##0"        # 计数
PCT_FMT = "0.0%"         # 进度（传入 0~1 小数）

_ALIGN_L = Alignment(horizontal="left", vertical="center", wrap_text=True)
_ALIGN_L_NOWRAP = Alignment(horizontal="left", vertical="center")  # 标题/分区条：不换行，长文本自然向右溢出
_ALIGN_R = Alignment(horizontal="right", vertical="center")
_ALIGN_C = Alignment(horizontal="center", vertical="center", wrap_text=True)


def new_workbook() -> Workbook:
    """新建一个不含默认 sheet 的工作簿。

    Returns:
        Workbook: 已删掉默认 Sheet 的空工作簿，后续用 add_sheet 逐个加。
    """
    wb = Workbook()
    wb.remove(wb.active)
    return wb


def add_sheet(wb: Workbook, title: str):
    """新增一个工作表（表名超长自动截断到 31 字符）。

    Args:
        wb (Workbook): 目标工作簿。
        title (str): 工作表名。

    Returns:
        Worksheet: 新建的工作表。
    """
    return wb.create_sheet(title[:31])


def _disp_width(text: str) -> int:
    """按中文占 2、其余占 1 估算字符串显示宽度。

    Args:
        text (str): 文本。

    Returns:
        int: 估算显示宽度。
    """
    return sum(2 if ord(c) > 127 else 1 for c in str(text))


def _autosize(ws, headers: list, rows: list, base_col: int = 1) -> None:
    """按表头与数据估算并设置各列列宽（clamp 到 [8,60]）。

    Args:
        ws: 工作表。
        headers (list): 表头列表。
        rows (list): 数据行（元组列表）。
        base_col (int): 首列列号（1 起）。Defaults to 1。
    """
    for i, h in enumerate(headers):
        w = _disp_width(h)
        for r in rows:
            if i < len(r) and r[i] is not None:
                w = max(w, _disp_width(r[i]))
        letter = get_column_letter(base_col + i)
        cur = ws.column_dimensions[letter].width or 0  # 只增不减：不覆盖调用方预设的更宽列宽
        ws.column_dimensions[letter].width = max(cur, min(60, max(8, w + 2)))


def _apply_fmt(cell, col_type: str) -> None:
    """按列类型给单元格设数字格式与对齐。

    Args:
        cell: 单元格。
        col_type (str): 列类型 money / int / pct / text。
    """
    if col_type == "money":
        cell.number_format = MONEY_FMT
        cell.alignment = _ALIGN_R
    elif col_type == "int":
        cell.number_format = INT_FMT
        cell.alignment = _ALIGN_R
    elif col_type == "pct":
        cell.number_format = PCT_FMT
        cell.alignment = _ALIGN_R
    else:
        cell.alignment = _ALIGN_L


def write_section_title(ws, row: int, ncols: int, text: str) -> int:
    """写一条横跨 ncols 列的分区标题条。

    Args:
        ws: 工作表。
        row (int): 起始行（1 起）。
        ncols (int): 跨列数。
        text (str): 标题文字。

    Returns:
        int: 下一可写行号。
    """
    # 不用合并单元格：合并区内文字无法溢出、列窄时长标题会被切。改为「给若干列铺底色的空单元格 +
    # 文字写在 A 列不换行」，让文字自然溢出到后面这些有色空单元格上（永远落在色条内、不被截断）。
    span = max(1, ncols)  # 铺色跨度=调用方给定列数（同 sheet 内各标题条传同一 ncols→长度统一、严谨）
    for col in range(1, span + 1):
        ws.cell(row=row, column=col).fill = FILL_SECTION
    c = ws.cell(row=row, column=1, value=text)
    c.font = FONT_SECTION
    c.alignment = _ALIGN_L_NOWRAP  # 不换行，长文本自然向右溢出到有色空单元格
    ws.row_dimensions[row].height = 22
    return row + 1


def write_title(ws, row: int, text: str) -> int:
    """写一条大标题（加粗大字，不填色不合并，自然向右溢出到空列，风格贴近 deca）。

    Args:
        ws: 工作表。
        row (int): 行号。
        text (str): 标题文字。

    Returns:
        int: 下一可写行号。
    """
    c = ws.cell(row=row, column=1, value=text)
    c.font = Font(color="1F3864", bold=True, size=14)
    c.alignment = _ALIGN_L_NOWRAP
    return row + 1


def write_kv(ws, row: int, items: list, title: str = None) -> int:
    """竖排写键值区（指标/数值两列），用于概览、单商家汇总。

    Args:
        ws: 工作表。
        row (int): 起始行。
        items (list): 元素为 (标签, 值, 类型) 的列表；类型取 text/money/int/pct。
        title (str, optional): 若给出，先写一条分区标题条。Defaults to None。

    Returns:
        int: 下一可写行号。
    """
    if title:
        row = write_section_title(ws, row, 2, title)
    for label, value, col_type in items:
        lc = ws.cell(row=row, column=1, value=label)
        lc.font = FONT_LABEL              # 标签：深蓝加粗 + 浅蓝底（对齐 deca 汇总块配色）
        lc.fill = FILL_HEADER
        lc.alignment = _ALIGN_L_NOWRAP
        lc.border = BORDER
        vc = ws.cell(row=row, column=2, value=value)
        vc.fill = FILL_SUBTOTAL           # 数值：浅橙底（对齐 deca）
        vc.border = BORDER
        _apply_fmt(vc, col_type)
        row += 1
    ws.column_dimensions["A"].width = max(ws.column_dimensions["A"].width or 8,
                                          min(40, max(_disp_width(i[0]) for i in items) + 2))
    ws.column_dimensions["B"].width = max(ws.column_dimensions["B"].width or 8, 20)
    return row + 1  # 区块后空一行


def write_table(ws, row: int, headers: list, rows: list, col_types: list,
                new_flags: list = None, freeze: bool = True) -> int:
    """写一张明细表（表头样式 + 斑马纹 + 可选新品高亮 + 数字格式 + 冻结表头 + 列宽自适应）。

    Args:
        ws: 工作表。
        row (int): 表头起始行。
        headers (list): 列标题。
        rows (list): 数据行，每行元组，元素已是展示单位（金额传元、进度传 0~1 小数）。
        col_types (list): 与 headers 等长的列类型 text/money/int/pct。
        new_flags (list, optional): 与 rows 等长的布尔列表，True 的行套新品高亮底色。Defaults to None。
        freeze (bool, optional): 是否冻结表头行。Defaults to True。

    Returns:
        int: 下一可写行号。
    """
    header_row = row
    for i, h in enumerate(headers):
        c = ws.cell(row=header_row, column=1 + i, value=h)
        c.fill = FILL_HEADER
        c.font = FONT_HEADER
        c.alignment = _ALIGN_C
        c.border = BORDER
    ws.row_dimensions[header_row].height = 26

    for ri, data in enumerate(rows):
        r = header_row + 1 + ri
        is_new = bool(new_flags[ri]) if new_flags else False
        for i, val in enumerate(data):
            c = ws.cell(row=r, column=1 + i, value=val)
            c.border = BORDER
            _apply_fmt(c, col_types[i] if i < len(col_types) else "text")
            if is_new:
                c.fill = FILL_NEWROW
            elif ri % 2 == 1:
                c.fill = FILL_ZEBRA

    _autosize(ws, headers, rows)
    if freeze:
        ws.freeze_panes = f"A{header_row + 1}"
    return header_row + 1 + len(rows) + 1  # 表后空一行


def save(wb: Workbook, path: str) -> None:
    """保存工作簿到磁盘。

    Args:
        wb (Workbook): 工作簿。
        path (str): 输出文件路径。
    """
    wb.save(path)