首次提交：初始化后端、数据库结构与文档代码

2026-03-23 16:10:29 +08:00
commit 86f384c2d3
95 changed files with 10090 additions and 0 deletions
--- a/sql/migrate_item_price_to_cents.sql
+++ b/sql/migrate_item_price_to_cents.sql
@@ -0,0 +1,20 @@
+-- ================================================
+-- 商品表 price 字段迁移：DECIMAL(12,2) → BIGINT（分）
+-- 执行前提：已有数据的 price/cost_price 含小数点（如 10.00）
+-- 执行顺序：先改类型，再清除已入库的错误数据让重新同步
+-- ================================================
+
+USE youzandatahub;
+
+-- Step 1: 修改字段类型 DECIMAL → BIGINT
+ALTER TABLE `dim_item_sku`
+    MODIFY COLUMN `price` BIGINT DEFAULT 0 COMMENT '当前售卖价（单位：分）',
+    MODIFY COLUMN `cost_price` BIGINT DEFAULT 0 COMMENT '成本价（单位：分，若有）';
+
+-- Step 2: 清除已入库的商品数据（因为旧数据的 price 可能被错误解析）
+-- 重新同步后会自动用正确的分单位入库
+TRUNCATE TABLE `dim_item_sku`;
+
+-- 验证
+-- SELECT COUNT(*) FROM dim_item_sku;  -- 应为 0
+-- 然后调用 GET http://localhost:8080/api/sync/item 重新同步
--- a/sql/phase3_ddl.sql
+++ b/sql/phase3_ddl.sql
@@ -0,0 +1,30 @@
+-- Phase 3 DDL Migration Script
+-- 在已有数据库上执行，补充 Phase 3 新增的字段和表
+-- dim_inventory_snapshot 如果已在之前执行中创建，则此脚本中的 CREATE TABLE 会报 "already exists"，可忽略
+
+USE youzandatahub;
+
+-- 1. dim_offline_store: 新增仓库编码和库存模式字段
+ALTER TABLE dim_offline_store
+  ADD COLUMN warehouse_code VARCHAR(64) DEFAULT NULL COMMENT '仓库编码(库存API必需)',
+  ADD COLUMN stock_mode INT DEFAULT NULL COMMENT '库存模式:1独立,2共享总部,3共享门店仓,4进出存';
+
+-- 2. dwd_trade_refund_detail: 新增退款诉求、阶段、买家ID、修改时间
+ALTER TABLE dwd_trade_refund_detail
+  ADD COLUMN refund_demand INT DEFAULT NULL COMMENT '退款诉求:1仅退款,2退货退款,3换货',
+  ADD COLUMN refund_phase INT DEFAULT NULL COMMENT '退款阶段:1售中,2售后',
+  ADD COLUMN yz_open_id VARCHAR(64) DEFAULT NULL COMMENT '买家yz_open_id',
+  ADD COLUMN modified_time DATETIME DEFAULT NULL COMMENT '最后修改时间';
+
+-- 3. 新建库存快照表 (如已存在则跳过)
+CREATE TABLE IF NOT EXISTS `dim_inventory_snapshot` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+    `warehouse_code` VARCHAR(64) NOT NULL COMMENT '仓库编码',
+    `sku_code` VARCHAR(128) NOT NULL COMMENT 'SKU编码',
+    `stock_num` DECIMAL(12,2) DEFAULT 0 COMMENT '实物库存',
+    `freeze_num` DECIMAL(12,2) DEFAULT 0 COMMENT '实物占用',
+    `available_num` DECIMAL(12,2) DEFAULT 0 COMMENT '可用库存(stock_num-freeze_num)',
+    `snapshot_date` DATE NOT NULL COMMENT '快照日期',
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台同步时间',
+    UNIQUE KEY `uk_snapshot` (`warehouse_code`, `sku_code`, `snapshot_date`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='每日库存快照表';
--- a/sql/phase4_alter_outer_item_id.sql
+++ b/sql/phase4_alter_outer_item_id.sql
@@ -0,0 +1,23 @@
+-- Phase 4 补丁: adm 表增加 outer_item_id 列，用于按商家统一编码聚合
+-- 原因: 有赞连锁模式下，同一个商品在不同门店有不同的 item_id，
+--       只有 outer_item_id (商家编码) 才是全门店统一的商品标识
+
+-- 1. 复购表增加 outer_item_id
+ALTER TABLE `adm_item_repurchase`
+  ADD COLUMN `outer_item_id` VARCHAR(64) DEFAULT NULL COMMENT '商家统一商品编码' AFTER `sku_id`,
+  ADD COLUMN `item_name` VARCHAR(128) DEFAULT NULL COMMENT '商品名称' AFTER `outer_item_id`,
+  DROP INDEX `uk_repurchase_date`,
+  ADD UNIQUE KEY `uk_repurchase_date` (`stat_date`, `outer_item_id`);
+
+-- 2. 购物篮表增加 outer_item_id
+ALTER TABLE `adm_item_basket`
+  ADD COLUMN `outer_item_id_a` VARCHAR(64) DEFAULT NULL COMMENT '商品A商家编码' AFTER `item_id_a`,
+  ADD COLUMN `outer_item_id_b` VARCHAR(64) DEFAULT NULL COMMENT '商品B商家编码' AFTER `item_id_b`,
+  DROP INDEX `uk_item_pair`,
+  ADD UNIQUE KEY `uk_item_pair` (`outer_item_id_a`, `outer_item_id_b`);
+
+-- 3. 销售趋势表增加 outer_item_id
+ALTER TABLE `adm_item_sales_trend`
+  ADD COLUMN `outer_item_id` VARCHAR(64) DEFAULT NULL COMMENT '商家统一商品编码' AFTER `sku_id`,
+  DROP INDEX `uk_trend_date`,
+  ADD UNIQUE KEY `uk_trend_date` (`stat_date`, `outer_item_id`);
--- a/sql/phase4_ddl.sql
+++ b/sql/phase4_ddl.sql
@@ -0,0 +1,97 @@
+-- Phase 4: 商品与会员洞察 (ADM数据市集层)
+
+-- ==========================================
+-- 会员洞察 (Customer Insights)
+-- ==========================================
+
+-- 1. 客户 RFM 与评分模型表
+CREATE TABLE IF NOT EXISTS `adm_customer_rfm` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `yz_open_id` VARCHAR(64) NOT NULL COMMENT '有赞open_id',
+    `mobile` VARCHAR(32) DEFAULT NULL COMMENT '客户手机号',
+    
+    `last_trade_time` DATETIME DEFAULT NULL COMMENT '最近一次消费时间 (Recency)',
+    `trade_count_90d` INT DEFAULT 0 COMMENT '近90天消费频次 (Frequency)',
+    `trade_amount_90d` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '近90天消费金额 (Monetary)',
+    
+    `r_score` INT DEFAULT 0 COMMENT 'R得分(1-5级)',
+    `f_score` INT DEFAULT 0 COMMENT 'F得分(1-5级)',
+    `m_score` INT DEFAULT 0 COMMENT 'M得分(1-5级)',
+    
+    `rfm_group` VARCHAR(32) DEFAULT NULL COMMENT '客群分层(例如: 重要价值客户/沉睡客户等)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '同步更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_yz_open_id` (`yz_open_id`),
+    KEY `idx_rfm_group` (`rfm_group`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员RFM洞察表';
+
+-- 2. 客户标签表 (人群特征画像)
+CREATE TABLE IF NOT EXISTS `adm_customer_tags` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `yz_open_id` VARCHAR(64) NOT NULL,
+    `tag_name` VARCHAR(64) NOT NULL COMMENT '标签名称(如: 工作日外带客, 高客单囤货客)',
+    `tag_value` VARCHAR(128) DEFAULT NULL COMMENT '标签值或权重',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_customer_tag` (`yz_open_id`, `tag_name`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户画像标签表';
+
+
+-- ==========================================
+-- 商品洞察 (Product Insights)
+-- ==========================================
+
+-- 3. 商品销售趋势表 (日维统计)
+CREATE TABLE IF NOT EXISTS `adm_item_sales_trend` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `stat_date` DATE NOT NULL COMMENT '统计归属日期',
+    `item_id` BIGINT NOT NULL COMMENT '商品ID',
+    `sku_id` BIGINT NOT NULL DEFAULT 0 COMMENT '规格ID',
+    `item_name` VARCHAR(128) DEFAULT NULL COMMENT '商品名称',
+    
+    `sales_qty` INT DEFAULT 0 COMMENT '当日销量(件数)',
+    `sales_amount` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '当日销售额',
+    `order_count` INT DEFAULT 0 COMMENT '当日包含该商品的订单数',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_trend_date` (`stat_date`, `item_id`, `sku_id`),
+    KEY `idx_item` (`item_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品销售趋势表';
+
+-- 4. 商品关联分析表 (购物篮挖掘)
+CREATE TABLE IF NOT EXISTS `adm_item_basket` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `item_id_a` BIGINT NOT NULL COMMENT '商品A',
+    `item_name_a` VARCHAR(128) DEFAULT NULL COMMENT '商品A名称',
+    `item_id_b` BIGINT NOT NULL COMMENT '商品B',
+    `item_name_b` VARCHAR(128) DEFAULT NULL COMMENT '商品B名称',
+    
+    `pair_order_count` INT DEFAULT 0 COMMENT 'A和B共同出现的订单数',
+    `item_a_order_count` INT DEFAULT 0 COMMENT 'A独立出现的包含订单总数',
+    `confidence` DECIMAL(5, 4) DEFAULT 0.0000 COMMENT '置信度 (A->B的概率)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_item_pair` (`item_id_a`, `item_id_b`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品购物篮关联分析表';
+
+-- 5. 商品复购分析表
+CREATE TABLE IF NOT EXISTS `adm_item_repurchase` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `stat_date` DATE NOT NULL COMMENT '统计归属日期',
+    `item_id` BIGINT NOT NULL,
+    `sku_id` BIGINT NOT NULL DEFAULT 0,
+    
+    `purchaser_count_30d` INT DEFAULT 0 COMMENT '过去30天购买总人数',
+    `repurchaser_count_30d` INT DEFAULT 0 COMMENT '过去30天产生二次复购的人数',
+    `repurchase_rate_30d` DECIMAL(5, 4) DEFAULT 0.0000 COMMENT '30天复购率 (二次人数/总人数)',
+    
+    `matrix_tag` VARCHAR(32) DEFAULT NULL COMMENT '波士顿矩阵打标分类 (如: 核心引流款, 需淘汰等)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_repurchase_date` (`stat_date`, `item_id`, `sku_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品复购率分析表';
--- a/sql/youzan_tplus1_ddl.sql
+++ b/sql/youzan_tplus1_ddl.sql
@@ -0,0 +1,354 @@
+-- 交易明细事实表 (dwd_trade_order_detail)
+-- 用于拉取有赞 trades.sold.get 等接口数据，基于订单明细粒度（SKU级别）
+CREATE TABLE `dwd_trade_order_detail` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '底层自增主键',
+    `tid` VARCHAR(64) NOT NULL COMMENT '有赞主订单号 (tid)',
+    `oid` VARCHAR(64) NOT NULL COMMENT '有赞子订单号/明细ID (oid)',
+    
+    `buyer_phone` VARCHAR(32) DEFAULT NULL COMMENT '买家手机号 (buyer_info.buyer_phone)，基于安全组件可能脱敏',
+    `yz_open_id` VARCHAR(64) DEFAULT NULL COMMENT '有赞用户开放ID (buyer_info.yz_open_id)',
+    `fans_id` BIGINT DEFAULT NULL COMMENT '粉丝ID (buyer_info.fans_id)',
+    
+    `shop_org_id` VARCHAR(64) DEFAULT NULL COMMENT '店铺组织ID (shop_org_id)',
+    `offline_id` BIGINT DEFAULT NULL COMMENT '网点/门店ID (node_kdt_id)',
+    
+    `item_id` BIGINT NOT NULL COMMENT '商品ID (item_id)',
+    `sku_id` BIGINT NOT NULL COMMENT 'SKU ID (sku_id)',
+    `outer_item_id` VARCHAR(128) DEFAULT NULL COMMENT '商家外部商品编码 (outer_item_id) - 核心映射字段',
+    `outer_sku_id` VARCHAR(128) DEFAULT NULL COMMENT '商家外部SKU编码 (outer_sku_id)',
+    `title` VARCHAR(255) DEFAULT NULL COMMENT '商品名称快照 (title)',
+    
+    `price` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '单商品原价 (price)',
+    `num` INT NOT NULL DEFAULT 0 COMMENT '购买数量 (num)',
+    `total_fee` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '该明细原价小计 (total_fee = price * num)',
+    `discount_price` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '单商品折扣后价格 (discount_price)',
+    `payment` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '该明细实际支付摊销金额 (payment) - 计算销售额核心',
+    
+    `status` VARCHAR(32) NOT NULL COMMENT '当前主订单状态 (status: WAIT_SELLER_SEND_GOODS 等)',
+    `refund_state` INT DEFAULT 0 COMMENT '退款状态 (refund_state: 0正常, 其他视情况)',
+    
+    `source_platform` VARCHAR(32) DEFAULT NULL COMMENT '订单来源平台 (source_info.source.platform: weixin/other)',
+    `is_retail_order` TINYINT(1) DEFAULT 0 COMMENT '是否零售门店订单 (order_info.is_retail_order)',
+    `order_type` INT DEFAULT 0 COMMENT '订单类型 (order_info.type: 0-普通 10-零售门店)',
+    
+    `pay_time` DATETIME DEFAULT NULL COMMENT '支付时间 (pay_time) - 业务时间戳',
+    `created_time` DATETIME DEFAULT NULL COMMENT '订单创建时间 (created)',
+    `update_time` DATETIME DEFAULT NULL COMMENT '订单最后更新时间 (update_time)',
+    `success_time` DATETIME DEFAULT NULL COMMENT '订单完成时间 (success_time)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台数据更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_oid` (`oid`),
+    KEY `idx_tid` (`tid`),
+    KEY `idx_pay_time` (`pay_time`),
+    KEY `idx_update_time` (`update_time`),
+    KEY `idx_buyer` (`buyer_phone`, `yz_open_id`),
+    KEY `idx_item_sku` (`item_id`, `sku_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='交易明细事实表 (T+1有赞同步)';
+
+-- 客户维度宽表 (dim_customer_info)
+-- 用于融合有赞买家、微信粉丝、线下POS留资，构建 OneID 视图及基础标签
+CREATE TABLE `dim_customer_info` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '中台内部统一客户ID (OneID)',
+    
+    `mobile` VARCHAR(32) DEFAULT NULL COMMENT '手机号（首选关联枢纽，微信粉丝场景可能缺失）',
+    `yz_open_id` VARCHAR(64) DEFAULT NULL COMMENT '有赞生态统一用户ID（备选主键）',
+    `wx_union_id` VARCHAR(64) DEFAULT NULL COMMENT '微信生态UnionID',
+    `wx_open_id` VARCHAR(64) DEFAULT NULL COMMENT '微信公众号/小程序OpenID',
+    
+    `nickname` VARCHAR(128) DEFAULT NULL COMMENT '客户昵称快照 (fans_nickname)',
+    `name` VARCHAR(64) DEFAULT NULL COMMENT '客户真实姓名（若有）',
+    `gender` TINYINT DEFAULT 0 COMMENT '性别: 0-未知, 1-男, 2-女',
+    `birthday` DATE DEFAULT NULL COMMENT '生日',
+    
+    `register_time` DATETIME DEFAULT NULL COMMENT '首次注册/留资时间',
+    `register_channel` VARCHAR(32) DEFAULT NULL COMMENT '注册渠道 (有赞、线下门店、微信等)',
+    
+    `member_level_id` BIGINT DEFAULT NULL COMMENT '当前会员等级ID',
+    `member_level_name` VARCHAR(64) DEFAULT NULL COMMENT '当前会员等级名称',
+    
+    `first_pay_time` DATETIME DEFAULT NULL COMMENT '首单支付时间',
+    `last_pay_time` DATETIME DEFAULT NULL COMMENT '最近一次支付时间（用于RFM-R计算）',
+    `total_pay_amount` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '历史累计实付金额（用于RFM-M计算）',
+    `total_pay_count` INT DEFAULT 0 COMMENT '历史累计支付订单数（用于RFM-F计算）',
+    
+    `customer_tags` JSON DEFAULT NULL COMMENT '客户身上的业务标签集合 (JSON格式存储，如 ["高潜", "流失预警"])',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台数据更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_yz_open_id` (`yz_open_id`),
+    UNIQUE KEY `uk_mobile` (`mobile`),  -- 可空唯一: MySQL 允许多个 NULL, 有手机号则保证不重复
+    KEY `idx_wx_union_id` (`wx_union_id`),
+    KEY `idx_last_pay_time` (`last_pay_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='统一客户维度宽表 (OneID及基础RFM视角)';
+
+-- ==========================================
+-- 新增：商品维表、门店维表、库存流水、退货退款明细
+-- ==========================================
+
+-- 商品与SKU维表 (dim_item_sku)
+-- 记录有赞商品的快照及外部映射，用以统一冷链和热食的销售分析
+CREATE TABLE `dim_item_sku` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `item_id` BIGINT NOT NULL COMMENT '有赞商品ID (item_id)',
+    `sku_id` BIGINT NOT NULL COMMENT '有赞SKU ID (sku_id)',
+    
+    `outer_item_id` VARCHAR(128) DEFAULT NULL COMMENT '商家外部商品编码 (关联核心)',
+    `outer_sku_id` VARCHAR(128) DEFAULT NULL COMMENT '商家外部SKU编码',
+    `barcode` VARCHAR(128) DEFAULT NULL COMMENT '商品条码',
+    
+    `title` VARCHAR(255) NOT NULL COMMENT '商品/SKU名称',
+    `alias` VARCHAR(128) DEFAULT NULL COMMENT '商品别名/短链接标识',
+    
+    `category_id` BIGINT DEFAULT NULL COMMENT '叶子类目ID',
+    `category_name` VARCHAR(128) DEFAULT NULL COMMENT '叶子类目名称',
+    `group_ids` VARCHAR(255) DEFAULT NULL COMMENT '商品分组ID列表 (逗号分隔)',
+    
+    `price` BIGINT DEFAULT 0 COMMENT '当前售卖价（单位：分）',
+    `cost_price` BIGINT DEFAULT 0 COMMENT '成本价（单位：分，若有）',
+    
+    `is_listing` TINYINT(1) DEFAULT 1 COMMENT '是否上架: 1-上架, 0-下架',
+    `created_time` DATETIME DEFAULT NULL COMMENT '商品在有赞的创建时间',
+    `update_time` DATETIME DEFAULT NULL COMMENT '商品最近更新时间',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台数据更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_item_sku` (`item_id`, `sku_id`),
+    KEY `idx_outer_item_id` (`outer_item_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品与SKU维度表';
+
+
+-- 门店与网点维表 (dim_offline_store)
+CREATE TABLE `dim_offline_store` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `offline_id` BIGINT NOT NULL COMMENT '有赞网点/门店ID (offline_id / node_kdt_id)',
+    `shop_org_id` VARCHAR(64) DEFAULT NULL COMMENT '组织店铺ID',
+    
+    `name` VARCHAR(128) NOT NULL COMMENT '门店名称',
+    `type` VARCHAR(32) DEFAULT NULL COMMENT '节点类型: STORE-门店, WAREHOUSE-仓库',
+    
+    `province` VARCHAR(64) DEFAULT NULL COMMENT '省份',
+    `city` VARCHAR(64) DEFAULT NULL COMMENT '城市',
+    `district` VARCHAR(64) DEFAULT NULL COMMENT '区县',
+    `address` VARCHAR(255) DEFAULT NULL COMMENT '详细地址',
+    
+    `status` TINYINT(1) DEFAULT 1 COMMENT '营业状态: 1-营业, 0-关店',
+    `warehouse_code` VARCHAR(64) DEFAULT NULL COMMENT '仓库编码 (库存API必需, warehouse.query获取)',
+    `stock_mode` INT DEFAULT NULL COMMENT '库存模式: 1-独立销售库存, 2-共享总部, 3-共享门店仓, 4-进出存单据管理',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台数据更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_offline_id` (`offline_id`),
+    KEY `idx_city` (`city`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='门店与网点维度表';
+
+
+-- 售后与退款明细事实表 (dwd_trade_refund_detail)
+-- 用于计算交易净额 (GMV = 支付额 - 退款额)
+CREATE TABLE `dwd_trade_refund_detail` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `refund_id` VARCHAR(64) NOT NULL COMMENT '退款单号 (refund_id)',
+    `tid` VARCHAR(64) NOT NULL COMMENT '关联的有赞主订单号 (tid)',
+    `oid` VARCHAR(64) DEFAULT NULL COMMENT '关联的子订单明细ID (oid, 若仅退款则为空)',
+    
+    `offline_id` BIGINT DEFAULT NULL COMMENT '发起退款的门店ID (处理多网点)',
+    
+    `refund_type` INT DEFAULT 1 COMMENT '退款类型: 1-仅退款, 2-退货退款',
+    `refund_fee` DECIMAL(12, 2) NOT NULL DEFAULT 0.00 COMMENT '实际退款金额',
+    `reason` VARCHAR(255) DEFAULT NULL COMMENT '退款原因 (整数编码: 54-未发货, 11-质量问题等)',
+    
+    `status` VARCHAR(32) NOT NULL COMMENT '退款状态 (SUCCESS/CLOSED/WAIT_SELLER_AGREE等)',
+    `created_time` DATETIME DEFAULT NULL COMMENT '退款申请时间',
+    `success_time` DATETIME DEFAULT NULL COMMENT '退款成功时间',
+    `modified_time` DATETIME DEFAULT NULL COMMENT '退款最后修改时间',
+    
+    `refund_demand` INT DEFAULT NULL COMMENT '退款诉求: 1-仅退款, 2-退货退款, 3-换货',
+    `refund_phase` INT DEFAULT NULL COMMENT '退款阶段: 1-售中, 2-售后',
+    `yz_open_id` VARCHAR(64) DEFAULT NULL COMMENT '买家有赞用户ID (yz_open_id)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台数据更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_refund_id` (`refund_id`),
+    KEY `idx_tid` (`tid`),
+    KEY `idx_success_time` (`success_time`),
+    KEY `idx_yz_open_id` (`yz_open_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='售后与退款明细表';
+
+
+-- 每日库存快照表 (dim_inventory_snapshot)
+-- 记录每日各仓库/门店的SKU库存余量，用于库存周转分析和缺货预警
+CREATE TABLE `dim_inventory_snapshot` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `warehouse_code` VARCHAR(64) NOT NULL COMMENT '仓库编码 (warehouse.query获取)',
+    `sku_code` VARCHAR(128) NOT NULL COMMENT 'SKU编码 (outer_sku_id)',
+    `stock_num` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '实物库存数量',
+    `freeze_num` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '实物库存占用 (被订单锁定)',
+    `available_num` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '可用库存 (stock_num - freeze_num)',
+    `snapshot_date` DATE NOT NULL COMMENT '快照日期',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台同步时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_snapshot` (`warehouse_code`, `sku_code`, `snapshot_date`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='每日库存快照表';
+
+
+-- 进销存库存流水事实表 (dwd_inventory_flow_di)
+-- 记录每日出入库流水，辅助动销分析与损耗监控
+CREATE TABLE `dwd_inventory_flow_di` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `biz_no` VARCHAR(64) NOT NULL COMMENT '业务单据号 (如盘点单号, 采购单号)',
+    `biz_type` VARCHAR(32) NOT NULL COMMENT '单据类型: PURCHASE-采购, ALLOCATE-调拨, CHECK-盘点, ADJUST-调整',
+    
+    `offline_id` BIGINT NOT NULL COMMENT '发生动作的门店/仓库ID',
+    `item_id` BIGINT NOT NULL COMMENT '商品ID',
+    `sku_id` BIGINT NOT NULL COMMENT 'SKU ID',
+    
+    `change_quantity` INT NOT NULL COMMENT '库存变动量 (正数为入, 负数为出)',
+    `after_quantity` INT DEFAULT NULL COMMENT '变动后该SKU的总可用库存',
+    `reason` VARCHAR(255) DEFAULT NULL COMMENT '变动原因 (如报损说明, 盘点原因)',
+    
+    `occur_time` DATETIME NOT NULL COMMENT '流水发生时间',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台同步时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_biz_flow` (`biz_no`, `item_id`, `sku_id`, `offline_id`, `biz_type`),
+    KEY `idx_offline_sku` (`offline_id`, `sku_id`),
+    KEY `idx_occur_time` (`occur_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='库存变动流水记录表';
+
+
+-- ==========================================
+-- 新增：优惠券/营销活动事实表
+-- ==========================================
+
+-- 优惠券流水事实表 (dwd_coupon_flow)
+-- 记录优惠券的发放与核销，用于活动ROI分析
+CREATE TABLE `dwd_coupon_flow` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `coupon_group_id` BIGINT NOT NULL COMMENT '优惠券活动/券组ID (coupon_group_id)',
+    `coupon_id` VARCHAR(64) NOT NULL COMMENT '优惠券实例ID / 券码 (verify_code)',
+    
+    `yz_open_id` VARCHAR(64) DEFAULT NULL COMMENT '领券/用券用户 (yz_open_id)',
+    `mobile` VARCHAR(32) DEFAULT NULL COMMENT '用户手机号',
+    
+    `coupon_type` VARCHAR(32) DEFAULT NULL COMMENT '券类型: CASH-满减, DISCOUNT-折扣, EXCHANGE-兑换',
+    `coupon_name` VARCHAR(128) DEFAULT NULL COMMENT '券名称',
+    `denomination` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '面额/减免金额',
+    `condition_amount` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '使用门槛金额 (满X元可用)',
+    
+    `send_time` DATETIME DEFAULT NULL COMMENT '发放时间',
+    `use_time` DATETIME DEFAULT NULL COMMENT '核销/使用时间',
+    `expire_time` DATETIME DEFAULT NULL COMMENT '过期时间',
+    
+    `status` VARCHAR(32) NOT NULL COMMENT '券状态: SENT-已发, USED-已核销, EXPIRED-已过期',
+    `use_tid` VARCHAR(64) DEFAULT NULL COMMENT '核销时关联的订单号 (tid)',
+    `use_offline_id` BIGINT DEFAULT NULL COMMENT '核销门店ID (offline_id)',
+    
+    `activity_id` BIGINT DEFAULT NULL COMMENT '关联营销活动ID (activity_id)',
+    `activity_type` VARCHAR(32) DEFAULT NULL COMMENT '活动类型',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '中台同步时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_coupon_id` (`coupon_id`),
+    KEY `idx_coupon_group` (`coupon_group_id`),
+    KEY `idx_yz_open_id` (`yz_open_id`),
+    KEY `idx_use_time` (`use_time`),
+    KEY `idx_use_tid` (`use_tid`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='优惠券流水事实表 (发放与核销)';
+
+
+-- ==========================================
+-- Phase 4: 商品与会员洞察 (ADM数据市集层)
+-- ==========================================
+
+-- 1. 客户 RFM 与评分模型表
+CREATE TABLE IF NOT EXISTS `adm_customer_rfm` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '自增主键',
+    `yz_open_id` VARCHAR(64) NOT NULL COMMENT '有赞open_id',
+    `mobile` VARCHAR(32) DEFAULT NULL COMMENT '客户手机号',
+    
+    `last_trade_time` DATETIME DEFAULT NULL COMMENT '最近一次消费时间 (Recency)',
+    `trade_count_90d` INT DEFAULT 0 COMMENT '近90天消费频次 (Frequency)',
+    `trade_amount_90d` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '近90天消费金额 (Monetary)',
+    
+    `r_score` INT DEFAULT 0 COMMENT 'R得分(1-5级)',
+    `f_score` INT DEFAULT 0 COMMENT 'F得分(1-5级)',
+    `m_score` INT DEFAULT 0 COMMENT 'M得分(1-5级)',
+    
+    `rfm_group` VARCHAR(32) DEFAULT NULL COMMENT '客群分层(例如: 重要价值客户/沉睡客户等)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '同步更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_yz_open_id` (`yz_open_id`),
+    KEY `idx_rfm_group` (`rfm_group`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员RFM洞察表';
+
+-- 2. 客户标签表 (人群特征画像)
+CREATE TABLE IF NOT EXISTS `adm_customer_tags` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `yz_open_id` VARCHAR(64) NOT NULL,
+    `tag_name` VARCHAR(64) NOT NULL COMMENT '标签名称(如: 工作日外带客, 高客单囤货客)',
+    `tag_value` VARCHAR(128) DEFAULT NULL COMMENT '标签值或权重',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_customer_tag` (`yz_open_id`, `tag_name`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户画像标签表';
+
+-- 3. 商品销售趋势表 (日维统计, 按 outer_item_id 聚合)
+CREATE TABLE IF NOT EXISTS `adm_item_sales_trend` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `stat_date` DATE NOT NULL COMMENT '统计归属日期',
+    `item_id` BIGINT NOT NULL COMMENT '商品ID (代表性)',
+    `sku_id` BIGINT NOT NULL DEFAULT 0 COMMENT '规格ID',
+    `outer_item_id` VARCHAR(64) DEFAULT NULL COMMENT '商家统一商品编码',
+    `item_name` VARCHAR(128) DEFAULT NULL COMMENT '商品名称',
+    
+    `sales_qty` INT DEFAULT 0 COMMENT '当日销量(件数)',
+    `sales_amount` DECIMAL(12, 2) DEFAULT 0.00 COMMENT '当日销售额',
+    `order_count` INT DEFAULT 0 COMMENT '当日包含该商品的订单数',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_trend_date` (`stat_date`, `outer_item_id`),
+    KEY `idx_item` (`item_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品销售趋势表';
+
+-- 4. 商品关联分析表 (购物篮挖掘, 按 outer_item_id 聚合)
+CREATE TABLE IF NOT EXISTS `adm_item_basket` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `item_id_a` BIGINT NOT NULL COMMENT '商品A',
+    `outer_item_id_a` VARCHAR(64) DEFAULT NULL COMMENT '商品A商家编码',
+    `item_name_a` VARCHAR(128) DEFAULT NULL COMMENT '商品A名称',
+    `item_id_b` BIGINT NOT NULL COMMENT '商品B',
+    `outer_item_id_b` VARCHAR(64) DEFAULT NULL COMMENT '商品B商家编码',
+    `item_name_b` VARCHAR(128) DEFAULT NULL COMMENT '商品B名称',
+    
+    `pair_order_count` INT DEFAULT 0 COMMENT 'A和B共同出现的订单数',
+    `item_a_order_count` INT DEFAULT 0 COMMENT 'A独立出现的包含订单总数',
+    `confidence` DECIMAL(5, 4) DEFAULT 0.0000 COMMENT '置信度 (A->B的概率)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_item_pair` (`outer_item_id_a`, `outer_item_id_b`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品购物篮关联分析表';
+
+-- 5. 商品复购分析表 (按 outer_item_id 聚合)
+CREATE TABLE IF NOT EXISTS `adm_item_repurchase` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT,
+    `stat_date` DATE NOT NULL COMMENT '统计归属日期',
+    `item_id` BIGINT NOT NULL COMMENT '商品ID (代表性)',
+    `sku_id` BIGINT NOT NULL DEFAULT 0,
+    `outer_item_id` VARCHAR(64) DEFAULT NULL COMMENT '商家统一商品编码',
+    `item_name` VARCHAR(128) DEFAULT NULL COMMENT '商品名称',
+    
+    `purchaser_count_30d` INT DEFAULT 0 COMMENT '过去30天购买总人数',
+    `repurchaser_count_30d` INT DEFAULT 0 COMMENT '过去30天产生二次复购的人数',
+    `repurchase_rate_30d` DECIMAL(5, 4) DEFAULT 0.0000 COMMENT '30天复购率 (二次人数/总人数)',
+    
+    `matrix_tag` VARCHAR(32) DEFAULT NULL COMMENT '波士顿矩阵打标分类 (如: 核心引流款, 需淘汰等)',
+    
+    `etl_update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_repurchase_date` (`stat_date`, `outer_item_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品复购率分析表';