catalog.py 7.1 KB

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