@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,924 @@
+# Excel 工作簿体检与自动校正。
+#
+# 定位：Excel 的事故与 Word/PPT 都不同——它**不改变外观，只改变数字**。
+# 金额存成文本，SUM 得 0；合计行是上周算好的常量，改了明细它纹丝不动；
+# SUM(B2:B100) 但数据长到了 B180，少算 80 行；合并单元格一排序整张表错位；
+# 明细里混着「合计」行，一汇总就翻倍。这些全都不报错、不变色、不出框——
+# 它们只是安静地给出一个错的数，而错的数和对的数长得一模一样。
+#
+# 所以本模块查六类：数据 / 结构 / 公式 / 勾稽 / 呈现 / 元信息。
+# 其中「公式」与「勾稽」两类是 Excel 独有的、也是最值钱的——别的工具基本不查。
+#
+# fix=true 只修**可确定性修**的那几类，且一律另存 `-已校正.xlsx` 不覆盖原件。
+
+import json
+import os
+import re
+import sys
+from collections import Counter, defaultdict
+
+from openpyxl import load_workbook
+from openpyxl.styles import Alignment, Font
+from openpyxl.utils import get_column_letter
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import xlsx_layout as L          # noqa: E402
+
+SUBTOTAL_MARKS = ('合计', '小计', '总计', '合 计', '小 计', '总 计', '本页合计', '累计',
+                  'total', 'subtotal', '汇总')
+INVISIBLE = '\xa0　​\t\r\n'
+NUM_TEXT_RE = re.compile(r'^\s*[（(]?\s*[-+]?[¥￥$]?\s*\d[\d,，]*(\.\d+)?\s*[%元]?\s*[)）]?\s*$')
+DATE_TEXT_RE = re.compile(r'^\s*\d{4}[-/.年]\d{1,2}([-/.月]\d{1,2}日?)?\s*$')
+ID_HINTS = ('编码', '编号', '代码', '卡号', '工号', '身份证', '邮编', '单号', 'id', 'code', 'no')
+SUM_RE = re.compile(r'\b(SUM|SUBTOTAL)\s*\(\s*(?:9\s*,\s*|109\s*,\s*)?\$?([A-Z]{1,3})\$?(\d+)\s*:\s*\$?([A-Z]{1,3})\$?(\d+)\s*\)', re.I)
+SHEET_REF_RE = re.compile(r"(?:'([^']+)'|([A-Za-z0-9_一-鿿]+))!\$?[A-Z]{1,3}\$?\d+")
+
+
+# 工作表「类型」识别：体检必须先分清自己在看什么，否则会对**完全合规的报表**喊狼来了——
+# 说明页当然没有筛选、标题横幅当然在表头上面、分组小计当然是公式而明细是常量。
+# 与 docx_check 的段落角色识别是同一件事：一个天天误报的体检器，用两次就没人看了。
+def _sheet_kind(s):
+    """table 数据表 / form 说明页与表单（键值两列）/ blank 空表 / other 说不清就少判。
+
+    **不能只按列数判**：「省份 + 销售额」两列二十行是标准的数据表，不是说明页。
+    真正的分界是第二列有没有度量——说明页那一列是「数据一部」「含税」这类文字，
+    数据表那一列是数字（哪怕被存成了文本，也仍然是度量）。
+    早先只数列数，结果两列的数据表被整组跳过检查，坏表反而查不出问题。"""
+    if not s['max_row'] or not s['max_col']:
+        return 'blank'
+    # 表单是**键→值两列**。单列表是清单，不是表单——早先把 max_col<=2 一并算作表单，
+    # 结果任何单列工作表都被整组跳过检查，等于有一整类表从来没被查过。
+    if s['max_col'] == 2 and s['max_row'] <= 40 and not _has_measure(s):
+        return 'form'
+    if s['header_row'] and s['max_row'] - s['first_data'] + 1 >= 2:
+        return 'table'
+    return 'other'
+
+
+def _has_measure(s):
+    """最后一列是不是度量列（数字，或看起来是数字的文本）。"""
+    ws, j = s['ws'], s['max_col']
+    vals = [ws.cell(r, j).value for r in range(max(s['first_data'], 2), s['max_row'] + 1)]
+    vals = [v for v in vals if v is not None and str(v).strip() != '']
+    if len(vals) < 3:
+        return False
+    hit = sum(1 for v in vals
+              if (isinstance(v, (int, float)) and not isinstance(v, bool))
+              or (isinstance(v, str) and NUM_TEXT_RE.match(v)))
+    return hit >= len(vals) * 0.6
+
+
+def _is_title_banner(s):
+    """表头之上那几行是不是「刻意的标题横幅」。是 → 表头不在首行属正常排版，不该报。
+
+    判据：行数不多（≤3），且每一行要么整行为空，要么只有第一格有内容/跨列合并——
+    这正是「标题 + 口径说明 + 空行」的样子。反过来，上面塞着半张残表就不是横幅。"""
+    h = s['header_row']
+    if not h or h > 4:
+        return False
+    ws = s['ws']
+    for r in range(1, h):
+        vals = [ws.cell(r, j).value for j in range(1, s['max_col'] + 1)]
+        nonnull = [j for j, v in enumerate(vals, 1) if v is not None and str(v).strip() != '']
+        if not nonnull:
+            continue
+        if nonnull != [1]:
+            merged_full = any(re.match(rf'A{r}:[A-Z]+{r}$', m) for m in s['merges'])
+            if not merged_full:
+                return False
+    return True
+
+
+def _subtotal_cells_are_formulas(s, rows):
+    """分组小计行里的数值格是不是都用了 SUBTOTAL——是的话这是**正确构造**，不是隐患。"""
+    ws, seen = s['ws'], False
+    for r in rows:
+        for j in range(1, s['max_col'] + 1):
+            v = ws.cell(r, j).value
+            if _num(v) is not None and not _is_formula(v):
+                return False
+            if _is_formula(v):
+                seen = True
+                if 'SUBTOTAL' not in str(v).upper():
+                    return False
+    return seen
+
+
+def _issue(level, group, kind, where, msg, detail='', fixable=False):
+    return {'level': level, 'group': group, 'kind': kind, 'where': where,
+            'msg': msg, 'detail': detail, 'fixable': fixable}
+
+
+def _is_formula(v):
+    return isinstance(v, str) and v.startswith('=')
+
+
+def _is_err(v):
+    return isinstance(v, str) and v.strip().upper() in L.ERR_VALUES
+
+
+def _num(v):
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    return None
+
+
+def _num_loose(v):
+    """数字，或「看着像数字的文本」（1,200.00 / （1234） / ¥500）。勾稽判定用它。"""
+    n = _num(v)
+    if n is not None:
+        return n
+    if isinstance(v, str) and NUM_TEXT_RE.match(v):
+        s = v.strip()
+        neg = s.startswith(('(', '（')) and s.endswith((')', '）'))
+        t = re.sub(r'[（()）,，¥￥$元\s%]', '', s)
+        try:
+            x = float(t)
+        except ValueError:
+            return None
+        return -abs(x) if neg else x
+    return None
+
+
+def _from_legacy(path):
+    """把旧版 .xls 的**值**搬进一个内存 openpyxl 工作簿，只为数据层检查服务。
+    搬不动的（公式、列宽、合并、冻结、打印）在调用处被明确停掉，不做猜测。"""
+    import pandas as pd
+    from openpyxl import Workbook
+    sheets = pd.read_excel(path, sheet_name=None, header=None, dtype=object)
+    wb = Workbook()
+    wb.remove(wb.active)
+    for name, df in sheets.items():
+        ws = wb.create_sheet(str(name)[:31] or 'Sheet1')
+        for row in df.itertuples(index=False, name=None):
+            ws.append([None if pd.isna(v) else v for v in row])
+    if not wb.sheetnames:
+        wb.create_sheet('Sheet1')
+    return wb
+
+
+class Book:
+    """解析后的工作簿模型：每张表的数据区、表头行、列画像、公式画像。"""
+
+    def __init__(self, path, profile_name='auto'):
+        self.path = path
+        self.legacy = False
+        try:
+            self.wb = load_workbook(path, data_only=False)
+        except Exception:
+            # 旧版 .xls：openpyxl 读不了。真实归档里这类占一半（评审报告、预算表全是 .xls），
+            # 直接抛异常等于半数交付件根本没法体检。用 pandas/xlrd 把**值**搬进内存工作簿，
+            # 数据层照查；公式、列宽、合并、打印设置在这一步全丢了，
+            # 所以呈现层与公式层必须停掉——照查会凭空报出「合计是写死的常量」「缺冻结窗格」，
+            # 那是编造出来的结论，比读不了更糟。
+            self.wb = _from_legacy(path)
+            self.legacy = True
+        self.wbv = self.wb if self.legacy else None
+        if not self.legacy:
+            try:
+                self.wbv = load_workbook(path, data_only=True)
+            except Exception:
+                self.wbv = None
+        self.sheets = [self._sheet(ws) for ws in self.wb.worksheets]
+        self.profile = L.profile(self._detect(profile_name))
+
+    def _detect(self, name):
+        if name and name != 'auto':
+            return name
+        for s in self.sheets:
+            if any('(' in str(c.get('format') or '') for c in s['cols']):
+                return 'finance'
+        return 'report'
+
+    def _sheet(self, ws):
+        wsv = self.wbv[ws.title] if self.wbv is not None and ws.title in self.wbv.sheetnames else None
+        max_r, max_c = self._extent(ws)
+        head = self._header_row(ws, max_r, max_c)
+        s = {'name': ws.title, 'ws': ws, 'wsv': wsv, 'max_row': max_r, 'max_col': max_c,
+             'header_row': head, 'first_data': head + 1 if head else 1,
+             'hidden': ws.sheet_state != 'visible',
+             'freeze': ws.freeze_panes, 'autofilter': ws.auto_filter.ref,
+             'print_titles': ws.print_title_rows,
+             'fit_width': bool(getattr(ws.page_setup, 'fitToWidth', None)),
+             'landscape': str(getattr(ws.page_setup, 'orientation', '')) == 'landscape',
+             'merges': [str(m) for m in ws.merged_cells.ranges],
+             'charts': len(getattr(ws, '_charts', []) or []),
+             'cols': [], 'formulas': 0, 'errors': [], 'subtotal_rows': [], 'total_rows': []}
+        if not max_r or not max_c:
+            return s
+        s['cols'] = [self._col(ws, wsv, j, s) for j in range(1, max_c + 1)]
+        s['formulas'] = sum(c['n_formula'] for c in s['cols'])
+        for c in s['cols']:
+            s['errors'].extend(c['errors'])
+        s['subtotal_rows'] = self._subtotal_rows(ws, s)
+        s['hidden_rows'] = [r for r in range(1, max_r + 1)
+                            if ws.row_dimensions[r].hidden]
+        s['hidden_cols'] = [get_column_letter(j) for j in range(1, max_c + 1)
+                            if ws.column_dimensions[get_column_letter(j)].hidden]
+        s['kind'] = _sheet_kind(s)
+        s['banner'] = _is_title_banner(s)
+        return s
+
+    @staticmethod
+    def _extent(ws):
+        """真实数据范围：openpyxl 的 max_row/max_column 会被「只设过格式的空单元格」撑虚。"""
+        max_r = max_c = 0
+        for row in ws.iter_rows():
+            for cell in row:
+                if cell.value is not None and str(cell.value).strip() != '':
+                    if cell.row > max_r:
+                        max_r = cell.row
+                    if cell.column > max_c:
+                        max_c = cell.column
+        return max_r, max_c
+
+    @staticmethod
+    def _header_row(ws, max_r, max_c, scan=12):
+        """找表头行：文字格最密、且下一行开始出现数值的那一行。找不到返回 0（无表头结构）。"""
+        best, best_score = 0, 0.0
+        for r in range(1, min(scan, max_r) + 1):
+            vals = [ws.cell(r, j).value for j in range(1, max_c + 1)]
+            nonnull = [v for v in vals if v is not None and str(v).strip() != '']
+            if not nonnull:
+                continue
+            strs = [v for v in nonnull if isinstance(v, str) and not NUM_TEXT_RE.match(v)]
+            cover = len(nonnull) / max(1, max_c)
+            txt = len(strs) / max(1, len(nonnull))
+            nxt = [ws.cell(r + 1, j).value for j in range(1, max_c + 1)] if r < max_r else []
+            has_num = any(isinstance(v, (int, float)) and not isinstance(v, bool) for v in nxt)
+            score = cover * 1.0 + txt * 1.2 + (0.8 if has_num else 0)
+            if score > best_score and cover >= 0.5 and txt >= 0.6:
+                best, best_score = r, score
+        return best
+
+    def _col(self, ws, wsv, j, s):
+        letter = get_column_letter(j)
+        header = ws.cell(s['header_row'], j).value if s['header_row'] else None
+        vals, kinds, errors = [], Counter(), []
+        n_formula = 0
+        formulas = []
+        for r in range(s['first_data'], s['max_row'] + 1):
+            cell = ws.cell(r, j)
+            v = cell.value
+            if _is_formula(v):
+                n_formula += 1
+                formulas.append((r, v))
+                vv = wsv.cell(r, j).value if wsv is not None else None
+                if _is_err(vv):
+                    errors.append((r, str(vv)))
+                    kinds['error'] += 1
+                elif vv is not None:
+                    vals.append(vv)
+                    kinds['number' if _num(vv) is not None else 'text'] += 1
+                continue
+            if v is None or (isinstance(v, str) and v.strip() == ''):
+                kinds['blank'] += 1
+                continue
+            if _is_err(v):
+                errors.append((r, str(v)))
+                kinds['error'] += 1
+                continue
+            vals.append(v)
+            if _num(v) is not None:
+                kinds['number'] += 1
+            elif isinstance(v, str):
+                kinds['num-text' if NUM_TEXT_RE.match(v) else
+                      ('date-text' if DATE_TEXT_RE.match(v) else 'text')] += 1
+            else:
+                kinds['date' if hasattr(v, 'year') else 'other'] += 1
+        fmts = Counter(ws.cell(r, j).number_format
+                       for r in range(s['first_data'], min(s['max_row'], s['first_data'] + 400) + 1)
+                       if ws.cell(r, j).value is not None)
+        width = ws.column_dimensions[letter].width
+        return {'j': j, 'letter': letter, 'header': header, 'vals': vals[:2000], 'kinds': kinds,
+                'n_formula': n_formula, 'formulas': formulas, 'errors': errors,
+                'formats': fmts, 'format': fmts.most_common(1)[0][0] if fmts else 'General',
+                'width': width, 'width_set': width is not None}
+
+    @staticmethod
+    def _subtotal_rows(ws, s):
+        out = []
+        for r in range(s['first_data'], s['max_row'] + 1):
+            for j in range(1, min(s['max_col'], 4) + 1):
+                v = ws.cell(r, j).value
+                if isinstance(v, str):
+                    t = v.strip().lower()
+                    if t and len(t) <= 12 and any(k in t for k in SUBTOTAL_MARKS):
+                        out.append(r)
+                        break
+        return out
+
+
+# ── 检查族 ─────────────────────────────────────────────────────────────────
+def check_data(B):
+    out = []
+    for s in B.sheets:
+        w = s['name']
+        if not s['max_row']:
+            out.append(_issue('warn', 'data', 'empty-sheet', w, '空工作表', '', fixable=False))
+            continue
+        for c in s['cols']:
+            k, head = c['kinds'], str(c['header'] or c['letter'])
+            n = sum(k.values()) - k['blank']
+            if n <= 0:
+                continue
+            # ① 数字存成文本：SUM 会得 0，是「对账对不平」的头号原因
+            if k['num-text'] >= max(3, n * 0.6) and not any(h in head.lower() for h in ID_HINTS):
+                out.append(_issue('error', 'data', 'num-as-text', f'{w}!{c["letter"]}',
+                                  f'「{head}」列的数值被存成文本（{k["num-text"]}/{n} 格）',
+                                  'Excel 里 SUM 会跳过文本，结果得 0 或偏小', fixable=True))
+            # ② 一列里数字与文本混：排序、筛选、比较全都会出鬼
+            elif k['number'] and k['num-text'] and 0.1 < k['num-text'] / n < 0.9:
+                out.append(_issue('warn', 'data', 'mixed-type', f'{w}!{c["letter"]}',
+                                  f'「{head}」列数字与文本混杂（{k["number"]} 数字 / {k["num-text"]} 文本）',
+                                  '排序会把文本排到数字后面，比较大小也不对', fixable=True))
+            if k['date-text'] >= max(3, n * 0.6):
+                out.append(_issue('warn', 'data', 'date-as-text', f'{w}!{c["letter"]}',
+                                  f'「{head}」列的日期被存成文本（{k["date-text"]}/{n} 格）',
+                                  '不能参与日期计算，按月分组要先转换'))
+            # ③ 编号列被存成数字：前导零没了、18 位变科学计数法
+            if any(h in head.lower() for h in ID_HINTS) and k['number'] >= max(3, n * 0.8):
+                mx = max((abs(float(v)) for v in c['vals'] if _num(v) is not None), default=0)
+                out.append(_issue('error' if mx >= 1e15 else 'warn', 'data', 'id-as-number',
+                                  f'{w}!{c["letter"]}', f'「{head}」是编号列却存成了数字',
+                                  ('已超 15 位，末位精度已丢失——只能让对方按文本重新导出，'
+                                   '这一步任何工具都救不回来'
+                                   if mx >= 1e15 else '前导零会消失，长号会显示成科学计数法'),
+                                  fixable=mx < 1e15))
+            # ④ 首尾空白与不可见字符：分组会分成两组
+            dirty = sum(1 for v in c['vals'] if isinstance(v, str)
+                        and (v != v.strip() or any(ch in v for ch in INVISIBLE)))
+            if dirty:
+                out.append(_issue('warn', 'data', 'whitespace', f'{w}!{c["letter"]}',
+                                  f'「{head}」列有 {dirty} 格带首尾空白或不可见字符',
+                                  '「北京 」与「北京」会被当成两个值', fixable=True))
+        # ⑤ 超长单元格（放在数据类而不是呈现类：这是内容问题，
+        #    而呈现类只对被判为「数据表」的 sheet 跑，单列清单那种会被整组跳过）
+        longest, where = 0, ''
+        for c in s['cols']:
+            for v in c['vals']:
+                if isinstance(v, str) and len(v) > longest:
+                    longest, where = len(v), c['letter']
+        if longest > 200:
+            out.append(_issue('info', 'data', 'long-cell', f'{w}!{where}',
+                              f'最长单元格 {longest} 字',
+                              '一格几千字会把整行撑得极高；长文本应放正文或另附说明'))
+        # ⑥ 完全重复行
+        if s['header_row'] and s['max_row'] - s['first_data'] >= 2:
+            seen, dup = set(), 0
+            for r in range(s['first_data'], s['max_row'] + 1):
+                key = tuple(s['ws'].cell(r, j).value for j in range(1, s['max_col'] + 1))
+                if all(v is None for v in key):
+                    continue
+                if key in seen:
+                    dup += 1
+                seen.add(key)
+            if dup:
+                out.append(_issue('warn', 'data', 'dup-row', w,
+                                  f'{dup} 行完全重复', '确认是真实业务重复还是导出重复；汇总前要不要去重'))
+    return out
+
+
+def check_structure(B):
+    out = []
+    for s in B.sheets:
+        w = s['name']
+        if not s['max_row'] or s['kind'] in ('blank', 'form'):
+            continue                       # 说明页/表单没有「数据区」这回事，那套判据不适用
+        # 合并单元格：只有落在**数据区**里的才是问题；表格上方的标题横幅是正常排版
+        bad_merges = []
+        for m in s['merges']:
+            mm = re.match(r'([A-Z]+)(\d+):([A-Z]+)(\d+)', m)
+            if not mm:
+                continue
+            r1, r2 = int(mm.group(2)), int(mm.group(4))
+            if r2 >= s['first_data'] and s['header_row']:
+                bad_merges.append(m)
+        if bad_merges:
+            out.append(_issue('error', 'structure', 'merged-cells', w,
+                              f'数据区内有 {len(bad_merges)} 处合并单元格：{bad_merges[:5]}',
+                              '排序会报错、筛选会漏行、透视表读不到——合并只该出现在表格上方的标题',
+                              fixable=True))
+        if s['header_row'] > 1 and not s['banner']:
+            out.append(_issue('info', 'structure', 'header-not-first', w,
+                              f'表头在第 {s["header_row"]} 行而不是第 1 行',
+                              '别人用 pandas 读会拿到一排 Unnamed 列——除非上方是刻意的标题行'))
+        if not s['header_row']:
+            out.append(_issue('warn', 'structure', 'no-header', w, '识别不出表头行',
+                              '整表可能没有列名，或首行就是数据'))
+        if s.get('hidden_rows'):
+            out.append(_issue('warn', 'structure', 'hidden-row', w,
+                              f'{len(s["hidden_rows"])} 行被隐藏（行号 {s["hidden_rows"][:6]}）',
+                              '隐藏行仍会被 SUM 计入、却不会被人看见，是对不上账时最难找的原因'))
+        if s.get('hidden_cols'):
+            out.append(_issue('warn', 'structure', 'hidden-col', w,
+                              f'列 {s["hidden_cols"][:6]} 被隐藏', ''))
+        # 合计行混在明细中：一汇总就双计
+        mid = [r for r in s['subtotal_rows'] if r < s['max_row']]
+        if mid:
+            tail_only = all(r >= s['max_row'] - 1 for r in s['subtotal_rows'])
+            # 小计行全部用 SUBTOTAL(9,…) 写成公式 = 规范的分组报表构造：
+            # SUBTOTAL 自己会忽略嵌套的 SUBTOTAL，总计不会把小计再加一遍。这种不该报。
+            if not tail_only and not _subtotal_cells_are_formulas(s, mid):
+                out.append(_issue('warn', 'structure', 'subtotal-inline', w,
+                                  f'{len(mid)} 行「合计/小计」混在明细中（行 {mid[:6]}）',
+                                  '别人拿去做透视或求和会翻倍；分组小计是可以的，但要让下游知道'))
+        # 列名问题
+        if s['header_row']:
+            heads = [str(c['header']) if c['header'] is not None else '' for c in s['cols']]
+            blank = [c['letter'] for c, h in zip(s['cols'], heads) if not h.strip()]
+            if blank:
+                out.append(_issue('warn', 'structure', 'blank-header', w,
+                                  f'{len(blank)} 列没有列名：{blank[:6]}', ''))
+            dup = [h for h, n in Counter(h for h in heads if h.strip()).items() if n > 1]
+            if dup:
+                out.append(_issue('error', 'structure', 'dup-header', w,
+                                  f'重名列：{dup[:5]}', 'pandas 读取时取列会拿到 DataFrame 而不是 Series'))
+    names = [s['name'] for s in B.sheets]
+    default = [n for n in names if re.fullmatch(r'(Sheet|sheet|工作表)\d*', n)]
+    if default:
+        out.append(_issue('info', 'meta', 'default-name', '工作簿',
+                          f'{len(default)} 张表还是默认名：{default[:4]}',
+                          '交付件里的 Sheet1 很扎眼；但改名会断掉其它公式的跨表引用，改前先查引用'))
+    hid = [s['name'] for s in B.sheets if s['hidden']]
+    if hid:
+        out.append(_issue('warn', 'meta', 'hidden-sheet', '工作簿',
+                          f'隐藏工作表：{hid}', '收件人可能根本不知道这些表存在'))
+    return out
+
+
+def check_formula(B):
+    """Excel 独有、也最值钱的一类：公式看着对，算出来的范围却不对。"""
+    out = []
+    for s in B.sheets:
+        w = s['name']
+        for c in s['cols']:
+            if c['errors']:
+                kinds = Counter(e[1] for e in c['errors'])
+                out.append(_issue('error', 'formula', 'error-value', f'{w}!{c["letter"]}',
+                                  f'{len(c["errors"])} 个错误值：{dict(kinds)}',
+                                  f'首个在第 {c["errors"][0][0]} 行——交付前必须清零'))
+            # 列内公式不一致：一列里有的是公式有的是手打的数，最容易被改坏。
+            # **小计/合计行必须排除**——「明细是常量、小计是公式」正是正确构造，
+            # 不排除就会对每一张分组报表都报一次，那是纯噪声。
+            body_f = sum(1 for r, _f in c['formulas'] if r not in s['subtotal_rows'])
+            n_val = c['kinds']['number'] + c['kinds']['num-text']
+            if body_f and n_val and 0.1 < body_f / (body_f + n_val) < 0.9:
+                out.append(_issue('warn', 'formula', 'mixed-formula', f'{w}!{c["letter"]}',
+                                  f'「{c["header"] or c["letter"]}」列 {body_f} 格是公式、'
+                                  f'{n_val} 格是手打的常量',
+                                  '手打的那几格不会随源数据更新，是最隐蔽的过期数据'))
+            # SUM 范围没覆盖到数据末行：少算了后面新增的行
+            for r, f in c['formulas'][:200]:
+                for m in SUM_RE.finditer(f):
+                    c1, r1, c2, r2 = m.group(2), int(m.group(3)), m.group(4), int(m.group(5))
+                    if c1 != c2:
+                        continue
+                    jj = L.col_index(c1)
+                    if not (1 <= jj <= s['max_col']):
+                        continue
+                    last = _last_value_row(s, jj, r1, r)
+                    if last and r2 < last:
+                        out.append(_issue('error', 'formula', 'sum-short', f'{w}!{c["letter"]}{r}',
+                                          f'求和范围只到第 {r2} 行，但该列数据到第 {last} 行',
+                                          f'{f[:48]} —— 少算了 {last - r2} 行', fixable=True))
+            for r, f in c['formulas'][:200]:
+                if '[' in f and ']' in f:
+                    out.append(_issue('warn', 'formula', 'external-link', f'{w}!{c["letter"]}{r}',
+                                      '公式引用了外部工作簿', f[:60] + '——对方打开时会提示更新链接、或直接断链'))
+                    break
+            vol = [v for v in L.VOLATILE if any(v in f for _r, f in c['formulas'][:200])]
+            if vol and c['n_formula'] > 20:
+                out.append(_issue('info', 'formula', 'volatile', f'{w}!{c["letter"]}',
+                                  f'大量使用易失函数 {vol}', '每次改任何单元格都会全表重算，大表会卡'))
+        # 跨表引用指向不存在的工作表
+        names = {x['name'] for x in B.sheets}
+        for c in s['cols']:
+            for r, f in c['formulas'][:200]:
+                for m in SHEET_REF_RE.finditer(f):
+                    ref = m.group(1) or m.group(2)
+                    if ref and ref not in names and not ref.upper() in ('IF', 'SUM'):
+                        out.append(_issue('error', 'formula', 'bad-sheet-ref', f'{w}!{c["letter"]}{r}',
+                                          f'公式引用了不存在的工作表「{ref}」', f[:60]))
+                        break
+    return out
+
+
+def _last_value_row(s, j, from_row, before_row):
+    last = 0
+    for r in range(max(from_row, 1), min(before_row, s['max_row'] + 1)):
+        v = s['ws'].cell(r, j).value
+        if v is not None and str(v).strip() != '' and not (
+                isinstance(v, str) and any(k in v.lower() for k in SUBTOTAL_MARKS)):
+            last = r
+    return last
+
+
+def check_reconcile(B):
+    """勾稽：合计对不对得上明细。**这是 Excel 交付件最值钱的一条检查**——
+    硬编码的合计不会报错，只会安静地过期。"""
+    out = []
+    for s in B.sheets:
+        if not s['header_row'] or not s['subtotal_rows']:
+            continue
+        w = s['name']
+        tail = [r for r in s['subtotal_rows'] if r >= s['max_row'] - 1]
+        for tr in (tail or s['subtotal_rows'][-1:]):
+            for c in s['cols']:
+                cell = s['ws'].cell(tr, c['j'])
+                v = cell.value
+                if v is None:
+                    continue
+                # 明细可能是「看着像数字的文本」——那恰恰是最该报的场景：
+                # 金额存成文本 + 合计写死，两个毛病叠在一起，SUM 得 0 而合计看着还挺像。
+                detail = [_num_loose(s['ws'].cell(r, c['j']).value)
+                          for r in range(s['first_data'], tr)
+                          if r not in s['subtotal_rows']]
+                detail = [x for x in detail if x is not None]
+                if len(detail) < 2:
+                    continue
+                if _is_formula(v):
+                    continue                       # 公式合计天然跟着明细走，不必对
+                got = _num_loose(v)
+                if got is None:
+                    continue
+                # 旧版 .xls 走的是「值搬运」路径，公式在读入那一刻就没了——
+                # 此时每个合计都会长得像常量。照报等于编造：原件很可能本来就是 SUM。
+                # 「合计对不上明细」不受影响（按值算），继续报。
+                if not B.legacy:
+                    out.append(_issue('error', 'reconcile', 'hardcoded-total',
+                                      f'{w}!{c["letter"]}{tr}',
+                                      f'「{c["header"] or c["letter"]}」的合计是写死的常量，不是公式',
+                                      f'当前值 {got:,.2f}；改任何一行明细它都不会变', fixable=True))
+                want = sum(detail)
+                if abs(got - want) > max(0.01, abs(want) * 1e-6):
+                    out.append(_issue('error', 'reconcile', 'total-mismatch',
+                                      f'{w}!{c["letter"]}{tr}',
+                                      f'合计对不上明细：合计 {got:,.2f}，明细之和 {want:,.2f}'
+                                      f'（差 {got - want:,.2f}）',
+                                      '多半是明细改过而合计没跟着改', fixable=True))
+        pass
+    for s in B.sheets:
+        if not s['header_row'] or s['kind'] != 'table':
+            continue
+        w = s['name']
+        # 百分比列合计 ≈ 100%。**不依赖有没有小计行**——占比列自己就该加得起来，
+        # 早先把这条塞进小计循环里，没有合计行的表就一次也查不到。
+        for c in s['cols']:
+            if '%' not in str(c['format']):
+                continue
+            vals = [_num(x) for x in c['vals']]
+            vals = [x for x in vals if x is not None]
+            if len(vals) >= 3 and 0.9 < sum(vals) < 1.1 and abs(sum(vals) - 1.0) > 0.005:
+                out.append(_issue('warn', 'reconcile', 'pct-sum', f'{w}!{c["letter"]}',
+                                  f'占比列合计 {sum(vals)*100:.2f}%，不等于 100%',
+                                  '四舍五入误差要在末位调平，或注明「因四舍五入合计可能不为 100%」'))
+    return out
+
+
+def check_present(B):
+    out = []
+    prof = B.profile
+    for s in B.sheets:
+        if not s['max_row'] or not s['header_row'] or s['kind'] != 'table':
+            continue                       # 说明页不需要冻结/筛选/打印一页宽
+        w = s['name']
+        widths = []
+        for c in s['cols']:
+            width = c['width'] or 8.43
+            widths.append(width)
+            nums = [_num_loose(v) for v in c['vals']]
+            nums = [v for v in nums if v is not None]
+            if not nums:
+                continue
+            need = L.width_needed(nums, c['header'], c['format'])
+            if need > width:
+                out.append(_issue('error', 'present', 'too-narrow', f'{w}!{c["letter"]}',
+                                  f'「{c["header"] or c["letter"]}」列宽 {width:.1f} 不够显示（需要 {need:.0f}）',
+                                  '数字列宽度不足会显示成 ####，打印出来一片井号', fixable=True))
+            fmts = {f for f in c['formats'] if f not in (None, 'General')}
+            if len(fmts) > 1:
+                out.append(_issue('warn', 'present', 'format-mix', f'{w}!{c["letter"]}',
+                                  f'「{c["header"] or c["letter"]}」列有 {len(fmts)} 种数字格式：{list(fmts)[:3]}',
+                                  '同一列有的两位小数有的整数，是报表最扎眼的不专业', fixable=True))
+            if (any(h in str(c['header'] or '') for h in L.AMOUNT_HINTS)
+                    and ',' not in str(c['format']) and c['format'] in ('General', None)):
+                out.append(_issue('warn', 'present', 'no-thousands', f'{w}!{c["letter"]}',
+                                  f'「{c["header"]}」是金额列但没有千分位格式',
+                                  '七位数不加千分位没人读得出量级', fixable=True))
+        n_rows = s['max_row'] - s['first_data'] + 1
+        if n_rows > 20 and not s['freeze']:
+            out.append(_issue('warn', 'present', 'no-freeze', w,
+                              f'{n_rows} 行数据但没有冻结窗格',
+                              '翻到第 30 行就不知道每列是什么了', fixable=True))
+        if n_rows > 20 and not s['autofilter']:
+            out.append(_issue('info', 'present', 'no-filter', w, '数据表没有开启筛选',
+                              '', fixable=True))
+        if widths and not s['fit_width']:
+            pages, total, usable = L.print_pages_wide(widths, landscape=s['landscape'])
+            if pages > 1:
+                out.append(_issue('warn', 'present', 'print-wide', w,
+                                  f'打印会横跨 {pages} 页（表宽 {total}cm，可用 {usable}cm）',
+                                  '设置「缩放到一页宽」或改横向；跨页的报表没人看得下去', fixable=True))
+        if n_rows > 40 and not s['print_titles']:
+            out.append(_issue('info', 'present', 'no-print-title', w,
+                              '长表没有设置打印时重复标题行', '', fixable=True))
+    return out
+
+
+# ── 自动校正 ───────────────────────────────────────────────────────────────
+def fix(path, out_path=None, profile_name='auto', inplace=False):
+    B = Book(path, profile_name)
+    if B.legacy:
+        # 旧版 .xls 是「值搬运」读进来的：另存会把原件的公式、格式、合并、打印设置
+        # 一次性丢光，而输出文件看起来完全正常。这种「修完更糟且看不出来」的事不能做。
+        raise ValueError('旧版 .xls 不做自动校正：读入时只保留了值，'
+                         '另存会丢掉原件的公式与格式。请先用 Excel 另存为 .xlsx 再跑 fix')
+    prof = B.profile
+    done = Counter()
+    for s in B.sheets:
+        ws = s['ws']
+        if not s['max_row'] or not s['header_row']:
+            continue
+        # ① 拆掉数据区里的合并单元格并把值填满（排序/筛选/透视的前提）
+        for m in list(s['merges']):
+            mm = re.match(r'([A-Z]+)(\d+):([A-Z]+)(\d+)', m)
+            if not mm:
+                continue
+            r1, r2 = int(mm.group(2)), int(mm.group(4))
+            if r2 < s['first_data']:
+                continue                      # 表格上方的标题横幅，保留
+            c1, c2 = L.col_index(mm.group(1)), L.col_index(mm.group(3))
+            v = ws.cell(r1, c1).value
+            try:
+                ws.unmerge_cells(m)
+            except Exception:
+                continue
+            for r in range(r1, r2 + 1):
+                for j in range(c1, c2 + 1):
+                    if ws.cell(r, j).value is None:
+                        ws.cell(r, j).value = v
+            done['拆合并'] += 1
+        for c in s['cols']:
+            head = str(c['header'] or '')
+            k = c['kinds']
+            n = sum(k.values()) - k['blank']
+            is_id = any(h in head.lower() for h in ID_HINTS)
+            # ② 文本数字 → 真数字（SUM 才算得出来）；编号列反过来锁成文本
+            if n > 0 and k['num-text'] >= max(3, n * 0.6) and not is_id:
+                fmt = L.guess_format(head, [])
+                for r in range(s['first_data'], s['max_row'] + 1):
+                    cell = ws.cell(r, c['j'])
+                    if isinstance(cell.value, str) and NUM_TEXT_RE.match(cell.value):
+                        cell.value = _parse_num(cell.value)
+                        cell.number_format = fmt if fmt != 'General' else L.FORMATS['amount']
+                        cell.alignment = Alignment(horizontal='right', vertical='center')
+                done['文本转数字'] += 1
+            elif is_id and k['number'] >= max(3, n * 0.8):
+                mx = max((abs(float(v)) for v in c['vals'] if _num(v) is not None), default=0)
+                if mx >= 1e15:
+                    continue          # 精度已经丢了，把错值定型成文本只会把错误固化
+                for r in range(s['first_data'], s['max_row'] + 1):
+                    cell = ws.cell(r, c['j'])
+                    v = cell.value
+                    if _num(v) is not None:
+                        # 必须连**值**一起转成文本：只改 number_format，值还是数字，
+                        # 下次导出/读取照样按数字走，等于没修
+                        cell.value = ('%d' % v) if float(v).is_integer() else str(v)
+                        cell.number_format = L.FORMATS['text']
+                        cell.alignment = Alignment(horizontal='left', vertical='center')
+                done['编号列转文本'] += 1
+            # ③ 去首尾空白与不可见字符
+            dirty = 0
+            for r in range(s['first_data'], s['max_row'] + 1):
+                cell = ws.cell(r, c['j'])
+                if isinstance(cell.value, str):
+                    t = cell.value
+                    for ch in INVISIBLE:
+                        t = t.replace(ch, ' ' if ch in '\t\r\n' else '')
+                    t = t.strip()
+                    if t != cell.value:
+                        cell.value = t
+                        dirty += 1
+            if dirty:
+                done['清空白'] += 1
+            # ④ 同列数字格式归一
+            fmts = {f for f in c['formats'] if f not in (None, 'General')}
+            if len(fmts) > 1:
+                main = c['formats'].most_common(1)[0][0]
+                if main in (None, 'General'):
+                    main = sorted(fmts)[0]
+                for r in range(s['first_data'], s['max_row'] + 1):
+                    if ws.cell(r, c['j']).value is not None:
+                        ws.cell(r, c['j']).number_format = main
+                done['格式归一'] += 1
+            # ⑤ 金额列补千分位
+            if (any(h in head for h in L.AMOUNT_HINTS) and c['format'] in ('General', None)
+                    and k['number'] >= max(2, n * 0.5)):
+                for r in range(s['first_data'], s['max_row'] + 1):
+                    if _num(ws.cell(r, c['j']).value) is not None:
+                        ws.cell(r, c['j']).number_format = L.FORMATS['amount']
+                done['补千分位'] += 1
+        # ⑥ 硬编码合计 → SUM 公式；SUM 范围补到数据末行
+        done += _fix_totals(s)
+        done += _fix_sum_range(s)
+        # ⑦ 列宽自适应（放在最后，前面改过值与格式）
+        for c in s['cols']:
+            vals = [ws.cell(r, c['j']).value for r in range(s['first_data'], s['max_row'] + 1)]
+            vals = [v for v in vals if v is not None and not _is_formula(v)]
+            fmt = ws.cell(s['first_data'], c['j']).number_format
+            w = L.col_width(vals, c['header'], fmt)
+            if (c['width'] or 0) < w:
+                ws.column_dimensions[c['letter']].width = w
+                done['列宽'] += 1
+        # ⑧ 冻结 / 筛选 / 打印
+        n_rows = s['max_row'] - s['first_data'] + 1
+        if n_rows > 20 and not s['freeze']:
+            ws.freeze_panes = f'A{s["header_row"] + 1}'
+            done['冻结'] += 1
+        if n_rows > 20 and not s['autofilter']:
+            ws.auto_filter.ref = f'A{s["header_row"]}:{get_column_letter(s["max_col"])}{s["max_row"]}'
+            done['筛选'] += 1
+        if not s['fit_width']:
+            from openpyxl.worksheet.properties import PageSetupProperties
+            ws.sheet_properties.pageSetUpPr = PageSetupProperties(fitToPage=True)
+            ws.page_setup.fitToWidth = 1
+            ws.page_setup.fitToHeight = 0
+            done['打印一页宽'] += 1
+        if n_rows > 40 and not s['print_titles']:
+            ws.print_title_rows = f'{s["header_row"]}:{s["header_row"]}'
+            done['重复标题行'] += 1
+
+    if not out_path:
+        base, ext = os.path.splitext(path)
+        out_path = path if inplace else base + '-已校正' + ext
+    B.wb.save(out_path)
+    return out_path, done
+
+
+def _parse_num(t):
+    s = str(t).strip()
+    neg = s.startswith(('(', '（')) and s.endswith((')', '）'))
+    s = re.sub(r'[（()）,，¥￥$元\s%]', '', s)
+    try:
+        v = float(s)
+    except ValueError:
+        return t
+    if '%' in str(t):
+        v /= 100.0
+    return -abs(v) if neg else v
+
+
+def _fix_totals(s):
+    """把写死的合计换成 SUBTOTAL 公式——**这一条是本模块最值钱的修复**：
+    常量合计不会报错，只会在下次改明细后安静地给出过期的数。"""
+    done = Counter()
+    ws = s['ws']
+    tail = [r for r in s['subtotal_rows'] if r >= s['max_row'] - 1] or s['subtotal_rows'][-1:]
+    for tr in tail:
+        for c in s['cols']:
+            cell = ws.cell(tr, c['j'])
+            if _num(cell.value) is None or _is_formula(cell.value):
+                continue
+            body = [r for r in range(s['first_data'], tr) if r not in s['subtotal_rows']]
+            if len(body) < 2:
+                continue
+            nums = sum(1 for r in body if _num(ws.cell(r, c['j']).value) is not None)
+            if nums < 2:
+                continue
+            cell.value = f'=SUBTOTAL(9,{c["letter"]}{s["first_data"]}:{c["letter"]}{tr - 1})'
+            cell.font = Font(name=cell.font.name, size=cell.font.size, bold=True)
+            done['合计改公式'] += 1
+    return done
+
+
+def _fix_sum_range(s):
+    done = Counter()
+    ws = s['ws']
+    for c in s['cols']:
+        for r, f in c['formulas']:
+            new = f
+            for m in SUM_RE.finditer(f):
+                c1, r1, c2, r2 = m.group(2), int(m.group(3)), m.group(4), int(m.group(5))
+                if c1 != c2:
+                    continue
+                jj = L.col_index(c1)
+                if not (1 <= jj <= s['max_col']):
+                    continue
+                last = _last_value_row(s, jj, r1, r)
+                if last and r2 < last:
+                    new = new.replace(f'{c2}{r2}', f'{c2}{last}', 1)
+            if new != f:
+                ws.cell(r, c['j']).value = new
+                done['补齐求和范围'] += 1
+    return done
+
+
+# ── 汇总与报告 ─────────────────────────────────────────────────────────────
+LEVEL_LABEL = {'error': '必修', 'warn': '建议', 'info': '提示'}
+GROUP_LABEL = {'data': '数据', 'structure': '结构', 'formula': '公式',
+               'reconcile': '勾稽', 'present': '呈现', 'meta': '元信息'}
+ORDER = {'error': 0, 'warn': 1, 'info': 2}
+
+
+def inspect(path, profile_name='auto', strict=False):
+    B = Book(path, profile_name)
+    issues = []
+    issues += check_data(B)
+    issues += check_structure(B)
+    if B.legacy:
+        # 说清楚哪几层没查——不说，用户会以为「必修 0」等于这份表没问题
+        issues.append({'level': 'info', 'group': 'present', 'kind': 'legacy-xls',
+                       'where': os.path.basename(path),
+                       'msg': '这是旧版 .xls，只做了数据层体检',
+                       'detail': '公式、列宽、合并单元格、冻结窗格、打印设置这几类在 .xls 里读不到，'
+                                 '本次未做判断——不是「没问题」，是「没查」',
+                       'suggest': '用 Excel 另存为 .xlsx 后重跑，可拿到完整的六类体检'})
+    else:
+        issues += check_formula(B)
+    issues += check_reconcile(B)
+    if not B.legacy:
+        issues += check_present(B)
+    counts = Counter(i['level'] for i in issues)
+    return {
+        'path': path, 'profile': B.profile['name'], 'profile_label': B.profile['label'],
+        'stats': {'legacy': B.legacy, 'sheets': len(B.sheets),
+                  'rows': sum(s['max_row'] for s in B.sheets),
+                  'cols': max((s['max_col'] for s in B.sheets), default=0),
+                  'formulas': sum(s['formulas'] for s in B.sheets),
+                  'merged': sum(len(s['merges']) for s in B.sheets),
+                  'charts': sum(s['charts'] for s in B.sheets),
+                  'sheet_names': [s['name'] for s in B.sheets]},
+        'counts': {'error': counts.get('error', 0), 'warn': counts.get('warn', 0),
+                   'info': counts.get('info', 0)},
+        'issues': issues,
+    }
+
+
+def report(res, limit=5, show_info=True):
+    s, c = res['stats'], res['counts']
+    lines = [f"【表格体检】{os.path.basename(res['path'])} · {res['profile_label']}",
+             (f"  规模：{s['sheets']} 表 / 共 {s['rows']} 行 / 最宽 {s['cols']} 列"
+              f"（旧版 .xls：公式/合并/图表读不到，**不是没有**）"
+              if s.get('legacy') else
+              f"  规模：{s['sheets']} 表 / 共 {s['rows']} 行 / 最宽 {s['cols']} 列 / "
+              f"{s['formulas']} 个公式 / {s['merged']} 处合并 / {s['charts']} 张图"),
+             f"  结论：必修 {c['error']} · 建议 {c['warn']} · 提示 {c['info']}"]
+    grouped = defaultdict(list)
+    for it in res['issues']:
+        grouped[(it['level'], it['group'], it['kind'])].append(it)
+    for key in sorted(grouped, key=lambda k: (ORDER[k[0]], k[1])):
+        lvl, grp, _ = key
+        if lvl == 'info' and not show_info:
+            continue
+        items = grouped[key]
+        head = f"  [{LEVEL_LABEL[lvl]}·{GROUP_LABEL.get(grp, grp)}] {items[0]['msg']}"
+        if len(items) > 1:
+            head += f'（{len(items)} 处）'
+        if items[0].get('fixable'):
+            head += ' ⟨可自动修⟩'
+        lines.append(head)
+        for it in items[:limit]:
+            d = f" — {it['detail']}" if it.get('detail') else ''
+            lines.append(f"      · {it['where']}{d}")
+        if len(items) > limit:
+            lines.append(f'      · …另有 {len(items)-limit} 处')
+    if not res['issues']:
+        lines.append('  未发现问题。')
+    return '\n'.join(lines)
+
+
+def main(argv):
+    args = [a for a in argv if not a.startswith('--')]
+    if not args:
+        print('用法：python xlsx_check.py 表.xlsx [--fix] [--inplace] [--strict] '
+              '[--profile=report|plain|finance] [--json]')
+        return 2
+    path = args[0]
+    prof = 'auto'
+    for a in argv:
+        if a.startswith('--profile='):
+            prof = a.split('=', 1)[1]
+    if not os.path.exists(path):
+        print(f'文件不存在：{path}')
+        return 2
+    if os.path.isdir(path):
+        print('这是目录不是工作簿：请指定具体的 .xlsx 文件')
+        return 2
+    res = inspect(path, prof, '--strict' in argv)
+    if '--json' in argv:
+        print(json.dumps(res, ensure_ascii=False, default=str))
+        return 0
+    print(report(res))
+    if '--fix' in argv:
+        out, done = fix(path, None, prof, inplace='--inplace' in argv)
+        print('\n【自动校正】' + ('、'.join(f'{k} {v} 处' for k, v in done.items()) if done else '无可自动修复项'))
+        print(f'  已另存：{out}' if '--inplace' not in argv else f'  已就地修改：{out}')
+        print('\n' + report(inspect(out, prof)))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))