@huicai/cli 2026.814.0 → 2026.1019.0

package/skills/xlsx-analysis/scripts/xlsx_build.py

@@ -0,0 +1,522 @@
+# Excel 报表建表引擎：结构化 spec → 成品 xlsx（列宽先量后画、合计走公式、打印一页宽）。
+#
+# 与 docx_build / pptx_deck 同一条纪律：**模型只给「哪张表放什么」，尺寸与格式由引擎算**。
+# 人手写 openpyxl 会犯的五类错，这里从写法上就不可能发生：
+#   · 合计行写成 Python 算好的常量 → 改一行明细，合计还是旧数，而且**没有任何报错**；
+#     引擎一律写 SUBTOTAL/SUM 公式，改明细自动更新（这是 Excel 交付件最经典的事故）；
+#   · 列宽拍脑袋 → 数字列不够宽就显示成 ####，打印出来一片井号；引擎按内容量（与体检同一把尺）；
+#   · 订单号/身份证不设文本格式 → 前导零消失、18 位变科学计数法；引擎按列名判并强制 '@'；
+#   · 不设打印区域 → 一张宽表打成 6 页、翻页看不见表头；引擎默认缩放到一页宽 + 重复标题行；
+#   · 分组小计与总计都用 SUM → 总计把小计又加了一遍，数字翻倍；引擎一律 SUBTOTAL(9,…)，
+#     它会自动忽略嵌套的 SUBTOTAL，这正是这个函数存在的理由。
+#
+# 落盘后自动跑一遍 xlsx_check 体检，报告随返回值给出。
+
+import datetime
+import json
+import os
+import re
+import sys
+
+from openpyxl import Workbook
+from openpyxl.chart import BarChart, LineChart, PieChart, Reference
+from openpyxl.formatting.rule import CellIsRule, ColorScaleRule, DataBarRule
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+from openpyxl.worksheet.datavalidation import DataValidation
+from openpyxl.worksheet.properties import PageSetupProperties
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import xlsx_layout as L          # noqa: E402
+
+ALIGN = {'left': 'left', 'center': 'center', 'right': 'right'}
+
+
+def _side(color):
+    return Side(style='thin', color=color)
+
+
+class SheetBuilder:
+    """单张工作表建表。行号一律由引擎推，调用方不需要（也不应该）自己数行。"""
+
+    def __init__(self, ws, prof, spec):
+        self.ws, self.prof, self.spec = ws, prof, spec
+        self.c = prof['colors']
+        self.warnings = []
+        self.cols = self._norm_columns()
+        self.rows = self._norm_rows()
+        self.header_row = 1
+        self.first_data = 2
+        self.last_data = 1
+        self.total_row = None
+        self.group_rows = []
+
+    # ── 规范化输入 ────────────────────────────────────────────────────────
+    def _norm_columns(self):
+        cols = self.spec.get('columns')
+        recs = self.spec.get('records')
+        if not cols and recs:
+            keys = []
+            for r in recs:
+                for k in r:
+                    if k not in keys:
+                        keys.append(k)
+            cols = [{'key': k, 'header': k} for k in keys]
+        if not cols and self.spec.get('rows'):
+            head = self.spec['rows'][0]
+            cols = [{'key': i, 'header': str(h)} for i, h in enumerate(head)]
+            self.spec = {**self.spec, 'rows': self.spec['rows'][1:]}
+        out = []
+        for i, c in enumerate(cols or []):
+            c = dict(c) if isinstance(c, dict) else {'key': i, 'header': str(c)}
+            c.setdefault('key', i)
+            c.setdefault('header', str(c['key']))
+            out.append(c)
+        return out
+
+    def _norm_rows(self):
+        if self.spec.get('records') is not None:
+            keys = [c['key'] for c in self.cols]
+            return [[r.get(k) for k in keys] for r in self.spec['records']]
+        return [list(r) for r in (self.spec.get('rows') or [])]
+
+    @staticmethod
+    def _coerce(v, fmt):
+        """按列格式把值写成**正确的类型**。
+
+        引擎不能一边给列标上 yyyy-mm-dd，一边往里写字符串——那样 Excel 既算不了工期，
+        排序也按字典序走，而且下游数据体检会如实报「日期被存成文本」。
+        「先量后画」在类型上的对应物就是这一句。"""
+        if not isinstance(v, str) or not v.strip():
+            return v
+        t = v.strip()
+        if 'yyyy' in str(fmt):
+            m = re.match(r'^(\d{4})\s*[-/.年]\s*(\d{1,2})(?:\s*[-/.月]\s*(\d{1,2})日?)?$', t)
+            if m:
+                y, mo, d = int(m.group(1)), int(m.group(2)), int(m.group(3) or 1)
+                if 1900 <= y <= 2200 and 1 <= mo <= 12 and 1 <= d <= 31:
+                    try:
+                        return datetime.date(y, mo, d)
+                    except ValueError:
+                        return v
+            return v
+        if fmt in (L.FORMATS['text'], 'General', None):
+            return v
+        if re.fullmatch(r'[-+]?[\d,]+(\.\d+)?', t):
+            try:
+                return float(t.replace(',', '')) if '.' in t else int(t.replace(',', ''))
+            except ValueError:
+                return v
+        return v
+
+    def _fmt(self, col, j):
+        if col.get('format'):
+            return L.FORMATS.get(col['format'], col['format'])
+        vals = [r[j] for r in self.rows[:200] if j < len(r)]
+        f = L.guess_format(col['header'], vals)
+        if f == L.FORMATS['amount'] and self.prof.get('default_amount'):
+            return L.FORMATS[self.prof['default_amount']]
+        return f
+
+    # ── 建表 ──────────────────────────────────────────────────────────────
+    def build(self):
+        ws, p, c = self.ws, self.prof, self.c
+        ncol = max(1, len(self.cols))
+        r = 1
+        if self.spec.get('title'):
+            ws.cell(r, 1, self.spec['title'])
+            cell = ws.cell(r, 1)
+            cell.font = Font(name=p['font_west'], size=p['title_size'], bold=True, color=c['title_fg'])
+            cell.alignment = Alignment(horizontal='left', vertical='center')
+            self._ea(cell)
+            if ncol > 1:
+                ws.merge_cells(start_row=r, start_column=1, end_row=r, end_column=ncol)
+            ws.row_dimensions[r].height = p['title_size'] * 2
+            r += 1
+        if self.spec.get('note'):
+            ws.cell(r, 1, self.spec['note'])
+            cell = ws.cell(r, 1)
+            cell.font = Font(name=p['font_west'], size=p['size'] - 1, italic=False, color='808080')
+            self._ea(cell)
+            if ncol > 1:
+                ws.merge_cells(start_row=r, start_column=1, end_row=r, end_column=ncol)
+            r += 1
+        if self.spec.get('title') or self.spec.get('note'):
+            r += 0
+        self.header_row = r
+        self._write_header(r)
+        r += 1
+        self.first_data = r
+        formats = [self._fmt(col, j) for j, col in enumerate(self.cols)]
+        group_by = self.spec.get('group_by')
+        if group_by is not None:
+            r = self._write_grouped(r, formats, group_by)
+        else:
+            r = self._write_rows(r, self.rows, formats)
+        self.last_data = r - 1
+        if self.spec.get('total') and self.rows:
+            self._write_total(r, formats)
+            self.total_row = r
+            r += 1
+        self._widths(formats)
+        self._finish(r)
+        return self
+
+    def _ea(self, cell):
+        """中文字体：openpyxl 只有一个 font.name，中文得靠字体本身支持——用「等线」这类中西文兼备的。"""
+        cell.font = Font(name=self.prof['font'], size=cell.font.size, bold=cell.font.bold,
+                         color=cell.font.color, italic=cell.font.italic)
+
+    def _write_header(self, r):
+        p, c = self.prof, self.c
+        fill = PatternFill('solid', fgColor=c['head_bg'])
+        for j, col in enumerate(self.cols, start=1):
+            cell = self.ws.cell(r, j, col['header'])
+            cell.font = Font(name=p['font'], size=p['head_size'], bold=p['head_bold'], color=c['head_fg'])
+            cell.fill = fill
+            cell.alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
+            if p['borders']:
+                cell.border = Border(*(_side(c['border']),) * 4)
+        self.ws.row_dimensions[r].height = p['head_height']
+
+    def _write_rows(self, r, rows, formats, indent_first=False):
+        p, c = self.prof, self.c
+        stripe = PatternFill('solid', fgColor=c['stripe']) if p['stripe'] else None
+        border = Border(*(_side(c['border']),) * 4) if p['borders'] else None
+        for i, row in enumerate(rows):
+            for j, col in enumerate(self.cols, start=1):
+                v = row[j - 1] if j - 1 < len(row) else None
+                v = self._coerce(v, formats[j - 1])
+                cell = self.ws.cell(r, j, v)
+                cell.font = Font(name=p['font'], size=p['size'])
+                cell.number_format = formats[j - 1]
+                cell.alignment = Alignment(
+                    horizontal=col.get('align') or self._auto_align(formats[j - 1]),
+                    vertical='center', wrap_text=bool(col.get('wrap')))
+                if border:
+                    cell.border = border
+                if stripe and i % 2 == 1:
+                    cell.fill = stripe
+            self.ws.row_dimensions[r].height = p['row_height']
+            r += 1
+        return r
+
+    @staticmethod
+    def _auto_align(fmt):
+        if fmt == L.FORMATS['text'] or fmt == 'General':
+            return 'left'
+        if 'yyyy' in str(fmt):
+            return 'center'
+        return 'right'
+
+    def _write_grouped(self, r, formats, group_by):
+        """分组小计。小计与总计都用 SUBTOTAL(9,…)——它忽略嵌套 SUBTOTAL，总计不会把小计又加一遍。"""
+        keys = [c['key'] for c in self.cols]
+        gj = keys.index(group_by) if group_by in keys else (
+            group_by if isinstance(group_by, int) else 0)
+        sum_cols = self._sum_cols()
+        order, buckets = [], {}
+        for row in self.rows:
+            k = row[gj] if gj < len(row) else ''
+            if k not in buckets:
+                order.append(k)
+                buckets[k] = []
+            buckets[k].append(row)
+        for k in order:
+            start = r
+            r = self._write_rows(r, buckets[k], formats)
+            end = r - 1
+            self._write_subtotal(r, formats, start, end, f'{k} 小计', sum_cols)
+            self.group_rows.append(r)
+            r += 1
+        return r
+
+    def _sum_cols(self):
+        t = self.spec.get('total') or {}
+        want = t.get('cols')
+        keys = [c['key'] for c in self.cols]
+        if want:
+            return [keys.index(w) + 1 for w in want if w in keys]
+        out = []
+        for j, col in enumerate(self.cols, start=1):
+            f = self._fmt(col, j - 1)
+            if f in (L.FORMATS['amount'], L.FORMATS['amount0'], L.FORMATS['int'],
+                     L.FORMATS['accounting']):
+                out.append(j)
+        return out
+
+    def _write_subtotal(self, r, formats, start, end, label, sum_cols):
+        p, c = self.prof, self.c
+        fill = PatternFill('solid', fgColor=c['total_bg'])
+        border = Border(top=_side('808080'), bottom=_side(c['border']),
+                        left=_side(c['border']), right=_side(c['border']))
+        for j in range(1, len(self.cols) + 1):
+            cell = self.ws.cell(r, j)
+            cell.font = Font(name=p['font'], size=p['size'], bold=True)
+            cell.fill = fill
+            cell.border = border
+            cell.number_format = formats[j - 1]
+            if j == 1:
+                cell.value = label
+                cell.alignment = Alignment(horizontal='left', vertical='center')
+            elif j in sum_cols and end >= start:
+                letter = get_column_letter(j)
+                cell.value = f'=SUBTOTAL(9,{letter}{start}:{letter}{end})'
+                cell.alignment = Alignment(horizontal='right', vertical='center')
+        self.ws.row_dimensions[r].height = p['row_height']
+
+    def _write_total(self, r, formats):
+        t = self.spec.get('total') or {}
+        label = t.get('label', '合计')
+        self._write_subtotal(r, formats, self.first_data, self.last_data, label, self._sum_cols())
+
+    def _widths(self, formats):
+        for j, col in enumerate(self.cols, start=1):
+            if col.get('width'):
+                w = float(col['width'])
+            else:
+                vals = [r[j - 1] for r in self.rows if j - 1 < len(r)]
+                w = L.col_width(vals, col['header'], formats[j - 1])
+            self.ws.column_dimensions[get_column_letter(j)].width = w
+
+    def _finish(self, next_row):
+        ws, p, spec = self.ws, self.prof, self.spec
+        last = (self.total_row or self.last_data)
+        ncol = max(1, len(self.cols))
+        if spec.get('freeze', p['freeze']) and self.rows:
+            ws.freeze_panes = f'A{self.header_row + 1}'
+        if spec.get('autofilter', p['autofilter']) and self.rows:
+            ws.auto_filter.ref = (f'A{self.header_row}:'
+                                  f'{get_column_letter(ncol)}{self.last_data}')
+        self._conditional()
+        self._validation()
+        self._chart(next_row)
+        self._print_setup()
+
+    def _conditional(self):
+        keys = [c['key'] for c in self.cols]
+        for rule in (self.spec.get('conditional') or []):
+            col = rule.get('col')
+            if col not in keys:
+                self.warnings.append(f'条件格式跳过：找不到列「{col}」')
+                continue
+            letter = get_column_letter(keys.index(col) + 1)
+            ref = f'{letter}{self.first_data}:{letter}{self.last_data}'
+            kind = str(rule.get('type', 'data_bar'))
+            try:
+                if kind == 'data_bar':
+                    self.ws.conditional_formatting.add(
+                        ref, DataBarRule(start_type='min', end_type='max',
+                                         color=rule.get('color', '638EC6')))
+                elif kind == 'color_scale':
+                    self.ws.conditional_formatting.add(
+                        ref, ColorScaleRule(start_type='min', start_color='F8696B',
+                                            mid_type='percentile', mid_value=50, mid_color='FFEB84',
+                                            end_type='max', end_color='63BE7B'))
+                else:
+                    op = {'gt': 'greaterThan', 'lt': 'lessThan', 'ge': 'greaterThanOrEqual',
+                          'le': 'lessThanOrEqual', 'eq': 'equal'}.get(kind, 'greaterThan')
+                    fill = PatternFill('solid', fgColor=rule.get('color', 'FFC7CE'))
+                    self.ws.conditional_formatting.add(
+                        ref, CellIsRule(operator=op, formula=[str(rule.get('value', 0))], fill=fill))
+            except Exception as e:
+                self.warnings.append(f'条件格式失败（{col}）：{e}')
+
+    def _validation(self):
+        keys = [c['key'] for c in self.cols]
+        for v in (self.spec.get('validation') or []):
+            col = v.get('col')
+            if col not in keys or not v.get('list'):
+                continue
+            letter = get_column_letter(keys.index(col) + 1)
+            items = ','.join(str(x) for x in v['list'])
+            if len(items) > 250:
+                self.warnings.append(f'数据验证跳过（{col}）：候选项超 250 字符，Excel 内联清单放不下')
+                continue
+            dv = DataValidation(type='list', formula1=f'"{items}"', allow_blank=True, showErrorMessage=True)
+            dv.error, dv.errorTitle = '请从下拉列表中选择', '取值不在允许范围'
+            self.ws.add_data_validation(dv)
+            dv.add(f'{letter}{self.first_data}:{letter}{max(self.last_data, self.first_data)}')
+
+    def _chart(self, at_row):
+        ch = self.spec.get('chart')
+        if not ch or not self.rows:
+            return
+        keys = [c['key'] for c in self.cols]
+        cat = ch.get('cat')
+        vals = [v for v in (ch.get('values') or []) if v in keys]
+        if cat not in keys or not vals:
+            self.warnings.append('图表跳过：cat 或 values 指向的列不存在')
+            return
+        kind = str(ch.get('type', 'bar'))
+        chart = {'bar': BarChart, 'line': LineChart, 'pie': PieChart}.get(kind, BarChart)()
+        chart.title = ch.get('title') or self.spec.get('title') or ''
+        chart.height, chart.width = ch.get('height', 8), ch.get('width', 16)
+        cats = Reference(self.ws, min_col=keys.index(cat) + 1,
+                         min_row=self.first_data, max_row=self.last_data)
+        for v in vals:
+            j = keys.index(v) + 1
+            data = Reference(self.ws, min_col=j, min_row=self.header_row, max_row=self.last_data)
+            chart.add_data(data, titles_from_data=True)
+        chart.set_categories(cats)
+        self.ws.add_chart(chart, f'A{at_row + 2}')
+
+    def _print_setup(self):
+        ws, ps = self.ws, dict(self.prof['print'])
+        ps.update(self.spec.get('print') or {})
+        ws.page_setup.orientation = 'landscape' if ps.get('landscape') else 'portrait'
+        ws.page_setup.paperSize = ws.PAPERSIZE_A4 if str(ps.get('page', 'A4')).upper() == 'A4' else ws.PAPERSIZE_A3
+        if ps.get('fit_width', True):
+            ws.sheet_properties.pageSetUpPr = PageSetupProperties(fitToPage=True)
+            ws.page_setup.fitToWidth = 1
+            ws.page_setup.fitToHeight = 0
+        if ps.get('repeat_head', True) and self.rows:
+            ws.print_title_rows = f'{self.header_row}:{self.header_row}'
+        m = float(ps.get('margin_cm', 1.8)) / 2.54
+        ws.page_margins.left = ws.page_margins.right = m
+        ws.page_margins.top = ws.page_margins.bottom = m
+        if ps.get('footer_page', True):
+            ws.oddFooter.center.text = '第 &P 页 / 共 &N 页'
+            ws.oddFooter.center.size = 9
+
+
+def _cover(wb, spec, prof):
+    ws = wb.create_sheet('说明', 0)
+    ws.sheet_view.showGridLines = False
+    c = prof['colors']
+    ws.column_dimensions['A'].width = 18
+    ws.column_dimensions['B'].width = 60
+    ws.cell(1, 1, spec.get('title') or '报表说明')
+    ws.cell(1, 1).font = Font(name=prof['font'], size=18, bold=True, color=c['title_fg'])
+    ws.merge_cells('A1:B1')
+    ws.row_dimensions[1].height = 34
+    rows = list(spec.get('fields') or [])
+    rows.append(['生成日期', spec.get('date') or datetime.date.today().strftime('%Y-%m-%d')])
+    r = 3
+    for k, v in rows:
+        ws.cell(r, 1, str(k)).font = Font(name=prof['font'], size=11, bold=True)
+        ws.cell(r, 1).fill = PatternFill('solid', fgColor=c['total_bg'])
+        ws.cell(r, 1).alignment = Alignment(horizontal='center', vertical='center')
+        ws.cell(r, 2, str(v)).font = Font(name=prof['font'], size=11)
+        ws.cell(r, 2).alignment = Alignment(horizontal='left', vertical='center', wrap_text=True)
+        for j in (1, 2):
+            ws.cell(r, j).border = Border(*(_side(c['border']),) * 4)
+        ws.row_dimensions[r].height = 22
+        r += 1
+    return ws
+
+
+def build(spec, out_path):
+    """spec（dict）→ xlsx。返回 (path, 体检结果, warnings)。"""
+    prof = L.profile(spec.get('profile', 'report'))
+    if spec.get('theme'):
+        prof['colors'] = dict(L.THEMES.get(spec['theme'], prof['colors']))
+        prof['theme'] = spec['theme']
+    # 父目录不存在就建——直接调 API 的场景（如归档生成器批量落盘到子目录）
+    # 拿不到工具层的 resolveOut 兜底，漏了这一句就会在第一个子目录上炸。
+    d = os.path.dirname(os.path.abspath(out_path))
+    if d:
+        os.makedirs(d, exist_ok=True)
+    wb = Workbook()
+    wb.remove(wb.active)
+    warns = []
+    sheets = spec.get('sheets') or []
+    if not sheets:
+        raise ValueError('spec 至少要有一张 sheet（sheets: [{name, columns, rows}]）')
+    for s in sheets:
+        name = str(s.get('name') or f'Sheet{len(wb.sheetnames)+1}')
+        safe = re.sub(r'[\\/:*?\[\]]', '_', name)[:31]
+        if safe != name:
+            warns.append(f'工作表名「{name}」含非法字符或超 31 字，已改为「{safe}」')
+        if safe in wb.sheetnames:
+            safe = f'{safe[:28]}_{len(wb.sheetnames)}'
+        ws = wb.create_sheet(safe)
+        b = SheetBuilder(ws, prof, s).build()
+        warns.extend(f'[{safe}] {w}' for w in b.warnings)
+    if spec.get('cover'):
+        _cover(wb, spec['cover'], prof)
+    wb.save(out_path)
+    res = None
+    if spec.get('inspect', True):
+        try:
+            import xlsx_check
+            res = xlsx_check.inspect(out_path, prof['name'])
+        except Exception as e:
+            warns.append(f'体检未能运行：{e}')
+    return out_path, res, warns
+
+
+def from_frames(frames, out_path, profile='report', **kw):
+    """{sheet名: DataFrame} → 成品 xlsx（write_styled 的升级替代：带合计公式与打印设置）。"""
+    import pandas as pd
+    if hasattr(frames, 'columns'):
+        frames = {'Sheet1': frames}
+    sheets = []
+    for name, df in frames.items():
+        cols = [{'key': str(c), 'header': str(c)} for c in df.columns]
+        rows = df.where(pd.notna(df), None).values.tolist()
+        sheets.append({'name': str(name), 'columns': cols, 'rows': rows,
+                       **{k: v for k, v in kw.items() if k in
+                          ('title', 'note', 'total', 'group_by', 'chart', 'conditional', 'validation')}})
+    if kw.get('total') is True:
+        for s in sheets:
+            s['total'] = {'label': '合计'}
+    return build({'profile': profile, 'sheets': sheets,
+                  **{k: v for k, v in kw.items() if k in ('theme', 'cover', 'inspect')}}, out_path)
+
+
+def main(argv):
+    if len(argv) < 2:
+        print('用法：python xlsx_build.py spec.json 输出.xlsx  |  python xlsx_build.py --demo 出.xlsx')
+        return 2
+    if argv[0] == '--demo':
+        return _demo(argv[1])
+    spec = json.load(open(argv[0], encoding='utf-8'))
+    try:
+        path, res, warns = build(spec, argv[1])
+    except Exception as e:
+        print(json.dumps({'error': f'{type(e).__name__}: {e}'}, ensure_ascii=False))
+        return 1
+    out = {'path': path, 'warnings': warns}
+    if res:
+        import xlsx_check
+        out['check'] = {'counts': res['counts'], 'stats': res['stats']}
+        out['report'] = xlsx_check.report(res, show_info=False)
+    print(json.dumps(out, ensure_ascii=False, default=str))
+    return 0
+
+
+def _demo(out):
+    rows = [['华东', '上海', 12000.0, 9800.0, 0.224],
+            ['华东', '江苏', 8600.5, 7200.0, 0.194],
+            ['华南', '广东', 15300.0, 13100.0, 0.168],
+            ['华南', '福建', 4200.0, 3900.0, 0.077],
+            ['西南', '四川', 6100.0, 5600.0, 0.089]]
+    spec = {
+        'profile': 'report',
+        'cover': {'title': '2026 年 8 月经营报表', 'fields': [
+            ['编制单位', '数据一部'], ['数据口径', '含税，截至 2026-08-31'], ['数据来源', 'ERP 销售出库单']]},
+        'sheets': [{
+            'name': '分区域明细', 'title': '2026 年 8 月分区域销售明细',
+            'note': '口径：含税金额，单位万元；毛利率=毛利/销售额',
+            'columns': [{'key': 'region', 'header': '大区'}, {'key': 'prov', 'header': '省份'},
+                        {'key': 'amt', 'header': '销售额', 'format': 'amount'},
+                        {'key': 'cost', 'header': '成本', 'format': 'amount'},
+                        {'key': 'rate', 'header': '毛利率', 'format': 'percent'}],
+            'rows': rows, 'group_by': 'region', 'total': {'label': '总计'},
+            'conditional': [{'col': 'amt', 'type': 'data_bar'}],
+            'chart': {'type': 'bar', 'cat': 'prov', 'values': ['amt'], 'title': '各省销售额'},
+        }],
+    }
+    path, res, warns = build(spec, out)
+    print(f'demo → {path}')
+    if warns:
+        print('提示：' + '；'.join(warns))
+    if res:
+        import xlsx_check
+        print(xlsx_check.report(res))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))