"""Business table directory. Query semantics only: no classification/formula changes.""" from __future__ import annotations CATALOG_VERSION = '2026-11-18.1' AMOUNT = '实际金额(美元)' QUANTITY = '成交数量' PRICE = '平均单价(美元/成交数量单位)' CLASS_SUMMARY = '查询_叶子类目月度' MODEL_SUMMARY = '查询_品牌型号月度' ADDITIVE = [AMOUNT, QUANTITY, '记录数'] DEFINITIONS = { AMOUNT: '纳入范围的美元金额;任一成员缺失则合计未知', QUANTITY: '成交数量;只有单位可比时可累加;任一成员缺失则合计未知', PRICE: '合计金额 / 合计成交数量;不能累加或简单平均各行单价', '金额指数': '本期金额 / 2025-01金额 × 1000', '数量指数': '本期数量 / 2025-01数量 × 1000', '价格指数': '年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%', '金额占比': '本行金额 / 占比分母范围指定金额;不能跨分母累加', '数量占比': '本行数量 / 占比分母范围指定数量;不能跨分母累加', '金额环比': '本月金额 / 上月金额 - 1;缺数或零分母留空', '权重': '年度样本金额权重,封顶再分配;仅同一篮子可校验合计,不可跨篮子求和或平均', '数量环比': '本月数量 / 上月数量 - 1;缺数或零分母留空', } # Each original report is described independently; names match the supplied ZIP. SPECS = { '4.1_MLCC': ('电容器总览', '进出口方向×年月×电容器一级类目', '项目范围电容器全部纳入记录'), '5.1_存储器': ('存储器总览', '进出口方向×年月×存储器一级类目', '项目范围存储器全部纳入记录'), '1.0-3.0_MLCC': ('电容器指数', '方向×年月×电容器二级类目', '类目全部金额数量;价格指数使用年度样本'), '1.0-3.0_存储器': ('存储器指数', '方向×年月×类目节点;父子层级同时存在', '类目全部金额数量;价格指数使用年度样本'), '4.2.1_MLCC': ('电容器年度结构', '方向×年度×电容器二级类目', '当年已提供期间'), '5.2.1&3&5_存储器': ('存储器年度结构', '方向×年度×类目节点;父子层级同时存在', '当年已提供期间'), '4.2.2_MLCC': ('电容器月度结构', '方向×年月×二级类目', '类目全部纳入记录'), '5.2.2_存储器': ('存储器月度结构', '方向×年月×二级类目', '类目全部纳入记录'), '5.2.4_存储器': ('存储器月度结构', '方向×年月×三级类目', '类目全部纳入记录'), '5.2.6_存储器': ('存储器月度结构', '方向×年月×DDR代际', '类目全部纳入记录'), '4.2.3 (1-4)_MLCC': ('MLCC重点分析', '方向×年度×应用/品牌国别/品牌/型号路径节点', '年度入选路径及其他桶;父级与子级不可相加'), '5.2.7 (1-4)_存储器': ('DDR重点分析', '方向×年度×应用/品牌国别/品牌/型号路径节点', '已分类DDR入选路径及其他桶;父级与子级不可相加'), '4.2.3 (5)_MLCC': ('MLCC型号月度', '方向×年月×品牌型号×统计范围', '项目范围全部进口、限定入选路径是重叠视图,不可合计'), '5.2.7 (5)_存储器': ('DDR型号月度', '方向×年月×品牌型号×统计范围', '已分类DDR全部、限定入选路径是重叠视图,不可合计'), '4.3_MLCC': ('MLCC供应链', '方向×年度×供应链路径节点×港口粒度', '具体港口与港口国家地区为重叠视图;父子层级重复'), '5.3_存储器': ('DDR供应链', '方向×年度×供应链路径节点×港口粒度', '已分类DDR;具体港口与国家地区重叠;父子层级重复'), '样本权重': ('价格样本审计', '方向×基础类目×选样年度×样本品牌型号', '年度前100;不同类目样本可能重叠'), '选样排除': ('价格样本审计', '方向×基础类目×选样年度×排除品牌型号', '实际值仍计入总量,排除的只是价格选样'), '重点全量层级': ('重点分析审计', '方向×年度×专项×层级×父级路径×节点', '完整候选节点;父子层级不可相加'), '供应链条件占比': ('供应链条件审计', '方向×年度×专项×分析方式×港口粒度×层级×父级路径×节点', '分母随分析方式和路径改变,不可跨条件合计'), '周四归月映射': ('日历', '一个ISO年周', '整周按周四归月,不含业务金额'), '数据质量摘要': ('质量审计', '一个运行指标或异常原因', '该运行输入、排除、识别与口径说明'), '映射冲突': ('规则审计', '一个映射键的冲突', '规则库冲突,不含业务金额'), } def describe_table(name: str, columns: list[str], *, kind: str = 'stat', lineage: dict | None = None) -> dict: if name in (CLASS_SUMMARY, MODEL_SUMMARY): subject = '叶子类目月度总量' if name == CLASS_SUMMARY else '完整品牌型号月度总量' grain = '方向×年月×叶子类目路径' + ('×品牌×型号' if name == MODEL_SUMMARY else '') scope = '全部纳入记录;未识别品牌/型号保留空组;不含父级合计、TopN截断或价格样本限制' additive = [c for c in ADDITIVE if c in columns] partitions = [] elif name == 'raw': subject, grain, scope = '导入文件原文', '一条导入记录', '原始申报或外部统计导入;未经验证的外部统计禁止推断可汇总性' additive = list(columns) if kind == 'raw' else [] partitions = [] else: subject, grain, scope = SPECS.get(name, ('自定义/外部表', '由调用方确认分组维度', '未知口径,禁止自动汇总')) # Original reports are mixed views. Use summaries for additive queries. additive = [c for c in ADDITIVE if c in columns] if name in SPECS else [] partitions = [c for c in ('进/出口', '统计层级', '层级', '统计范围', '港口统计粒度', '分析方式', '占比分母范围', '选样年度') if c in columns] return dict(version=CATALOG_VERSION, subject=subject, row_grain=grain, coverage=scope, hierarchy='叶子且互斥' if name in (CLASS_SUMMARY, MODEL_SUMMARY) else '见粒度与统计层级字段;原模板可能混合父子节点', filter_dimensions=[c for c in columns if c not in DEFINITIONS and c not in ('记录数', '计算说明')], denominator='以每行占比分母范围为准;父子/范围/港口粒度视图不能相加' if '占比分母范围' in columns else '本表不提供占比;计算前需明确可比范围和单位', aggregation=dict(additive_fields=additive, required_partitions=partitions, non_additive=[c for c in columns if c in DEFINITIONS and c not in ADDITIVE], average_price='sum(金额)/sum(数量),缺数传播;成交数量单位须可比', unknown_scope=subject in ('自定义/外部表', '导入文件原文') and not additive), metric_definitions={c: DEFINITIONS[c] for c in columns if c in DEFINITIONS}, preferred_for='全量金额数量问答' if name in (CLASS_SUMMARY, MODEL_SUMMARY) else '按本表口径直接取值;求和前检查粒度', version_binding=lineage or {})