创建数据字典条目

数据字典条目：user_accounts.user_id

- 字段名: user_id
- 所属表: user_accounts
- 中文名称: 用户唯一标识
- 业务含义: 用于在系统内对用户账户进行全局唯一标识，作为用户相关数据的主键及跨表关联的外键引用目标。
- 数据类型:
  - 选型A（数值型主键）: BIGINT（带符号或无符号，取决于数据库实现）
  - 选型B（无序或时间有序标识）: UUID（推荐 v4 或 v7）
- 长度/精度:
  - BIGINT: 64 位整数（典型范围 0～9,22e18）
  - UUID: BINARY(16) 或 CHAR(36)（带连字符）/CHAR(32)（不带连字符）
- 允许为空: 否（NOT NULL）
- 唯一性: 是（UNIQUE）
- 主键: 是（PRIMARY KEY）
- 默认值:
  - BIGINT: 由数据库自增序列或外部 ID 生成服务提供（不建议手工赋值）
  - UUID: 由应用或数据库函数生成（如 uuid_generate_v4()、UUIDV7），无手工默认值
- 生成策略:
  - BIGINT: 自增（AUTO_INCREMENT/SEQUENCE）或分布式雪花算法（Snowflake）以保证跨节点唯一性
  - UUID: v4（随机）或 v7（时间排序，利于索引和范围检索）；推荐存储为 BINARY(16) 提升存储与索引效率
- 值域/格式约束:
  - BIGINT: 正整数，范围不溢出当前实现
  - UUID: 符合 RFC 4122（v4/v7）格式；若为 CHAR(36)，格式为 8-4-4-4-12（含连字符）
- 索引:
  - 主键索引（BTREE）；若采用 UUID v4，建议使用 BINARY(16) 或 v7 以减少索引随机插入开销
- 更新策略: 禁止更新（immutable）；仅在插入时生成，禁止复用或重置
- 删除策略: 推荐逻辑删除（如设置 deleted_at），避免主键复用；如物理删除，确保外键级联或引用清理
- 参考关系: 作为其他业务表（如 user_profiles、sessions、orders 等）的外键引用目标；外键列应与此列类型一致
- 访问与检索模式:
  - 高频作为连接键（JOIN）、点查（GET by ID）与权限校验；保证主键索引可用
  - 默认不作为分区键；如有分片/分区需求可使用哈希(user_id)实现均衡
- 数据质量规则:
  - 唯一性：全局唯一，禁止重复
  - 完整性：非空；插入时必须可生成且符合格式
  - 一致性：跨环境（开发/测试/生产）生成策略一致，避免 ID 冲突
- 安全与合规:
  - 不包含个人敏感信息（PII），可用于日志与审计
  - 若对外暴露（API/URL），应防止枚举攻击；优先选择难以猜测的方案（UUID 或非连续分布式 ID）
- 示例值:
  - BIGINT: 943281057213
  - UUID v4（CHAR36）: 3f5b2c7e-9a58-4d32-9b6f-4b3c2e8d1a70
  - UUID v7（BINARY16）: 0x018f22b3c4d5e6f7a8b90c1d2e3f4567
- 变更与迁移指引:
  - 类型变更需全量迁移与下游同步（含外键、索引、ETL 映射、数据仓库维表）
  - 若从 BIGINT 迁移至 UUID，需双写或影子列过渡（user_id_new），完成后切换主键并清理旧列
- 备注/选型建议:
  - 单库或集中式易扩展：可选 BIGINT 自增/雪花
  - 分布式、对外暴露、索引写入均衡：优先 UUID（v7 更适合排序与索引性能）

数据字典条目——kpi_app.dau

- 字段名: dau
- 中文名称: 日活跃用户数
- 所属表: kpi_app
- 业务含义: 在统计日期内发生至少一次“有效活跃行为”的唯一用户数量。用于衡量应用在自然日维度的用户活跃规模。
- 指标口径与计算规则:
  - 时间范围: 按自然日统计，统计窗口为当日00:00:00至23:59:59。时区与表的日期分区字段一致（如使用本地时区或统一的UTC+8；需与上游事件时间的时区保持一致）。
  - 活跃判定: 用户在统计窗口内产生至少一条有效行为事件（如应用打开/前台激活/会话开始/登录/核心功能使用等）。具体事件集合由埋点定义与口径版本维护。
  - 唯一标识: 以用户唯一标识去重统计。优先使用用户ID（user_id）；如缺失则使用设备标识（device_id）作为后备。最终去重键为 COALESCE(user_id, device_id)。
  - 去重规则: 在统计窗口内对同一用户仅计数一次（COUNT DISTINCT）。
  - 排除规则: 排除内部测试账号、自动化/机器人流量、异常/黑名单设备与已判定为无效的事件（依据上游清洗标识与名单）。
  - 跨平台合并: 若同一用户在多平台（如 iOS/Android/Web）活跃且用户ID一致，按一个用户计数；若仅有设备标识则按设备维度计数。
- 粒度: 通常按日期×应用维度聚合（例如 dt, app_id）。若表设计包含更多维度（如渠道、地域），dau按对应维度聚合。
- 数据类型: BIGINT（建议）
- 取值范围: 整数，>= 0
- 是否可为空: 否（无数据时应写入0）
- 默认值: 0
- 示例取值: 0, 12345, 678901
- 上游数据/血缘:
  - 来源于应用行为事件事实数据集（包含事件时间、用户标识、事件类型、清洗标签等）。
  - 依赖用户维度数据（用于辨识内部测试用户、合并多标识等）。
  - 依赖流量清洗规则与机器人识别规则（is_bot、is_internal_user、is_valid 等标识）。
- 更新频率与延迟: 日更；通常为T+1批处理生成。若存在迟到事件，可配置T+N回补与重新聚合。
- 质量校验:
  - 非负性校验（dau >= 0）。
  - 趋势与同口径对比（与近7日均值、与上游去重用户数对齐）。
  - 口径一致性校验（事件集合与过滤规则版本一致）。
  - 去重有效性校验（检查重复用户键比例、user_id与device_id覆盖率）。
- 口径版本: v1.0（后续如调整活跃事件集合、过滤规则或唯一标识策略，需记录版本与生效日期）
- 计算示例SQL（模板，需替换为实际表和字段名）:
  - 说明: 以下示例假设事件事实表为 app_event_fact，包含字段 dt, app_id, event_time, event_type, user_id, device_id, is_valid, is_bot, is_internal_user。
  - 示例:
    WITH base AS (
      SELECT
        dt,
        app_id,
        COALESCE(user_id, device_id) AS user_key
      FROM app_event_fact
      WHERE dt = :dt
        AND is_valid = 1
        AND is_bot = 0
        AND is_internal_user = 0
        AND event_type IN ('app_open', 'session_start', 'foreground') -- 按口径维护的事件集合
    )
    SELECT
      dt,
      app_id,
      COUNT(DISTINCT user_key) AS dau
    FROM base
    GROUP BY dt, app_id;

- 注意事项:
  - 保持事件时间的时区与分区字段一致，避免跨日误计。
  - 明确并版本化“有效活跃事件”集合与过滤名单，确保历史可追溯与重算一致性。
  - 在多身份体系场景（匿名ID、登录ID、设备ID），需定义稳定的合并与优先级策略，避免重复或漏计。

Data Dictionary Entry — orders.order_status

- Column name: order_status
- Table: orders
- Purpose: Represents the current lifecycle state of an order for operational processing and analytical reporting.
- Data type: String-based enumerated code (recommended: VARCHAR(20) or database ENUM).
- Format: Uppercase ASCII, underscore-separated where applicable; no leading/trailing spaces.
- Length: Up to 20 characters.
- Nullable: No (must be present for every order).
- Default: PENDING (set at order creation).
- Allowed values and meanings:
  - PENDING: Order created; awaiting payment authorization or validation.
  - CONFIRMED: Payment authorized and order accepted.
  - PROCESSING: Order is being prepared (e.g., picking/packing).
  - SHIPPED: Order handed off to carrier; in transit.
  - DELIVERED: Order confirmed delivered to recipient.
  - CANCELLED: Order cancelled prior to shipment (or by merchant/customer).
  - RETURNED: Order returned after delivery and received/processed.
  - FAILED: Payment or validation failure; order will not proceed.
  - ON_HOLD: Temporarily paused (e.g., fraud review, inventory issue).
- Business rules:
  - The value must be one of the allowed codes; enforce via a CHECK constraint or ENUM.
  - Terminal states: CANCELLED, RETURNED, FAILED. DELIVERED is typically terminal unless returns are allowed; if returns are possible, DELIVERED may transition to RETURNED.
  - Typical state transitions:
    - PENDING → CONFIRMED | CANCELLED | FAILED | ON_HOLD
    - ON_HOLD → PENDING | CONFIRMED | CANCELLED
    - CONFIRMED → PROCESSING | CANCELLED
    - PROCESSING → SHIPPED | CANCELLED
    - SHIPPED → DELIVERED | RETURNED
    - DELIVERED → RETURNED
  - Updates to order_status should be accompanied by a status timestamp (e.g., status_updated_at) for auditability.
- Source/Derivation: Set and updated by the order management or payment/fulfillment services based on event processing; not user-editable.
- Indexing: Consider indexing for common filters (e.g., active orders: PENDING, CONFIRMED, PROCESSING, SHIPPED).
- Data quality checks:
  - Value is non-null and within the allowed domain.
  - Transition validity: disallow illegal transitions (e.g., DELIVERED → SHIPPED).
  - Consistency with related attributes (e.g., SHIPPED requires a carrier/shipment record; DELIVERED requires delivery timestamp).
- Example values: PENDING, PROCESSING, SHIPPED.