数据字典条目撰写

数据字典条目：首购日期

- 字段中文名：首购日期
- 字段英文名：first_purchase_date
- 所属主题/域：客户（Customer）/ 客户生命周期
- 粒度：客户粒度（customer_id 唯一确定一条记录）
- 数据类型与格式：DATE（YYYY-MM-DD）
- 时区口径：以交易发生地业务时区为准（默认 UTC+08:00）；跨地区业务需在计算前完成时区统一

业务定义
- 客户在本企业范围内首次完成“有效购买”的日期。有效购买指订单已成功支付且未被全额退款或取消。用于刻画客户生命周期起点，常用于新客判定、留存与分群分析。

默认计算口径
- 交易范围：商品/服务销售订单
- 成交时间：以支付成功时间 paid_at 为准；若无 paid_at 且以收货/完成作为成交依据的业态，可取完成时间 finished_at，但需在口径中保持一致
- 有效订单条件：
  - 订单状态属于已支付/已完成（不含取消、关闭）
  - 非全额退款（全额退款订单剔除；部分退款订单保留）
  - 订单金额 amount_payable > 0（剔除纯0元、全额优惠、纯积分兑换、仅使用代金券且应收为0的订单）
  - 订单类型不包含：充值、礼品卡购买、内部测试单、虚拟冲销单
- 身份合并：如存在账号合并/多渠道统一客户ID，以统一后的 customer_id 取最早有效 paid_at 日期
- 拆单/并单：若一次购买被拆分多个子单，以最早一个有效子单的 paid_at 计入
- 预售/订金场景：以尾款支付成功时间计入（订金支付不计为首购）
- 退款时序：若首购订单后被全额退款且无其他有效订单，则首购日期置空；若存在更早被退款的订单且之后有有效订单，则以后者的最早支付日为首购日期

来源与血缘（示例）
- 源表：dwd_order_header（或事实表 fact_sales_order）
- 关键字段：customer_id, order_id, order_type, order_status, paid_at, finished_at, amount_payable, amount_refunded, is_test
- 生成逻辑（概念性）：
  1) 从订单事实中过滤有效订单（按上述口径）
  2) 以 customer_id 分组，取最小的 paid_at 的日期部分
  3) 写入客户主题表或客户快照表的 first_purchase_date

数据刷新
- 刷新频率：每日增量+周期性全量回溯（建议每周回溯近90天以处理迟到退款/状态更正）
- 生效延迟：考虑支付对账与退款回填延迟，T+1 至 T+2 稳妥

缺失与默认值
- 无有效订单的客户：首购日期为空（NULL）
- 禁止使用占位日期（如 1900-01-01）

数据质量校验
- 首购日期不应晚于当前日期
- 同一 customer_id 首购日期应唯一且不可变更，除非订单状态回溯导致口径重算
- 首购日期应大于等于客户首次识别日期（若小于且存在游客购买后注册，需确认ID合并逻辑）
- 核对规则：样本抽检首购订单应满足有效订单条件；全额退款回溯后样本应被移除

常见陷阱与处理
- 时区未统一导致跨日偏移：统一在 ETL 前转换至业务时区
- 将下单时间或发货时间误作成交时间：必须以 paid_at 为主口径
- 未剔除全额退款/测试单/0元单：严格按口径过滤
- 多渠道客户未合并：确保使用统一客户主数据（CDP/MDM）映射

应用场景
- 新客判定与首购 Cohort 分析
- RFM、CLV、留存与复购漏斗
- 精准营销与拉新投放归因起点

口径负责人与变更
- 口径负责人：数据治理/BI 负责人
- 版本与生效：v1.0（生效日期：填写发布日）
- 变更原则：任何口径调整需在数据字典与下游报表同步更新并进行影响评估

数据字典条目：订单金额

- 名称（中文/英文标识）
  - 订单金额 / 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.