README.md

---
title: Attribution Logic Engine
emoji: 📊
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
short_description: 商业级多渠道营销归因分析与模型对比系统
---

# 归因逻辑引擎 (Attribution Logic Engine)

## 项目简介
这是一个商业级的多渠道营销归因分析系统，旨在帮助市场营销人员理解不同营销渠道（如搜索广告、社交媒体、邮件等）对最终转化的贡献价值。

传统的“最后点击” (Last Click) 归因模型往往掩盖了用户决策路径中早期接触点的重要性。本系统通过模拟真实用户路径，并应用多种归因算法（线性、时间衰减、位置优先等），直观展示不同模型下的 ROI 差异。

## 核心功能
1.  **多模型对比 (Model Comparison)**:
    -   **Last Click**: 100% 归因于最后一次交互。
    -   **First Click**: 100% 归因于第一次交互。
    -   **Linear**: 所有交互点平分功劳。
    -   **Time Decay**: 距离转化越近的交互点权重越高（指数衰减）。
    -   **Position Based (U-Shaped)**: 首尾各 40%，中间平分 20%。

2.  **用户路径可视化 (Journey Visualization)**:
    -   使用 Sankey 图（桑基图）展示用户从首次接触到最终转化（或流失）的常见流动路径。

3.  **数据导入与模拟**:
    -   **模拟引擎**: 内置蒙特卡洛模拟器，可生成数千条复杂的用户行为路径。
    -   **自定义数据上传**: 支持上传 `.csv` 或 `.json` 格式的归因数据进行分析。

## 数据上传格式说明

### CSV 格式
需要包含 `path` (或 `touchpoints`), `converted`, `value` 字段。
- `path`: 渠道路径，可用 `>` 或 `,` 分隔。例如 `Email > Social > Direct`。
- `converted`: 是否转化 (1/0, true/false)。
- `value`: 转化价值 (数字)。

### JSON 格式
一个包含对象列表的文件：
```json
[
  {
    "path": ["Email", "Social Ads", "Direct"],
    "converted": true,
    "value": 150.0
  },
  ...
]
```

## 技术栈
-   **Backend**: Python 3.11, Flask, Pandas
-   **Frontend**: Vue 3, Tailwind CSS, ECharts 5
-   **Deployment**: Docker (Hugging Face Spaces Compatible)

## 商业价值
对于广告投放预算超过 $10k/月的企业，错误的归因模型可能导致 20-30% 的预算浪费。本工具帮助识别那些“助攻”型渠道（如社交媒体种草），避免因 ROI 计算错误而过早关闭有效渠道。

## 运行方式
```bash
# 构建镜像
docker build -t attribution-engine .

# 运行容器
docker run -p 7860:7860 attribution-engine
```
访问 http://localhost:7860 即可使用。