# attribution_analysis_system

**Repository Path**: great-hunger/attribution_analysis_system

## Basic Information

- **Project Name**: attribution_analysis_system
- **Description**: 经营归因分析系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 经营归因分析系统

多轮业务经营归因分析系统（VibeCoding 项目实战 M3）：围绕业务问题提问、取证、归因、得出结论。
后端 FastAPI + SQLAlchemy 2.x，前端 React + TypeScript + Vite + MUI + Zustand。

## 项目结构

```
backend/                后端服务
  app/                  FastAPI 应用（routers / services / tools / auth / utils / models / schemas）
  scripts/              初始化脚本（init_all / init_db / seed_data）
  data/                 演示数据库（demo_catalog.db、demo_refund.db）
  requirements.txt
  .env.example
frontend/               前端应用（React + Vite + TS）
  src/api/              axios 实例与 16 个接口封装
  src/types/            前后端契约类型（与 schemas.py 零丢失对齐）
  src/hooks/            useWebSocket / useDebounce
  src/modules/          认证 / 会话 / 聊天 / 附件 / 结果 / 配置 / 日志 模块
  src/components/       布局与共享组件
docs/                   接口契约与设计图
```

## 快速启动

### 0. 一键启动（推荐）

```bash
python start.py            # 同时启动后端(8000)与前端(5173)，Ctrl+C 停止
python start.py --check    # 仅检查环境
python start.py --backend-only / --frontend-only   # 单独启动某一端
```

首次使用前先完成依赖初始化（见下方第 1、2 节）。

### 1. 后端（端口 8000）

```bash
cd backend
python -m venv .venv && .venv/Scripts/activate   # 可选：创建虚拟环境
pip install -r requirements.txt                  # 安装依赖
cp .env.example .env                             # 按需修改配置（默认即可运行）
python scripts/init_all.py                       # 建 10 张表 + 默认配置 + 两个演示库
python -m uvicorn app.main:app --reload --port 8000
```

> 说明：Windows 下请使用 `python -m uvicorn` 而非裸 `uvicorn`，避免 PATH 中其他
> Python 环境的 uvicorn 干扰；接口文档见 http://localhost:8000/docs 。

### 2. 前端（端口 5173）

```bash
cd frontend
npm install            # 安装依赖（React18 / MUI / Zustand / Vite）
npm run dev            # 开发服务器（/api、/auth 自动代理到 8000）
npm run build          # 生产构建（产物 dist/）
```

> 项目路径含 `&` 字符时，Windows 下 `npx tsc`/`npm run build` 的 bin 解析可能失败，
> 可改用 `node node_modules/typescript/bin/tsc --noEmit` 与
> `node node_modules/vite/bin/vite.js build`。

浏览器访问 http://localhost:5173 。

## 演示场景全链路

系统内置两个演示场景数据库（由 `scripts/init_all.py` 生成，各表 8~15 行真实业务数据）。
登录页提供「分析用户」「系统管理员」两个演示身份（内置模拟认证中心）。

### 场景一：商品目录优化

**演示问题**：搜索曝光高但点击转化低的商品集中在哪些类目？

| 步骤 | 操作 | 预期结果 |
| --- | --- | --- |
| 1 初始化 | `python scripts/init_all.py` | 生成 10 张系统表 + 6 条默认配置 + demo_catalog.db/demo_refund.db |
| 2 登录 | 访问 :5173 → 授权登录 → 以「分析用户」身份确认 | 回跳工作台，三栏布局就绪 |
| 3 建会话 | 左栏「+」输入「商品目录优化分析」回车 | 新会话选中，中栏可输入 |
| 4 传附件 | 左栏附件「上传附件」选择示例 CSV（如 demo_products.csv） | 列表出现文件，解析状态「已解析」 |
| 5 提问 | 输入「搜索曝光高但点击转化低的商品集中在哪些类目？」回车 | 实时任务区出现 message_start → 状态「分析中」 |
| 6 实时观察 | 观察任务区 | 工具轨迹依次出现 db_query / text_search / file_io / command / result_file 完成 |
| 7 结果核对 | 右栏结果区刷新 | 六部分结果：关键指标含「搜索曝光量 40800 次」；结论指向「数码配件」类目 CTR 2.2% 最低 |
| 8 导出下载 | 结果区「导出」 | 下载 result_*.md 文件 |
| 9 追问 | 继续输入「数码配件类目转化低应如何优化？」 | 新一轮分析（消息 seq_no 递增，历史可见） |
| 10 切换历史 | 左栏切换其他会话或刷新页面 | 历史消息与结果正确回显 |

### 场景二：退款模式分析

**演示问题**：退款率上升主要由哪类订单/原因驱动？

| 步骤 | 操作 | 预期结果 |
| --- | --- | --- |
| 1~3 | 同场景一（会话标题「退款模式分析」） | 新会话就绪 |
| 4 | 提问「退款率上升主要由哪类订单/原因驱动？」 | 实时任务区跑完整工具链 |
| 5 | 观察结果区 | 关键指标「退款笔数 4 笔 / 金额 4056.0 元」；结论指向「质量缺陷」类商品问题与大促高客单订单 |
| 6 | 导出下载 | 结果文件可重复下载 |

### 管理员验收（A7）

- 登录时选择「系统管理员」身份；
- 左栏顶部「系统配置」→ 查看 6 条配置（summary.trigger_threshold 等）→「热更新」→ 提示配置已热更新；
- 「运行日志」→ 查看当前会话任务工具执行轨迹与错误；
- 分析用户身份访问 /config 或 /logs 会被重定向回工作台。

## 关键设计说明

- **分析流程**：WS 实时事件（message_start → message_delta → tool_start/finish → result_ready → done），
  任务状态机 `queued → running → success/failed/cancelled`，同会话并发限制为 1。
- **分析工具**：db_query（只读 SELECT 白名单）/ file_io / text_search / command（白名单+目录受限）/
  result_file（Markdown 导出），经工具注册表按名调度。
- **安全**：JWT 鉴权 + 一次性 WS 令牌 + 资源归属校验 + 路径穿越防护（path_guard）。
- **上下文管理**：消息超过阈值（默认 20 条）自动生成区间摘要，保留近期消息。

## 接口文档

完整契约见 [docs/api-contract.md](docs/api-contract.md)（16 个 HTTP 接口 + 8 种 WS 事件 + 认证流程）。