数据字典条目撰写

数据字典条目：订单金额

• 名称（中文/英文标识）

  • 订单金额 / order_amount

• 定义（业务口径）

  • 订单头粒度的“商品实付金额（含税）”，即消费者在支付成功时针对商品本身实际支付的金额：
    • 含：商品含税成交价合计
    • 扣除：商品行级与订单级的折扣、优惠券、满减等
    • 不含：运费、包装费、小费、保险、服务费等非商品金额
    • 不随退款变动（退款相关见“订单退款金额”）

• 计算逻辑（标准公式）

  • 行实付金额（含税）= 数量 × 含税成交单价 − 行级优惠
  • 订单金额 = Σ 行实付金额（含税） − 订单级优惠
  • 结果四舍五入到分（2 位小数）

• 粒度与主键

  • 粒度：订单头
  • 主键：order_id

• 适用状态与时间口径

  • 适用订单状态：支付成功（已支付）
  • 时间口径：以支付成功时间（pay_success_time）作为该金额的生效时间
  • 未支付或已关闭订单：该字段为空（NULL）

• 币种与单位

  • 单位：元
  • 币种：记录订单币种（currency_code）
  • 如涉及多币种，可同时维护基准币种金额（如 CNY），转换汇率基于支付成功时间取数，来源于企业标准汇率表

• 数据类型与取值范围

  • 数据类型：DECIMAL(18,2)
  • 取值范围：≥ 0.00
  • 允许极小的误差容忍（±0.01）用于明细汇总一致性校验

• 汇总与去重规则

  • 报表汇总使用 SUM(order_amount)
  • 跨明细表关联时，确保按订单去重（distinct order_id），避免订单头与订单行重复计数导致放大

• 与相近指标的区分

  • 订单原价金额：未扣减任何优惠的商品金额
  • 订单应付金额：商品金额（含税、折后）+ 运费等非商品金额
  • 支付金额：应付金额中由支付渠道实际扣款的总额（可能包含运费等）
  • 订单退款金额：支付后发生的退款累计金额
  • 订单净收入金额：支付金额 − 退款金额（具体以财务口径为准）

• 退款与取消处理

  • 本字段不随部分或全额退款变化
  • 全额退款订单在“订单金额”仍保留原实付额；分析净收入请使用“订单净收入金额”或结合退款字段

• 数据来源与血缘（示例，按企业实际系统替换）

  • 源系统：交易中心（OMS/TMS）
  • 明细表：src.order_items（成交单价、数量、行级优惠、税额）
  • 头表：src.orders（订单级优惠、订单状态、支付成功时间、币种）
  • 汇率表：dim.fx_rates（以支付成功时间取对应币种汇率）
  • 数仓分层：dwd_order_item → dwd_order_head → dws_order_summary

• 数据质量校验

  • 校验1：订单头金额 ≈ 明细行实付金额之和（误差 ≤ 0.01）
  • 校验2：订单金额 ≥ 0，currency_code 非空
  • 校验3：仅对支付成功订单产出金额；未支付订单为 NULL
  • 校验4：重复关联校验（order_id 唯一）

• 权限与合规

  • 本字段为交易敏感数据，涉及用户维度联表时需遵循最小权限原则与隐私合规要求

• 示例

  • 三个明细行（含税成交单价 × 数量 − 行级优惠）：100×1−10=90；50×2−0=100；30×1−5=25，合计215
  • 订单级优惠：15
  • 订单金额 = 215 − 15 = 200.00 元（不含运费等）

• 版本与负责人

  • 版本：v1.0
  • 口径负责人：数据治理/商业智能负责人（待指派）
  • 口径变更：如需变更是否含税、是否包含运费、是否随退款调整，需走变更评审并全量回溯或维护新指标名

结论与使用建议

• 本字段用于衡量商品层面的“实付销售额”，适合作为销售额的统一口径用于营销、转化与商品分析。
• 涉及收入确认、财务对账或跨币种分析时，应配合基准币种转换与退款字段，避免误用导致口径偏差。

Data Dictionary Entry: New Customer Flag

• Business Term: New Customer Flag
• Technical Name: new_customer_flag
• Definition (Business): Identifies whether a transaction is the customer’s first successful purchase with the company. Value = 1 (true) if the order is the earliest qualifying paid order for the resolved customer; otherwise 0 (false).
• Purpose/Use: Distinguishes acquisition vs. repeat sales; supports funnel analysis, marketing ROI, CAC/LTV segmentation, and new-to-company revenue reporting.
• Data Type / Domain: Boolean (BIT); Allowed values: 1 or 0 (no nulls).
• Grain: Transaction/Order-level (one flag per order_id).
• Scope: Enterprise-wide across brands and channels after customer identity resolution. For brand-limited needs, use New-to-Brand Flag.
• Calculation Logic:
  1. Resolve customer identity to customer_id (post-identity graph).
  2. Define qualifying order: order_status in {‘Paid’, ‘Fulfilled’, ‘Completed’}; exclude canceled, voided, failed payments; exclude test/internal orders.
  3. For each customer_id, find min(qualified_paid_at) as first_paid_at.
  4. Set new_customer_flag = 1 when order_paid_at = first_paid_at for that customer_id; else 0.
• Inclusion/Exclusion Rules:
  • Include only monetary purchases (exclude $0 orders unless business policy states otherwise).
  • If an order is fully refunded after payment, the flag on that order remains 1 (represents first conversion); net revenue is handled separately.
  • Same-day/tie handling: If multiple qualified orders share the same paid timestamp for the same customer, flag the earliest by order_created_at or lowest order_id as 1; others as 0.
  • Guest checkouts must be linked to the resolved identity; otherwise treated as separate customers.
• Source Systems / Lineage:
  • Primary fact: fact_orders (fields: order_id, customer_id, paid_at, order_status, gross_amount, is_test, channel).
  • Dimensions/services: dim_customer (identity resolution), ref_order_status.
• Refresh / Latency:
  • Recomputed daily after ETL completes and identity resolution converges. Retroactive changes can occur when identities merge.
• Data Quality Checks:
  • Uniqueness: Exactly one order per customer_id with new_customer_flag = 1.
  • Completeness: No null values.
  • Reasonableness: New-order rate within expected historical bounds; alert on deviations.
• Ownership:
  • Data Product Owner: Sales Analytics
  • Data Steward: BI Data Governance
• Example:
  • Customer C001 qualified orders: 2025-08-01 (Order 123), 2025-08-10 (Order 456). Order 123 → new_customer_flag = 1; Order 456 → 0.
• Related Fields:
  • first_order_date (customer-level)
  • new_to_brand_flag (brand scope)
  • returning_customer_flag
  • acquisition_channel

Key points:

• This flag marks only the first qualifying paid order per resolved customer across the enterprise.
• It is sensitive to identity resolution; merges can retroactively change historical flags.
• Use brand-scoped “new_to_brand_flag” for brand-specific acquisition reporting.