Data Agent 产品设计文档¶

触达活动描述（背景/主题/人群/目标）
    ↓
智能圈选目标人群（AI 推理 + CDP 标签）
    ↓
生成营销方案（多方案对比）
    ↓
触达策略生成（时机/通道/内容）
    ↓
触达任务配置（受众/触发条件/触达配置）
    ↓
个性化触达执行（匹配最优时机/物料/权益）
    ↓
数据分析与动态优化

┌─────────────────────────────────────────────────────┐
│                    User Interface                    │
│   (Web Chat / API / Dashboard / 定时推送)            │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              Data Agent Orchestrator                 │
│  (意图分类 → 路由 → 多Agent协同 → 结果聚合)           │
└──────┬─────────────────┬─────────────────┬──────────┘
       │                 │                 │
┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
│  智能问数Agent │  │ 营销策略Agent │  │  深度研究Agent│
│  (NL2SQL引擎) │  │ (CDP集成)    │  │ (多轮分析)    │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
│  SQL Parser  │  │  客群构建引擎 │  │  Python执行器 │
│  语义模型    │  │  策略生成引擎 │  │  报告生成器  │
│  归因分析    │  │  触达优化    │  │            │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                 │
┌──────▼───────────────▼─────────────────▼──────┐
│              Data Source Layer                │
│  ClickHouse / Doris / MySQL / Hologres / CDW │
└──────────────────────────────────────────────┘

用户问题（自然语言）
    ↓
意图理解 + 实体识别 + 上下文补全（多轮对话上下文）
    ↓
语义模型解析（业务术语 → 物理表字段映射）
    ↓
SQL 生成（LLM + Few-shot + Schema Constraint）
    ↓
SQL 校验 + 执行
    ↓
结果处理（聚合/筛选/排序）
    ↓
可视化选择（根据数据特征 + 用户问题关键词推荐图表）
    ↓
归因分析（如用户触发）
    ↓
数据解读（AI 生成自然语言解读）
    ↓
返回结果

触达活动描述（输入）
    ↓
AI 深度思考模块
  - 业务意图推理
  - 目标拆解为可执行指标
  - 行业实践知识检索
  - 画像标签识别策略
    ↓
客群构建（CDP 集成）
  - 标签组合查询
  - 客群规模预估
  - 分群规则生成
    ↓
方案生成
  - 拆分维度（人群/渠道/内容）
  - 多方案对比排序
    ↓
策略生成
  - 触达时机优化
  - 通道优先级排序
  - 内容个性化匹配
    ↓
触达任务执行
  - 受众过滤
  - 触发条件监听
  - 触达通道调用（短信/Webhook）
    ↓
效果追踪与动态优化
  - 转化数据回传
  - 策略调整建议

POST /api/v1/query
{
    "question": "本月华北地区销售额相比上月变化如何",
    "dataset_ids": ["ds_xxxx"],          // 可选，默认全量
    "conversation_id": "conv_xxxx",       // 多轮对话 ID
    "user_id": "user_xxxx",
    "options": {
        "show_thinking": true,            // 返回分析过程
        "visualization": true,           // 返回可视化建议
        "attribution": false             // 是否做归因分析
    }
}

Response:
{
    "conversation_id": "conv_xxxx",
    "answer": {
        "text": "本月华北地区销售额为 1,235 万元，环比上月下降 12%...",
        "sql": "SELECT region, SUM(amount) WHERE ...",
        "data": {
            "columns": ["region", "amount", "mom_change"],
            "rows": [["华北", 12350000, -0.12], ...],
            "chart_type": "line",
            "chart_config": {...}
        },
        "thinking": {
            "intent": "compare_query",
            "semantic_mapping": {...},
            "sql_generation": "..."
        },
        "attribution": null,
        "recommendations": [
            {"type": "follow_up", "question": "华北下降的原因是什么？"}
        ]
    }
}

GET  /api/v1/questions/recommended?dataset_ids=ds_xxxx,ds_yyyy
POST /api/v1/questions              # 创建推荐问题
POST /api/v1/questions/{id}/favorite # 用户收藏

POST /api/v1/query/attribution
{
    "query_result_id": "qr_xxxx",
    "dimensions": ["region", "product_category", "channel"],
    "target_metric": "销售额"
}

POST /api/v1/marketing/campaigns
{
    "name": "618 大促通知",
    "objective": "提升复购率",
    "audience_description": "高价值用户，近 30 天有购买记录",
    "触达时机": {
        "type": "optimal_window",
        "max_times": 3
    },
    "通道": ["sms"],
    "内容策略": "个性化",
    "options": {
        "generate_audience": true,
        "generate_content": true
    }
}

Response:
{
    "campaign_id": "camp_xxxx",
    "generated_audience": {
        "id": "aud_xxxx",
        "name": "AI 智能圈选-高价值用户",
        "estimated_count": 15832,
        "rules": [...],
        "insights": "该人群以 25-35 岁女性为主，周末活跃度更高..."
    },
    "proposed_plans": [
        {
            "id": "plan_xxxx",
            "拆分维度": "人群分层",
            "方案描述": "按消费频次分为高/中/低三层...",
            "预估效果": {...}
        },
        ...
    ]
}

POST /api/v1/marketing/plans/{plan_id}/apply
{
    "通道": ["sms", "webhook"],
    "内容物料": {
        "sms_template": "tmpl_xxx",
        "webhook_payload": {...}
    }
}

Response:
{
    "strategy_id": "str_xxxx",
    "触达时机设计": [
        {"segment": "高消费层", "最佳时机": "周末 10:00-12:00"},
        {"segment": "中消费层", "最佳时机": "工作日 19:00-21:00"}
    ],
    "通道优先级": {"sms": 0.7, "webhook": 0.3},
    "内容变体": [
        {"segment": "高消费层", "content": "尊敬 VIP..."}
    ]
}

POST /api/v1/marketing/tasks
{
    "campaign_id": "camp_xxxx",
    "strategy_id": "str_xxxx",
    "audience_id": "aud_xxxx",
    "触发条件": {
        "type": "time_window",
        "start": "2026-06-01T00:00:00Z",
        "end": "2026-06-18T23:59:59Z"
    },
    "触达配置": {
        "通道": "sms",
        "template_id": "tmpl_xxx",
        "frequency_limit": 1
    }
}

GET  /api/v1/marketing/tasks/{task_id}
PUT  /api/v1/marketing/tasks/{task_id}   # 编辑
DELETE /api/v1/marketing/tasks/{task_id}  # 删除
GET  /api/v1/marketing/tasks/{task_id}/analytics  # 效果数据

GET    /api/v1/datasets
POST   /api/v1/datasets              # 注册数据集
GET    /api/v1/datasets/{id}
GET    /api/v1/datasets/{id}/schema  # 获取语义模型
POST   /api/v1/datasets/{id}/sync    # 触发数据同步