@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,389 @@
+# 表格引擎压力测试台：正向跑批 + **反向造缺陷** + 反误报 + 自动校正闭环。
+#
+# 为什么必须有反向：一个只会说「未发现问题」的体检器和没有体检器是一回事，
+# 而且更糟——它给了人一个虚假的「已检查」印象。Excel 尤其如此：它的事故不改变外观，
+# 只改变数字，肉眼根本复核不了，全靠这一层证明检查真的会响。
+#
+# 反误报同等重要，方向相反：分组小计用 SUBTOTAL、标题横幅在表头之上、说明页没有筛选，
+# 这些都是**正确做法**，把它们判成毛病等于逼人把规范写法改坏。
+#
+# 用法：python xlsx_battery.py [份数] [--keep]
+# 改了 xlsx_layout / xlsx_build / xlsx_check 任何一个，**必须重跑**。
+
+import os
+import random
+import shutil
+import sys
+import tempfile
+from collections import Counter
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from openpyxl import load_workbook                      # noqa: E402
+from openpyxl.styles import Font                        # noqa: E402
+from openpyxl.utils import get_column_letter            # noqa: E402
+
+import xlsx_build as B                                  # noqa: E402
+import xlsx_check as C                                  # noqa: E402
+import xlsx_layout as L                                 # noqa: E402
+
+REGIONS = ['华东', '华南', '华北', '西南', '东北', '西北']
+PROVS = ['上海', '江苏', '广东', '福建', '北京', '四川', '辽宁', '陕西', '浙江', '山东']
+METRICS = [('销售额', 'amount'), ('成本', 'amount'), ('毛利', 'amount'),
+           ('数量', 'int'), ('完成率', 'percent'), ('客户数', 'int')]
+
+
+def random_spec(rng):
+    prof = rng.choice(['report', 'plain', 'finance'])
+    n_sheet = rng.randint(1, 3)
+    sheets = []
+    for k in range(n_sheet):
+        mets = rng.sample(METRICS, rng.randint(1, 4))
+        cols = [{'key': 'region', 'header': '大区'}, {'key': 'prov', 'header': '省份'}]
+        cols += [{'key': f'm{i}', 'header': h, 'format': f} for i, (h, f) in enumerate(mets)]
+        rows = []
+        for _ in range(rng.randint(2, 40)):
+            r = [rng.choice(REGIONS), rng.choice(PROVS)]
+            for _h, f in mets:
+                r.append(round(rng.uniform(0, 1), 4) if f == 'percent'
+                         else (rng.randint(1, 9999) if f == 'int' else round(rng.uniform(-5e4, 5e6), 2)))
+            rows.append(r)
+        s = {'name': f'表{k+1}_{rng.choice(["明细","汇总","台账"])}', 'columns': cols, 'rows': rows}
+        if rng.random() < 0.5:
+            s['title'] = f'{rng.choice(REGIONS)}区域{rng.choice(["销售","成本","经营"])}明细'
+        if rng.random() < 0.4:
+            s['note'] = '口径：含税；单位万元'
+        if rng.random() < 0.5:
+            s['total'] = {'label': '合计'}
+        if rng.random() < 0.35:
+            s['group_by'] = 'region'
+        if rng.random() < 0.3 and mets:
+            s['chart'] = {'type': rng.choice(['bar', 'line']), 'cat': 'prov', 'values': ['m0']}
+        if rng.random() < 0.3 and mets:
+            s['conditional'] = [{'col': 'm0', 'type': rng.choice(['data_bar', 'color_scale'])}]
+        sheets.append(s)
+    spec = {'profile': prof, 'sheets': sheets}
+    if rng.random() < 0.4:
+        spec['cover'] = {'title': '压测报表', 'fields': [['编制单位', '压测'], ['口径', '含税']]}
+    return spec
+
+
+def forward(n, workdir, verbose=True):
+    rng = random.Random(20260901)
+    bad, worst = 0, []
+    for i in range(n):
+        spec = random_spec(rng)
+        out = os.path.join(workdir, f'f{i}.xlsx')
+        try:
+            _p, res, _w = B.build(spec, out)
+        except Exception as e:
+            bad += 1
+            worst.append((f'f{i}', f'生成异常 {type(e).__name__}: {e}'))
+            continue
+        errs = [x for x in res['issues'] if x['level'] == 'error']
+        if errs:
+            bad += 1
+            worst.append((f"f{i}({spec['profile']})",
+                          '; '.join(sorted({x['kind'] + ':' + x['msg'][:44] for x in errs}))))
+        os.remove(out)
+        if verbose and (i + 1) % 40 == 0:
+            print(f'  正向 {i+1}/{n} …')
+    return bad, worst
+
+
+# ── 反向：每条规则配一个「故意做坏」的工作簿 ───────────────────────────────
+def _base(workdir, name, rows=None, **kw):
+    spec = {'profile': 'report', 'inspect': False, 'sheets': [{
+        'name': '明细',
+        'columns': [{'key': 'prov', 'header': '省份'},
+                    {'key': 'amt', 'header': '销售额', 'format': 'amount'},
+                    {'key': 'qty', 'header': '数量', 'format': 'int'}],
+        'rows': rows or [[PROVS[i % len(PROVS)], round(1000 + i * 137.5, 2), i + 1] for i in range(24)],
+        **kw}]}
+    out = os.path.join(workdir, name)
+    B.build(spec, out)
+    return out
+
+
+def _kinds(path):
+    return {i['kind'] for i in C.inspect(path)['issues']}
+
+
+def reverse(workdir):
+    cases = []
+
+    def case(name, expect, mutate, **kw):
+        """造一份缺陷件并断言体检会响。
+
+        **先验证用例真的改到了文件**：openpyxl 有 ws.cell(r,c,None) 这种「看着在写、其实是
+        空操作」的陷阱，用例没造出缺陷却被报成「规则是瞎的」——两件事性质完全不同，
+        混在一起会让人去改本来没问题的检查规则。"""
+        p = _base(workdir, name + '.xlsx', **kw)
+        before = open(p, 'rb').read()
+        wb = load_workbook(p)
+        mutate(wb)
+        wb.save(p)
+        if open(p, 'rb').read() == before:
+            cases.append((name, expect, False, {'<用例没改到文件>'}))
+            return p
+        got = _kinds(p)
+        cases.append((name, expect, expect in got, got))
+        return p
+
+    def col(wb, letter, first=2, last=25):
+        return [wb['明细'][f'{letter}{r}'] for r in range(first, last + 1)]
+
+    # 数据类
+    case('数字存成文本', 'num-as-text',
+         lambda wb: [setattr(c, 'value', f'{c.value:,.2f}') for c in col(wb, 'B') if c.value is not None])
+    case('数字文本混杂', 'mixed-type',
+         lambda wb: [setattr(c, 'value', f'{c.value:,.2f}') for c in col(wb, 'B', 2, 12) if c.value is not None])
+    case('日期存成文本', 'date-as-text',
+         lambda wb: [setattr(c, 'value', f'2026-{(i % 12) + 1:02d}-01')
+                     for i, c in enumerate(col(wb, 'A'))])
+    case('首尾空格', 'whitespace',
+         lambda wb: [setattr(c, 'value', str(c.value) + ' ') for c in col(wb, 'A', 2, 8)])
+    case('完全重复行', 'dup-row',
+         lambda wb: [wb['明细'].cell(r, j, wb['明细'].cell(2, j).value)
+                     for r in (20, 21) for j in (1, 2, 3)])
+    case('编号列存成数字', 'id-as-number',
+         lambda wb: [wb['明细'].cell(1, 1, '客户编号')]
+                    + [setattr(c, 'value', 100000 + i) for i, c in enumerate(col(wb, 'A'))])
+
+    # 结构类
+    def merge_body(wb):
+        wb['明细'].merge_cells('A5:A8')
+    case('数据区合并单元格', 'merged-cells', merge_body)
+    case('隐藏行', 'hidden-row',
+         lambda wb: [wb['明细'].row_dimensions[r].__setattr__('hidden', True) for r in (5, 6, 7)])
+    case('隐藏列', 'hidden-col',
+         lambda wb: wb['明细'].column_dimensions['C'].__setattr__('hidden', True))
+    case('重名列', 'dup-header', lambda wb: wb['明细'].cell(1, 3, '销售额'))
+    # 注意：ws.cell(r,c,None) 是空操作（openpyxl 把 None 当「没传值」），必须显式赋 .value
+    case('空列名', 'blank-header', lambda wb: setattr(wb['明细'].cell(1, 3), 'value', None))
+    case('隐藏工作表', 'hidden-sheet',
+         lambda wb: (wb.create_sheet('偷偷藏的'), setattr(wb['偷偷藏的'], 'sheet_state', 'hidden')))
+    case('默认工作表名', 'default-name', lambda wb: wb.create_sheet('Sheet2'))
+    case('常量小计混在明细', 'subtotal-inline',
+         lambda wb: (wb['明细'].insert_rows(10),
+                     wb['明细'].cell(10, 1, '小计'), wb['明细'].cell(10, 2, 12345.0)))
+
+    # 公式类
+    case('错误值', 'error-value',
+         lambda wb: [wb['明细'].cell(r, 2, '#DIV/0!') for r in (4, 5)])
+    case('列内公式不一致', 'mixed-formula',
+         lambda wb: [wb['明细'].cell(r, 3, f'=B{r}/100') for r in range(2, 14)])
+    case('求和范围没覆盖末行', 'sum-short',
+         lambda wb: wb['明细'].cell(27, 2, '=SUM(B2:B10)'))
+    case('引用不存在的工作表', 'bad-sheet-ref',
+         lambda wb: wb['明细'].cell(27, 2, "='不存在的表'!B2"))
+    case('外部工作簿链接', 'external-link',
+         lambda wb: wb['明细'].cell(27, 2, "=[预算.xlsx]Sheet1!B2"))
+
+    # 勾稽类
+    def hardcode_total(wb):
+        ws = wb['明细']
+        ws.cell(26, 1, '合计')
+        ws.cell(26, 2, 99999.0)          # 写死且与明细对不上
+    case('合计写死成常量', 'hardcoded-total', hardcode_total)
+    case('合计对不上明细', 'total-mismatch', hardcode_total)
+    case('占比合计不等于100%', 'pct-sum',
+         lambda wb: [wb['明细'].cell(1, 3, '占比')]
+                    + [(setattr(wb['明细'].cell(r, 3), 'value', 0.04),
+                        setattr(wb['明细'].cell(r, 3), 'number_format', '0.0%'))
+                       for r in range(2, 26)])
+
+    # 单列清单**不是**表单：早先 max_col<=2 一并算表单，任何单列工作表都被整组跳过检查。
+    case('单列表里的超长单元格', 'long-cell',
+         lambda wb: (wb.create_sheet('清单'),
+                     wb['清单'].append(['说明']),
+                     [wb['清单'].append(['长' * 900]) for _ in range(3)]))
+
+    # 两列的数据表**不是**说明页——早先按列数判会把整组检查跳过，坏表反而查不出问题
+    def two_col_bad(wb):
+        wb.create_sheet('两列表')
+        ws = wb['两列表']
+        ws.append(['省份', '销售额'])
+        for i in range(20):
+            ws.append([f'省{i}', f'{1000 + i * 137.5:,.2f}'])
+        ws.append(['合计', 99999.0])
+    case('两列数据表也要查', 'hardcoded-total', two_col_bad)
+
+    # 呈现类
+    case('列宽不足显示井号', 'too-narrow',
+         lambda wb: wb['明细'].column_dimensions['B'].__setattr__('width', 5))
+    case('同列格式不统一', 'format-mix',
+         lambda wb: [setattr(c, 'number_format', '0') for c in col(wb, 'B', 2, 10)])
+    case('金额列无千分位', 'no-thousands',
+         lambda wb: [setattr(c, 'number_format', 'General') for c in col(wb, 'B')])
+    case('没有冻结窗格', 'no-freeze', lambda wb: setattr(wb['明细'], 'freeze_panes', None))
+
+    def wide_print(wb):
+        ws = wb['明细']
+        ws.sheet_properties.pageSetUpPr = None
+        ws.page_setup.fitToWidth = None
+        for j in range(1, 4):
+            ws.column_dimensions[get_column_letter(j)].width = 60
+    case('打印会横跨多页', 'print-wide', wide_print)
+    return cases
+
+
+# ── 反误报：正确做法**绝不能**被判成问题 ───────────────────────────────────
+def negative(workdir):
+    cases = []
+
+    def nocase(name, forbidden, spec):
+        out = os.path.join(workdir, 'neg-' + name + '.xlsx')
+        B.build(spec, out)
+        got = _kinds(out)
+        bad = [k for k in forbidden if k in got]
+        cases.append((name, not bad, bad, got))
+
+    # ── 旧版 .xls：读进来只有值，公式/列宽/合并全丢了 ──────────────────────
+    # 这些层必须**停掉**而不是照查：照查会凭空报出「合计是写死的常量」「缺冻结窗格」，
+    # 而报告看起来跟真的一样。真实归档里 .xls 占一半，这条错了会污染半数结论。
+    def legacy_guard():
+        out = os.path.join(workdir, 'neg-legacy.xlsx')
+        B.build({'profile': 'report', 'sheets': [{
+            'name': '明细',
+            'columns': [{'key': 'p', 'header': '省份'},
+                        {'key': 'a', 'header': '销售额', 'format': 'amount'}],
+            'rows': [[PROVS[i % len(PROVS)], round(100 + i * 7.5, 2)] for i in range(30)],
+            'total': {'label': '总计'}}]}, out)
+        real = C.Book(out)
+        real.legacy = True                       # 只翻这一个开关，其余完全相同
+        got = {i['kind'] for i in
+               (C.check_data(real) + C.check_structure(real) + C.check_reconcile(real))}
+        banned = {'hardcoded-total', 'no-freeze', 'too-narrow', 'no-autofilter'}
+        bad = sorted(got & banned)
+        cases.append(('旧格式不得凭空报公式/呈现类', not bad, bad, got))
+    legacy_guard()
+
+    rows = [[REGIONS[i // 4], PROVS[i % len(PROVS)], round(1000 + i * 97.3, 2), i + 1]
+            for i in range(24)]
+    cols = [{'key': 'region', 'header': '大区'}, {'key': 'prov', 'header': '省份'},
+            {'key': 'amt', 'header': '销售额', 'format': 'amount'},
+            {'key': 'qty', 'header': '数量', 'format': 'int'}]
+
+    nocase('分组小计用SUBTOTAL', ['subtotal-inline', 'mixed-formula', 'hardcoded-total', 'total-mismatch'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'columns': cols, 'rows': rows,
+                                             'group_by': 'region', 'total': {'label': '总计'}}]})
+    nocase('标题横幅在表头之上', ['header-not-first', 'merged-cells'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'title': '2026 年 8 月销售明细',
+                                             'note': '口径：含税，单位万元',
+                                             'columns': cols, 'rows': rows}]})
+    nocase('说明页两列表单', ['no-freeze', 'no-filter', 'print-wide', 'header-not-first', 'merged-cells'],
+           {'profile': 'report', 'cover': {'title': '报表说明', 'fields': [
+               ['编制单位', '数据一部'], ['口径', '含税'], ['来源', 'ERP']]},
+            'sheets': [{'name': '明细', 'columns': cols, 'rows': rows}]})
+    nocase('编号列锁成文本', ['id-as-number', 'num-as-text', 'mixed-type'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'columns': [
+               {'key': 'no', 'header': '订单编号', 'format': 'text'},
+               {'key': 'amt', 'header': '销售额', 'format': 'amount'}],
+               'rows': [[f'{i:08d}', round(1000 + i * 13.5, 2)] for i in range(24)]}]})
+    # 建表引擎按列格式写类型（date 列写真日期、amount 列的「1,234.56」写成数字）。
+    # 写错方向会静默毁数据：把订单号转成数字，前导零当场消失。这两条守着那个转换。
+    nocase('编号列写文本不被转数字', ['num-as-text', 'id-as-number', 'mixed-type'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'columns': [
+               {'key': 'no', 'header': '订单编号', 'format': 'text'},
+               {'key': 'amt', 'header': '销售额', 'format': 'amount'}],
+               'rows': [[f'{i:05d}', f'{1000 + i * 11.5:,.2f}'] for i in range(1, 25)]}]})
+    nocase('日期列写成真日期', ['date-as-text', 'mixed-type'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'columns': [
+               {'key': 'd', 'header': '记账日期', 'format': 'date'},
+               {'key': 'amt', 'header': '金额', 'format': 'amount'}],
+               'rows': [[f'2026-{i % 12 + 1:02d}-0{i % 9 + 1}', 1000.0 + i] for i in range(1, 25)]}]})
+    nocase('短表不必冻结', ['no-freeze', 'no-filter'],
+           {'profile': 'report', 'sheets': [{'name': '小表', 'columns': cols, 'rows': rows[:6]}]})
+    nocase('大额金额列宽度够', ['too-narrow'],
+           {'profile': 'report', 'sheets': [{'name': '明细', 'columns': [
+               {'key': 'p', 'header': '省份'}, {'key': 'a', 'header': '销售额', 'format': 'amount'}],
+               'rows': [[PROVS[i % 10], round(1234567890.12 + i, 2)] for i in range(24)]}]})
+    return cases
+
+
+# ── 校正闭环 ───────────────────────────────────────────────────────────────
+FIXABLE = ['数字存成文本', '首尾空格', '数据区合并单元格', '求和范围没覆盖末行',
+           '合计写死成常量', '合计对不上明细', '列宽不足显示井号', '同列格式不统一',
+           '金额列无千分位', '没有冻结窗格', '打印会横跨多页', '编号列存成数字']
+
+
+def fix_round(workdir, cases):
+    out = []
+    for name, expect, hit, _got in cases:
+        if name not in FIXABLE or not hit:
+            continue
+        src = os.path.join(workdir, name + '.xlsx')
+        try:
+            dst, done = C.fix(src, os.path.join(workdir, name + '-fixed.xlsx'))
+        except Exception as e:
+            out.append((name, False, f'修复异常 {type(e).__name__}: {e}'))
+            continue
+        after, before = C.inspect(dst), C.inspect(src)
+        kinds = {i['kind'] for i in after['issues']}
+        new_err = ({i['kind'] for i in after['issues'] if i['level'] == 'error'}
+                   - {i['kind'] for i in before['issues'] if i['level'] == 'error'})
+        ok = expect not in kinds and not new_err
+        why = (f'修完仍命中 {expect}' if expect in kinds else
+               (f'修出新必修 {sorted(new_err)}' if new_err else
+                '已修（' + '、'.join(f'{k}{v}' for k, v in done.items()) + '）'))
+        out.append((name, ok, why))
+    return out
+
+
+def main(argv):
+    n = 120
+    for a in argv:
+        if a.isdigit():
+            n = int(a)
+    keep = '--keep' in argv
+    workdir = os.path.join(os.getcwd(), '_xbattery') if keep else tempfile.mkdtemp(prefix='xlsxbat-')
+    os.makedirs(workdir, exist_ok=True)
+    print(f'压测目录：{workdir}')
+    fails = 0
+
+    print(f'\n[1/4] 正向：随机内容 × 三档规范 × {n} 份，断言合规报表零必修')
+    bad, worst = forward(n, workdir)
+    if bad:
+        fails += 1
+        print(f'  ✗ {bad}/{n} 份出现必修项：')
+        for name, why in worst[:8]:
+            print(f'      {name} → {why}')
+    else:
+        print(f'  ✓ {n} 份全部零必修')
+
+    print('\n[2/4] 反向：每条规则配一个故意做坏的工作簿，断言体检真的会响')
+    cases = reverse(workdir)
+    miss = [c for c in cases if not c[2]]
+    for name, expect, hit, got in cases:
+        print(f"  {'✓' if hit else '✗'} {name:<18} 期望 {expect}"
+              + ('' if hit else f"　实际命中：{sorted(got)[:7]}"))
+    if miss:
+        fails += 1
+        print(f'  ✗ {len(miss)}/{len(cases)} 条规则是瞎的')
+    else:
+        print(f'  ✓ {len(cases)}/{len(cases)} 条规则全部命中')
+
+    print('\n[3/4] 反误报：正确做法不得被判成问题')
+    negs = negative(workdir)
+    for name, ok, bad2, _got in negs:
+        print(f"  {'✓' if ok else '✗'} {name:<18}" + ('' if ok else f'　被误报：{bad2}'))
+    if any(not ok for _n, ok, _b, _g in negs):
+        fails += 1
+    else:
+        print(f'  ✓ {len(negs)}/{len(negs)} 项正确做法零误报')
+
+    print('\n[4/4] 校正闭环：fix 后必须真干净，且不得修出新必修')
+    fr = fix_round(workdir, cases)
+    for name, ok, why in fr:
+        print(f"  {'✓' if ok else '✗'} {name:<18} {why}")
+    if any(not ok for _n, ok, _w in fr):
+        fails += 1
+
+    if not keep:
+        shutil.rmtree(workdir, ignore_errors=True)
+    print('\n' + ('全部通过。' if not fails else f'有 {fails} 个环节未通过。'))
+    return 1 if fails else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))