# Sales_BI_ETL

**Repository Path**: wei-jijian/sales_-bi_-etl

## Basic Information

- **Project Name**: Sales_BI_ETL
- **Description**: 一个自动化的ETL项目，用于处理每日销售Excel报表，并将数据清洗后加载到PostgreSQL数据库中。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-04
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sales_BI_ETL - AI 驱动的智能库存决策系统

> 让 AI 为你分析销量、预测趋势、制定清仓策略 | 只需一个 SKU，系统自动完成全部分析

---

## 🎯 一句话介绍

Sales_BI_ETL 是一个**多智能体 AI 分析系统**，针对每个 SKU-渠道组合，自动完成：历史数据分析 → 未来销量预测 → 最优定价策略生成，全程无需人工编写业务规则。

---

## 🚀 快速开始

### 方式一：命令行（最常用）

```bash
# 每日自动分析（分析所有待处理SKU）
python 02_scripts/main.py --mode daily

# 分析单个SKU
python 02_scripts/main.py --mode single --sku QK944902D01 --track 达播清仓

# 批量分析（前10个SKU）
python 02_scripts/main.py --mode batch --limit 10

# 仅测试，不保存到数据库
python 02_scripts/main.py --mode daily --no-save
```

### 方式二：Python API

```python
import sys
sys.path.insert(0, '02_scripts')
from ai_agents_real import RealAgent

agent = RealAgent()
result = agent.comprehensive_analysis('QK944902D01', '达播清仓')
agent.close()

# 返回结果包含：
# - detective_analysis: 历史销售数据、置信度、库存分析
# - prediction_expert: Chronos销量预测、XGBoost价格弹性
# - strategic_advisor: 定价策略、补货建议、风险评估
```

---

## 🏗️ 系统架构（v4.0 Orchestrator 模式）

```mermaid
graph TD
    User[用户: SKU + 赛道]
    RealAgent[RealAgent 编排者]

    subgraph "3个专业子Agent"
        Detective[🔍 DataDetective<br/>数据侦探]
        Predictor[📊 PredictionExpert<br/>预测专家]
        Advisor[🤔 StrategicAdvisor<br/>战略顾问]
    end

    subgraph "3个AI模型"
        Chronos[⏱️ Chronos<br/>时间序列预测]
        XGBoost[📈 XGBoost<br/>价格弹性分析]
        Qwen[💬 Qwen2.5-7B<br/>策略生成]
    end

    User --> RealAgent
    RealAgent --> Detective
    RealAgent --> Predictor
    RealAgent --> Advisor

    Detective --> Chronos
    Predictor --> XGBoost
    Advisor --> Qwen

    RealAgent --> DB[(PostgreSQL<br/>sale_BI_ETL)]
```

### 三个子 Agent 的分工

| Agent | 职责 | 输出 |
|-------|------|------|
| **🔍 数据侦探** | 分析历史销量、库存周转、断码率、计算置信度 | 净销量、风险等级、库存缺口 |
| **📊 预测专家** | Chronos 预测未来30天销量、XGBoost 分析价格弹性 | 最优价格、销量预测、弹性系数 |
| **🤔 战略顾问** | 综合分析生成策略、执行定价瀑布流、计算补货量 | 建议价格、补货建议、策略评分 |

---

## ✨ 核心功能

### 1. 智能销量预测（Chronos）
- 基于历史销售数据，自动预测未来30天销量
- 无需人工设定季节性参数，AI 自动识别季节款/四季款

### 2. 价格弹性分析（XGBoost）
- 训练价格-销量关系模型
- 模拟不同价格策略的收益影响
- 找出收益最大化的最优价格

### 3. 定价瀑布流（V4.1）
```
XGBoost基准价 → 基于目标的动态定价 → 去化豁免检查 → 成本红线校验
```
- 清仓款可突破329元价格底线
- 非清仓款严格遵守成本红线（2倍成本）

### 4. 全局库存管理
- 跨9大渠道（唯品、直播、天猫、拼多多、得物等）共享库存
- 智能补货建议：算出还剩多少天断货、需要补多少

---

## 🛠️ 技术栈

| 组件 | 技术 | 用途 |
|------|------|------|
| **编程语言** | Python 3.10+ | 核心开发语言 |
| **数据库** | PostgreSQL | 数据存储与分析 |
| **LLM** | Qwen2.5-7B (Ollama) | 策略生成与推理 |
| **时序预测** | Chronos-t5-small (Amazon) | 销量预测 |
| **机器学习** | XGBoost | 价格弹性分析 |
| **数据处理** | pandas / numpy | ETL 与数据分析 |

---

## 📁 目录结构

```
Sales_BI_ETL/
├── 01_data/              # 数据目录
│   ├── raw/              # 原始Excel销售数据
│   └── archive/          # 已处理的归档文件
├── 02_scripts/           # 核心代码（重要！）
│   ├── ai_agents_real.py # 编排者入口
│   ├── main.py           # 批量分析主程序
│   ├── agents/           # 3个子Agent
│   │   ├── data_detective.py
│   │   ├── prediction_expert.py
│   │   └── strategic_advisor.py
│   ├── database_tool.py  # 数据库访问工具
│   ├── qwen_llm.py       # Qwen LLM客户端
│   └── etl_script.py     # 数据加载脚本
├── 03_sql/               # SQL脚本（建表、视图）
├── 04_docs/              # 项目文档
│   ├── 数据库表结构说明.md
│   └── 数据流程说明.md
├── _archive/             # 历史归档文档
├── README.md             # 本文档
└── CLAUDE.md             # AI开发指南（面向Claude Code）
```

---

## 🔧 启动依赖

### 必需服务

1. **PostgreSQL**
   - 地址: localhost:5432
   - 数据库: sale_BI_ETL
   - 用户名/密码: postgres / 111111

2. **Ollama (运行 Qwen)**
   ```bash
   ollama serve           # 启动服务
   ollama pull qwen2.5:7b # 下载模型
   ```

### 可选模型

- **Chronos**: 首次使用时自动下载 amazon/chronos-t5-small
- **XGBoost**: 自动从历史数据训练或加载 xgb_price_elasticity_model.json

---

## 📖 了解更多

- **完整技术文档**: CLAUDE.md - 面向 AI 开发者的详细指南
- **业务规则说明**: 商业逻辑运营确认文档.md - 运营参数与公式
- **AI 数据字段**: AI_数据分析字段详细说明.md - 技术细节

---

## 📝 版本历史

| 版本 | 更新内容 |
|------|----------|
| **V4.0** | 编排者架构重构，拆分为3个专业子Agent |
| **V4.1** | 定价瀑布流升级，支持动态定价与去化豁免 |
| **V4.2 Final** | 策略评分权重优化 (4/4/2)，移除过时参数 |

---

*系统已就绪，只需一个 SKU，即可获得完整的 AI 驱动决策建议！*