本体+AI大模型驱动的电商数据分析报告生成方案加具体实现

┌─────────────────────────────────────────────────────────┐
│                    分析报告层                            │
│   (Markdown + ECharts 图表 + 可执行建议)                 │
├─────────────────────────────────────────────────────────┤
│                    AI推理层                              │
│   LLM语义推理 · 模式识别 · 因果推断                      │
│   所有结论引用本体规则 + SQL溯源                          │
├─────────────────────────────────────────────────────────┤
│                    数据计算层                            │
│   SQL确定性计算 · 统计算法 · 指标聚合                     │
│   不依赖LLM，确保数值精确                                │
├─────────────────────────────────────────────────────────┤
│                    语义映射层（外部）                     │
│   实体→表字段映射 · 指标→SQL模板映射 · 置信度标注         │
│   零侵入：不修改源数据库任何表结构                        │
├─────────────────────────────────────────────────────────┤
│                    本体模型层                            │
│   M1 对象模型 · M2 行为模型 · M3 规则模型                │
│   M_Metric 指标模型 · M4 场景模型 · M5 主体模型          │
├─────────────────────────────────────────────────────────┤
│                    数据源层                              │
│   现有电商数据库 (SQLite / MySQL / PostgreSQL)            │
└─────────────────────────────────────────────────────────┘

步骤一：提出分析需求 ──────── 业务方以自然语言描述分析目标
  ↓
步骤二：AI 细化需求 ──────── 梳理指标体系、数据对象、关系、规则
  ↓
步骤三：本体建模 ──────────── M1–M5 + M_Metric 六模型体系
  ↓
步骤四：数据库映射 ────────── 本体实体/指标 → 数据库表字段映射
  ↓
步骤五：模板构建 ──────────── 报告结构 · 指标配置 · 展示规范
  ↓
步骤六：AI 驱动报告生成 ───── 数据采集 → 推理分析 → 报告输出

交易域：Order(订单) ──< OrderItem(订单明细) ──< Payment(支付记录)
商品域：Product(SPU) ──< ProductSKU(SKU) ──< Category(类目)
用户域：User(用户) ──< UserBehavior(行为记录)
店铺域：Shop(店铺)
营销域：Campaign(活动) ──< Coupon(优惠券)
流量域：Session(访问会话)

- id:MTR-USR-006                    # 唯一标识
name:用户流失率                    # 中文名
formula:"上月活跃且本月未活跃 / 上月活跃用户数"# 计算公式
dependsOn:[ENT-USR-001,ENT-USR-002,ENT-ORD-001]# 依赖的M1实体
ruleRefs:[RULE-USR-001,RULE-USR-002]              # 依赖的M3规则
grains:[月]                       # 支持的统计粒度
dimensions:[用户等级,地区,注册渠道]# 可拆分维度
computationType:SQL_COMPUTE       # SQL_COMPUTE / STAT_ALGO / LLM_REASONING
defaultVisualization:bar_chart    # 默认图表类型
tags:[用户质量,风险指标]

- id:RULE-USR-002
name:流失用户定义
ruleType:VALIDATION
description:|
    月流失：上月活跃但本月未活跃的用户
    流失率 = 流失用户数 / 上月活跃用户数
inputParams:
    -name:wasActiveLastMonth
      type:Boolean
    -name:isActiveThisMonth
      type:Boolean
outputType:Boolean
expression: |
    wasActiveLastMonth == true AND isActiveThisMonth == false

本体层                    映射层                      数据库层
───────                  ──────                      ────────
ENT-ORD-001.Order  ←──  entity_mappings  ──→  t_order 表
  .orderId         ←──  field_mappings   ──→  order_id 列
  .orderStatus     ←──  value_mapping    ──→  status (枚举值映射)
  .payAmount       ←──  field_mappings   ──→  pay_amount 列
  [有效订单]        ←──  default_filter  ──→  status NOT IN ('cancelled', 'refund_only')

MTR-TXN-001.GMV    ←──  metric_sql_mappings ──→  SELECT SUM(pay_amount) ...
  .dimensions      ←──  supported_dimensions ──→  LEFT JOIN + GROUP BY
  .traceability    ←──  rule_refs         ──→  RULE-MTR-001 (GMV口径)

entity_mappings:
  -ontology_entity:ENT-ORD-001        # 映射目标：订单实体
    confidence:0.97                    # 整体映射置信度
    db_tables:
      -table:"t_order"
        alias:"ord"
        primary:true
    field_mappings:
      -ontology_field:orderStatus     # 本体字段
        db_expression:"ord.status"     # 数据库表达式
        confidence:0.85               # ⚠️ 低置信度
        value_mapping:                 # 枚举值映射
          "1":"待付款"
          "2":"已付款"
          ...
        note:"需与业务方确认状态码含义"
      -ontology_field:payAmount
        db_expression:"ord.pay_amount"
        confidence:0.95
    default_filter:"ord.status NOT IN ('5', '6')"# 对应 RULE-MTR-001

metric_sql_mappings:
  -metric_id:MTR-USR-006             # 用户流失率
    sql_template:|
      WITH last_month_active AS (
        SELECT DISTINCT user_id FROM t_user_behavior
        WHERE created_at BETWEEN '{lm_start}' AND '{lm_end}'
        UNION
        SELECT DISTINCT user_id FROM t_order
        WHERE created_at BETWEEN '{lm_start}' AND '{lm_end}'
          AND order_status NOT IN ('cancelled', 'refund_only')
      ),
      this_month_active AS (...)
      SELECT
        (SELECT COUNT(*) FROM last_month_active) AS base_active,
        (SELECT COUNT(*) FROM lma LEFT JOIN tma ...) AS churned,
        ROUND(...*100.0/..., 2) AS churn_rate
    supported_dimensions:
      -name:用户等级
        dimension_sql:"SELECT usr.user_level, ... GROUP BY usr.user_level"
      -name:注册渠道
        dimension_sql:"SELECT usr.register_channel, ... GROUP BY usr.register_channel"
    traceability:
      ontology_refs:[ENT-USR-001,ENT-USR-002,ENT-ORD-001]
      rule_refs:[RULE-USR-001,RULE-USR-002]
      mapping_refs:[ENT-ORD-001.payAmount,ENT-ORD-001.orderStatus]

# 手机配件店铺(8,9)在3月的售后率加权提高
if is_march and shop_id in PROBLEM_SHOPS:
    order_status = random.choices(
        ["completed", "completed", "completed", "refund_only", "return_refund"],
        weights=[40, 20, 10, 15, 15]  # 售后权重30% vs 正常3%
    )[0]

# 移除约800名用户在3月的所有行为和订单
# 其中VIP1用户200名、短视频渠道用户100名
# 使流失率达到17.1%

# 头部服饰店铺25%的SKU在3月标记缺货
if shop_id in HEAD_SHOPS and cat_id in FASHION_CATS:
    if random.random() < 0.25:
        stock = 0
        sale_status = "out_of_stock"

# 3月第3周跳过约35%的服饰店铺订单
if is_gmv_drop_week and shop_id in HEAD_SHOPS:
    if random.random() < 0.35:
        continue# 不生成该订单

# 搜索渠道转化率降低
if source == "搜索"and is_gmv_drop_week:
    has_order = 1if random.random() < 0.03else0# 3% vs 正常8%

# 新人券占35%预算但使用率低
campaign3_config = [
    ("满减券", 199, 40, 0.25),
    ("新人券", 99, 30, 0.25),    # 25%数量占比，但效率低
    ("品牌券", 300, 50, 0.15),    # 15%数量占比，但ROI最高
    ...
]

-- 验证手机配件售后率
SELECT cat.category_name,
       COUNT(CASE WHEN ord.order_status IN ('refund_only','return_refund') THEN 1 END) * 1.0 / COUNT(*)
FROM t_order ord ... WHERE cat.parent_id = 22  -- 手机配件
-- 结果：手机壳15.21%, 贴膜18.74%, 充电器16.29%, 数据线16.80%

-- 验证GMV周期差异
-- 结果：3月第3周 GMV = 12,496,706；其他周均值 = 18,147,065

RULE-MTR-004 分解规则：
GMV变化 = 订单量效应 + 客单价效应
订单量效应 = (当期订单数 - 基期订单数) × 基期客单价
客单价效应 = (当期客单价 - 基期客单价) × 当期订单数

volume_effect = (current_orders - baseline_orders) * baseline_atv
price_effect = (current_atv - baseline_atv) * current_orders
volume_share = volume_effect / gmv_change    # 订单量贡献百分比
price_share = price_effect / gmv_change      # 客单价贡献百分比

GMV下降
  → M_Metric.dimensions: [类目, 渠道, 店铺, 地区]
  → 按类目下钻: Order → OrderItem → Product → Category
    发现"服饰鞋包"GMV下降最大(-35%)
  → 关联MTR-PRD-004(缺货率):
    Product → ProductSKU.saleStatus
    发现服饰店铺缺货率22%
  → 关联MTR-TFC-002(转化率):
    Session → Order
    发现搜索渠道转化率从8.2%降至5.1%
  → 关联MTR-TXN-003(客单价):
    发现美妆类目客单价下降24%

推理步骤详情
├── Step 1: 本体加载
│   └── 加载了哪些实体、规则、指标定义
├── Step 2: SQL数据采集
│   └── 执行的SQL语句、返回行数、溯源信息
├── Step 3: 统计分析
│   └── 使用的算法、参数、中间结果
├── Step 4: 本体关系导航
│   └── 跨域关联的实体路径（如：User→Order→Shop→Category）
├── Step 5: 模式识别
│   └── 触发阈值、匹配的规则、识别的异常
├── Step 6: AI因果推理
│   └── 推理链（数据观察→模式识别→因果推断）、置信度评估
└── Step 7: 行动建议生成
    └── 建议的优先级排序依据

sections:
  -section_id:SEC-001
    title:一、活动ROI总览
    type:metric_cards
    cards:
      -label:实际ROI
        value:"${roi_summary.roi}"
        change:"${roi_summary.achieved ? 'up' : 'down'}"
        description:"目标ROI: ${roi_summary.target_roi}"

-section_id:SEC-002
    title:二、优惠券效率分析
    type:charts
    charts:
      -id:coupon_subsidy
        chart_type:pie
        data_from:"${mkt_data.coupon_efficiency}"
        pie_name_field:coupon_type
        pie_value_field:total_subsidy

class TemplateEngine:
    def render(self, scenario: str, context: dict) -> dict:
        template = self.load_template(scenario)     # 加载YAML模板
        sections = []
        for sec in template["sections"]:
            if self._eval_condition(sec, context):  # 条件检查
                rendered = self._render_section(sec, context)
                sections.append(rendered)
        return {
            "report_meta": { ... },
            "sections": sections,
            "data_lineage": template["data_lineage"],
            "ontology_references": template["ontology_model_used"],
        }

backend/
├── app.py                 # FastAPI主程序（3场景API + 本体查询API + 推理文档导出）
├── ontology_loader.py     # 本体模型加载器（加载YAML → 索引 → 查询接口）
├── analysis_engine.py     # 分析引擎（SQL执行 + 统计计算 + 数据采集）
├── ontology_reasoner.py   # 本体推理器（模式识别 + 因果推断 + 建议生成）
├── template_loader.py     # 模板引擎（YAML加载 + 表达式求值 + 图表配置生成）
├── report_generator.py    # 报告生成器（构建数据上下文 → 调用模板引擎）
└── reasoning_logger.py    # 推理过程记录（Markdown文档生成）

GET /api/health                          — 健康检查
GET /api/scenario/churn?month=2026-03    — 场景一：用户流失诊断
GET /api/scenario/gmv?start=...&end=...  — 场景二：GMV归因分析
GET /api/scenario/marketing?campaign_id=3 — 场景三：营销ROI评估
GET /api/reasoning-doc/churn             — 导出推理过程Markdown文档
GET /api/ontology/entities               — 列出所有本体实体
GET /api/ontology/metrics                — 列出所有指标定义
GET /api/ontology/rules                  — 列出所有业务规则

{
  "scenario": "用户流失异常诊断",
"report": {
    "report_meta": { "template_id": "TPL-CHURN-001", ... },
    "sections": [ { "section_id": "SEC-001", "type": "metric_cards", ... } ],
    "data_lineage": { "MTR-USR-006": "SQLite CTE ...", ... },
    "ontology_references": { "entities": [...], "rules": [...] }
  },
"reasoning_process": {
    "steps": [ ... ],
    "ontology_references": { ... },
    "key_ontology_insight": "AI通过本体M3规则模型..."
  }
}

App
├── TopErrorBoundary              ← 顶层崩溃兜底
├── ScenarioSelector              ← 三个场景切换按钮
├── ReportView                    ← 报告主容器
│   ├── ReportMetaBar             ← 场景名/时间/活动信息
│   ├── SectionErrorBoundary × N  ← 每个区块独立容错
│   │   ├── MetricCardView        ← 指标卡片
│   │   ├── ChartBlock            ← ECharts图表（bar/pie/hbar/line）
│   │   ├── SafeTable             ← 数据表格
│   │   ├── SafeInsight           ← AI推理结论面板
│   │   └── RecItemView           ← 行动建议项
│   ├── DataLineage               ← 数据溯源表
│   └── ReasoningPanel            ← AI推理过程面板
└── LoadingState / ErrorState     ← 加载/错误状态