@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,391 @@
+# 数据体检：分析动手之前，先把这份数据「哪里不能信」查清楚。
+#
+# 为什么必须有：数据分析出错误答案，绝大多数不是算法错，是**读进来的东西不是你以为的东西**——
+# 金额是文本（SUM 得 0）、订单号被读成数字（前导零没了）、日期是 Excel 序列号、
+# 明细里混着「合计」行（一汇总就翻倍）、两个「北京」差一个空格没合并、主键其实不唯一。
+# 这些在代码里都不报错，只是把数字算错，而算错的数字看起来和算对的一模一样。
+#
+# 与 xlsx_toolkit 的分工：那边管**把脏表读进来**（表头识别、金额救回、日期归一），
+# 这边管**读进来之后告诉你它还有哪里不对**。先 smart_read，再 profile。
+#
+# 用法：
+#   import data_profile as P
+#   P.report(P.profile(df, '应收明细'))          # 单表体检
+#   P.report_file('收款单.xlsx')                 # 整本工作簿逐 Sheet 体检
+# 或 CLI：python data_profile.py 数据.xlsx [--sheet 名] [--json]
+
+import json
+import re
+import sys
+import warnings
+from collections import Counter
+
+warnings.simplefilter('ignore')
+import numpy as np      # noqa: E402
+import pandas as pd     # noqa: E402
+
+ID_HINTS = ('编码', '编号', '代码', '号', 'id', 'code', 'no', '卡号', '工号', '身份证', '邮编')
+AMOUNT_HINTS = ('金额', '贷方', '借方', '余额', '税额', '价税', '收入', '成本', '费用',
+                '单价', '工资', '总额', '应收', '应付', '预收', '预付', '销售额', '利润')
+DATE_HINTS = ('日期', '时间', '月份', '期间', '账期', '年月')
+SUBTOTAL_MARKS = ('合计', '小计', '总计', '合 计', '小 计', '总 计', '本页合计', '累计', 'total', 'subtotal')
+INVISIBLE = ' 　​\t\r\n'
+NUM_RE = re.compile(r'^\s*[（(]?\s*[-+]?[¥￥$]?\s*[\d,，]+(\.\d+)?\s*[%元]?\s*[)）]?\s*$')
+
+
+def _issue(level, kind, where, msg, detail='', suggest=''):
+    return {'level': level, 'kind': kind, 'where': where, 'msg': msg,
+            'detail': detail, 'suggest': suggest}
+
+
+def _sample(s, n=3):
+    v = s.dropna()
+    if v.empty:
+        return []
+    return [str(x)[:24] for x in v.head(n).tolist()]
+
+
+def _looks_number(x):
+    if isinstance(x, (int, float, np.number)) and not isinstance(x, bool):
+        return True
+    return bool(NUM_RE.match(str(x)))
+
+
+def _looks_date(x):
+    s = str(x).strip()
+    if re.fullmatch(r'\d{4}[-/.年]\d{1,2}([-/.月]\d{1,2}日?)?', s):
+        return True
+    return bool(re.fullmatch(r'\d{4}[-/]\d{1,2}[-/]\d{1,2}[ T].*', s))
+
+
+def _norm_cat(x):
+    """分类值归一：去空白与不可见字符、全半角、大小写——用于找「同物异名」。"""
+    t = str(x)
+    for ch in INVISIBLE:
+        t = t.replace(ch, '')
+    return t.strip().lower().replace('（', '(').replace('）', ')')
+
+
+# ── 单列体检 ───────────────────────────────────────────────────────────────
+def profile_column(s, name, n_rows):
+    col = {'name': name, 'dtype': str(s.dtype), 'nulls': int(s.isna().sum()),
+           'null_rate': round(float(s.isna().mean()), 4) if n_rows else 0.0,
+           'unique': int(s.nunique(dropna=True)), 'sample': _sample(s)}
+    issues = []
+    nn = s.dropna()
+    col['inferred'] = 'empty'
+    if nn.empty:
+        issues.append(_issue('warn', 'empty-col', name, '整列为空',
+                             '', '确认是否漏读了列，或直接删掉这一列'))
+        return col, issues
+
+    is_obj = s.dtype == object or pd.api.types.is_string_dtype(s)
+    if pd.api.types.is_numeric_dtype(s) and not pd.api.types.is_bool_dtype(s):
+        col['inferred'] = 'number'
+    elif pd.api.types.is_datetime64_any_dtype(s):
+        col['inferred'] = 'date'
+    elif pd.api.types.is_bool_dtype(s):
+        col['inferred'] = 'bool'
+    else:
+        col['inferred'] = 'text'
+
+    if is_obj:
+        # **按值的真实类型判，不按列 dtype 判**：pandas 用 dtype=object 读进来的列里
+        # 装的往往是货真价实的 int/float（smart_read 就是这么读的）。
+        # 早先按 dtype 判，这类列一律被判成「数值被存成文本」——在最常用的读表路径上
+        # 大面积误报，而误报比漏报更快让人关掉检查。
+        head = nn.head(500)
+        n = len(head)
+        strs = [v for v in head if isinstance(v, str)]
+        reals = [v for v in head if isinstance(v, (int, float, np.number)) and not isinstance(v, bool)]
+        num_like = sum(1 for v in strs if NUM_RE.match(v)) / max(n, 1)
+        date_like = sum(1 for v in strs if _looks_date(v)) / max(n, 1)
+        if reals and len(reals) >= n * 0.9:
+            col['inferred'] = 'number'          # object 列，但装的是真数字
+        # ① 数字存成了文本——SUM 会得 0，是「对账对不平」的头号原因
+        if num_like >= 0.9 and not any(k in str(name) for k in ID_HINTS):
+            col['inferred'] = 'number-as-text'
+            issues.append(_issue('error', 'num-as-text', name,
+                                 f'数值被存成文本（{num_like*100:.0f}% 的值形如数字）',
+                                 f'示例 {col["sample"]}',
+                                 '用 to_amount() 转成 float 再算；直接 sum 会得 0 或字符串拼接'))
+        elif date_like >= 0.9:
+            col['inferred'] = 'date-as-text'
+            issues.append(_issue('warn', 'date-as-text', name,
+                                 f'日期被存成文本（{date_like*100:.0f}% 形如日期）',
+                                 f'示例 {col["sample"]}', '用 to_period()/to_datetime() 转换后再排序或分组'))
+        # ② 一列里数字与文本混——排序、分组、比较全都会出鬼
+        elif reals and strs and 0.15 < len(strs) / max(n, 1) < 0.85:
+            issues.append(_issue('warn', 'mixed-type', name,
+                                 f'同一列里真数字与文本混杂（{len(reals)} 数字 / {len(strs)} 文本）',
+                                 f'示例 {col["sample"]}', '先统一类型：要么全转数字，要么全按文本处理'))
+        # ③ 首尾空白与不可见字符——「北京 」和「北京」分组会分成两组
+        dirty = int(sum(v != v.strip() or any(ch in v for ch in INVISIBLE)
+                        for v in nn.head(2000) if isinstance(v, str)))
+        if dirty:
+            issues.append(_issue('warn', 'whitespace', name,
+                                 f'{dirty} 个值带首尾空白或不可见字符（含全角空格/换行）',
+                                 '', '.str.strip() 并清掉 \\u00a0/\\u3000，否则分组会分成两组'))
+        # ④ 同物异名：归一化后能合并的组
+        if 1 < col['unique'] <= 2000 and col['inferred'] not in ('number', 'number-as-text'):
+            groups = Counter(_norm_cat(v) for v in nn.head(2000))
+            merged = [k for k, c in groups.items() if c > 0]
+            if len(merged) < col['unique']:
+                issues.append(_issue('warn', 'alias', name,
+                                     f'归一化后取值从 {col["unique"]} 个降到 {len(merged)} 个，存在同物异名',
+                                     '', '先 normalize_key() 再分组/关联，否则会算成不同的实体'))
+    # ⑤ ID 列被读成数字 → 前导零丢了、超 15 位精度丢了
+    if col['inferred'] == 'number' and any(k in str(name).lower() for k in ID_HINTS):
+        mx = float(pd.to_numeric(nn, errors='coerce').abs().max() or 0)
+        issues.append(_issue('warn' if mx < 1e15 else 'error', 'id-as-number', name,
+                             '编号类列被读成了数字',
+                             f'最大值 {mx:.0f}' + ('（已超 15 位，末位精度可能已丢）' if mx >= 1e15 else ''),
+                             'read_excel(dtype={"%s": str})，否则前导零会消失、长号会变科学计数法' % name))
+
+    if col['inferred'] == 'number':
+        v = pd.to_numeric(nn, errors='coerce').dropna()
+        if len(v):
+            q1, q3 = float(v.quantile(.25)), float(v.quantile(.75))
+            iqr = q3 - q1
+            out = int(((v < q1 - 3 * iqr) | (v > q3 + 3 * iqr)).sum()) if iqr > 0 else 0
+            col['stats'] = {'min': float(v.min()), 'max': float(v.max()),
+                            'mean': round(float(v.mean()), 4), 'median': float(v.median()),
+                            'zeros': int((v == 0).sum()), 'negatives': int((v < 0).sum()),
+                            'outliers': out}
+            if out and out / len(v) < 0.05:
+                issues.append(_issue('info', 'outlier', name,
+                                     f'{out} 个极端值（超出 3 倍四分位距）',
+                                     f'范围 {v.min():.2f} ~ {v.max():.2f}', '确认是真实极值还是录入错误'))
+    if col['inferred'] == 'date':
+        v = nn
+        try:
+            col['stats'] = {'min': str(v.min())[:10], 'max': str(v.max())[:10]}
+            future = int((v > pd.Timestamp.now()).sum())
+            if future:
+                issues.append(_issue('warn', 'future-date', name,
+                                     f'{future} 个未来日期', f'最大 {str(v.max())[:10]}',
+                                     '确认是计划日期还是录入错误'))
+            months = pd.Series(v).dt.to_period('M').nunique()
+            span = (v.max() - v.min()).days if len(v) > 1 else 0
+            if span > 62 and months and months < span / 31 * 0.7:
+                issues.append(_issue('info', 'gap-month', name,
+                                     f'时间跨度 {span} 天但只覆盖 {months} 个月，中间有断月',
+                                     '', '按月汇总时缺月会被跳过，画趋势图要先 reindex 补齐'))
+        except Exception:
+            pass
+    return col, issues
+
+
+# ── 整表体检 ───────────────────────────────────────────────────────────────
+def profile(df, name='', key_hint=None):
+    """单表体检。返回 {name, shape, columns[], issues[], keys[]}。"""
+    n_rows, n_cols = df.shape
+    res = {'name': name, 'rows': int(n_rows), 'cols': int(n_cols),
+           'memory_mb': round(float(df.memory_usage(deep=True).sum()) / 1048576, 2),
+           'columns': [], 'issues': [], 'keys': []}
+    if n_rows == 0:
+        res['issues'].append(_issue('error', 'empty', name or '表', '表里没有数据行',
+                                    '', '确认表头行是否识别对了（smart_read 可手动传 header=N）'))
+        return res
+    # 列名问题
+    names = [str(c) for c in df.columns]
+    unnamed = [c for c in names if c.lower().startswith('unnamed') or re.fullmatch(r'列\d+', c)]
+    if unnamed:
+        res['issues'].append(_issue('warn', 'unnamed-col', '列名',
+                                    f'{len(unnamed)} 个列没有名字：{unnamed[:5]}',
+                                    '', '多半是表头行认错了——用 detect_header 复核，或手动指定 header=N'))
+    dup = [c for c, k in Counter(names).items() if k > 1]
+    if dup:
+        res['issues'].append(_issue('error', 'dup-col', '列名', f'重名列：{dup[:5]}',
+                                    '', '重名列取值时会拿到 DataFrame 而不是 Series，后续全错'))
+    messy = [c for c in names if c != c.strip() or any(ch in c for ch in INVISIBLE)]
+    if messy:
+        res['issues'].append(_issue('warn', 'messy-col', '列名',
+                                    f'{len(messy)} 个列名带空白/换行：{messy[:3]}',
+                                    '', 'df.columns = df.columns.str.strip()，否则 df["销售额"] 会 KeyError'))
+
+    # 重复行
+    try:
+        dups = int(df.duplicated().sum())
+        if dups:
+            res['issues'].append(_issue('warn', 'dup-row', '全表',
+                                        f'{dups} 行完全重复（占 {dups/n_rows*100:.1f}%）',
+                                        '', '确认是真实重复业务还是导出重复；汇总前要不要去重'))
+    except Exception:
+        pass
+
+    # 「合计」行混在明细里——一汇总就双计，是最隐蔽的错误来源
+    sub = _subtotal_rows(df)
+    if sub:
+        res['issues'].append(_issue('error', 'subtotal-row', '全表',
+                                    f'{len(sub)} 行疑似「合计/小计」混在明细中（行号 {sub[:6]}）',
+                                    '', '分析前剔除，否则求和会翻倍；合计用 pivot_table(margins=True) 自己生成'))
+
+    # 全空行/列
+    blank_rows = int(df.isna().all(axis=1).sum())
+    if blank_rows:
+        res['issues'].append(_issue('info', 'blank-row', '全表', f'{blank_rows} 行整行为空',
+                                    '', 'dropna(how="all") 清掉'))
+
+    # 主键候选：先单列，再两列组合（组合只在单列都不唯一时找，且列数不多时才试）
+    res['keys'] = _find_keys(df, key_hint)
+    if not res['keys']:
+        res['issues'].append(_issue('info', 'no-key', '全表',
+                                    '没有找到唯一标识列（单列或两列组合）',
+                                    '', '关联前要确认粒度：主键不唯一时 merge 会产生笛卡尔积把行数放大'))
+
+    for c in df.columns:
+        col, iss = profile_column(df[c], str(c), n_rows)
+        res['columns'].append(col)
+        res['issues'].extend(iss)
+    return res
+
+
+def _subtotal_rows(df, max_scan=20000):
+    hits = []
+    for c in df.columns:
+        s = df[c]
+        if s.dtype != object and not pd.api.types.is_string_dtype(s):
+            continue
+        # .str 访问器会把 NaN 原样传下去（不是 'nan'），所以必须 fillna 后再判，
+        # 否则 lambda 会收到 float nan 直接 TypeError
+        v = s.head(max_scan).astype(str).str.strip().str.lower().fillna('')
+        m = v.apply(lambda x: bool(x) and len(x) <= 12 and any(k in x for k in SUBTOTAL_MARKS))
+        hits.extend(list(df.index[:len(m)][m.fillna(False)]))
+    return sorted(set(int(i) for i in hits if isinstance(i, (int, np.integer))))[:50]
+
+
+def _find_keys(df, key_hint=None, max_cols=12):
+    n = len(df)
+    single = [str(c) for c in df.columns
+              if df[c].notna().all() and df[c].nunique(dropna=True) == n]
+    if single:
+        return single[:3]
+    cand = [c for c in df.columns if df[c].notna().all() and 1 < df[c].nunique(dropna=True) < n]
+    if key_hint:
+        cand = [c for c in cand if str(c) in key_hint] or cand
+    cand = cand[:max_cols]
+    for i, a in enumerate(cand):
+        for b in cand[i + 1:]:
+            try:
+                if not df.duplicated(subset=[a, b]).any():
+                    return [f'{a} + {b}']
+            except Exception:
+                continue
+    return []
+
+
+def profile_file(path, sheet=None, smart=True):
+    """整本工作簿逐 Sheet 体检。smart=True 时优先用 xlsx_toolkit 的稳读（治表头不在首行）。"""
+    reader = None
+    if smart:
+        try:
+            import os
+            sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+            import xlsx_toolkit as T
+            reader = T
+        except Exception:
+            reader = None
+    out = []
+    if str(path).lower().endswith('.csv'):
+        df = pd.read_csv(path, dtype=object, encoding='utf-8-sig')   # 吃掉 BOM，否则首列名带 \ufeff
+        out.append(profile(df, '(csv)'))
+        return out
+    xf = None
+    if reader is not None:
+        xf, why = reader.open_workbook(path)
+        if xf is None:
+            return [{'name': str(path), 'rows': 0, 'cols': 0, 'columns': [], 'keys': [],
+                     'issues': [_issue('error', 'unreadable', str(path), f'打不开：{why}')]}]
+    else:
+        xf = pd.ExcelFile(path)
+    names = [sheet] if sheet else xf.sheet_names
+    for s in names:
+        try:
+            df = reader.smart_read(path, s) if reader is not None else xf.parse(s)
+        except Exception as e:
+            out.append({'name': s, 'rows': 0, 'cols': 0, 'columns': [], 'keys': [],
+                        'issues': [_issue('error', 'unreadable', s, f'读取失败：{type(e).__name__}: {e}')]})
+            continue
+        out.append(profile(df, str(s)))
+    return out
+
+
+# ── 报告 ───────────────────────────────────────────────────────────────────
+LEVEL = {'error': '必修', 'warn': '建议', 'info': '提示'}
+ORDER = {'error': 0, 'warn': 1, 'info': 2}
+
+
+def report(res, max_cols=40):
+    if isinstance(res, list):
+        return '\n\n'.join(report(r, max_cols) for r in res)
+    lines = [f"【数据体检】{res.get('name') or '表'} · {res['rows']} 行 × {res['cols']} 列"
+             + (f" · {res['memory_mb']}MB" if res.get('memory_mb') else '')]
+    if res.get('keys'):
+        lines.append(f"  唯一标识：{'、'.join(res['keys'])}")
+    cnt = Counter(i['level'] for i in res['issues'])
+    lines.append(f"  结论：必修 {cnt.get('error',0)} · 建议 {cnt.get('warn',0)} · 提示 {cnt.get('info',0)}")
+    for it in sorted(res['issues'], key=lambda x: ORDER[x['level']]):
+        tail = f" — {it['detail']}" if it['detail'] else ''
+        lines.append(f"  [{LEVEL[it['level']]}] {it['where']}：{it['msg']}{tail}")
+        if it['suggest']:
+            lines.append(f"      → {it['suggest']}")
+    if res['columns']:
+        lines.append('  列清单（类型 / 缺失 / 唯一值 / 示例）：')
+        for c in res['columns'][:max_cols]:
+            st = c.get('stats') or {}
+            extra = ''
+            if 'min' in st and 'mean' in st:
+                extra = f" | {st['min']:g}~{st['max']:g} 均{st['mean']:g}"
+            elif 'min' in st:
+                extra = f" | {st['min']}~{st['max']}"
+            lines.append(f"    · {c['name'][:22]:<22} {c['inferred']:<15} "
+                         f"缺{c['null_rate']*100:.0f}% 唯{c['unique']}{extra} {c['sample'][:2]}")
+        if len(res['columns']) > max_cols:
+            lines.append(f"    · …另有 {len(res['columns']) - max_cols} 列")
+    return '\n'.join(lines)
+
+
+def self_test():
+    df = pd.DataFrame({
+        '订单编号': ['001', '002', '003', '004', '合计'],
+        '客户': ['北京公司', '北京公司 ', '上海公司', '上海公司', ''],
+        '金额': ['1,200.00', '3,400.50', '2,000', '900', '7,500.50'],
+        '数量': [1, 2, 3, 4, 10],
+        '备注': [None, None, None, None, None],
+    })
+    r = profile(df, '订单明细')
+    ks = {i['kind'] for i in r['issues']}
+    assert 'num-as-text' in ks, ks           # 金额是带千分位的文本
+    assert 'subtotal-row' in ks, ks          # 「合计」行混在明细里
+    assert 'whitespace' in ks or 'alias' in ks, ks   # 「北京公司 」带尾空格
+    assert 'empty-col' in ks, ks             # 备注整列空
+    obj_int = pd.DataFrame({'序列': pd.Series([1, 2, 3, 4], dtype=object),
+                            '名称': ['甲', '乙', '丙', '丁']})
+    ks_obj = {i['kind'] for i in profile(obj_int, 'object列真数字')['issues']}
+    assert 'num-as-text' not in ks_obj, ks_obj
+    clean = pd.DataFrame({'编号': ['A1', 'A2', 'A3'], '销售额': [1.0, 2.0, 3.0],
+                          '日期': pd.to_datetime(['2026-01-01', '2026-02-01', '2026-03-01'])})
+    r2 = profile(clean, '干净表')
+    assert not [i for i in r2['issues'] if i['level'] == 'error'], r2['issues']
+    assert r2['keys'], '应识别出「编号」是唯一标识'
+    assert [c for c in r2['columns'] if c['name'] == '销售额'][0]['inferred'] == 'number'
+    print(f"[data_profile] self-test OK · 脏表命中 {len(ks)} 类、干净表零必修")
+
+
+def main(argv):
+    args = [a for a in argv if not a.startswith('--')]
+    if not args:
+        self_test()
+        return 0
+    sheet = None
+    for a in argv:
+        if a.startswith('--sheet='):
+            sheet = a.split('=', 1)[1]
+    res = profile_file(args[0], sheet)
+    print(json.dumps(res, ensure_ascii=False, default=str) if '--json' in argv else report(res))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))