# 药店销售预测系统 - LLM编程快速参考

## 🎯 项目概述
**技术栈**: Python (Flask) + Vue3 + SQLite + PyTorch + ECharts  
**用途**: 基于深度学习的药品销售时序预测系统  
**环境**: Windows + PowerShell + UV包管理器  

## 🚀 快速启动
```powershell
# 后端启动
uv run .\server\api.py

# 前端启动
cd UI; npm run dev
```

## 📁 核心目录结构
```
药店销售预测系统/
├── server/                    # 🐍 Python后端服务
│   ├── api.py                # 主API入口 (2900+ 行)
│   ├── models/               # 🧠 深度学习模型
│   │   ├── mlstm/           # mLSTM模型
│   │   ├── transformer/     # Transformer模型
│   │   ├── kan/             # KAN模型
│   │   ├── kan_optimized/   # 优化KAN模型
│   │   └── tcn/             # TCN模型
│   ├── trainers/            # 🏋️ 模型训练器
│   ├── predictors/          # 🔮 模型预测器
│   ├── predictions/         # 📊 预测结果存储
│   └── static/              # 📁 静态文件
├── UI/                       # 🖥️ Vue3前端
│   └── src/views/           # 📄 页面组件
│       ├── DataView.vue     # 数据管理
│       ├── TrainingView.vue # 模型训练
│       ├── PredictionView.vue # 预测分析
│       ├── HistoryView.vue  # 历史查看
│       └── ManagementView.vue # 模型管理
└── prediction_history.db    # 🗄️ SQLite数据库
```

## 🔌 核心API接口

### 数据管理
- `GET /api/products` - 获取产品列表
- `GET /api/products/{id}/sales` - 获取销售数据
- `POST /api/data/upload` - 上传Excel数据

### 模型训练
- `POST /api/training` - 启动训练任务
- `GET /api/training/{task_id}` - 查询训练状态

### 预测分析
- `POST /api/prediction` - 执行预测
- `GET /api/prediction/history` - 获取历史记录
- `GET /api/prediction/history/{id}` - 获取预测详情

### 模型管理
- `GET /api/models` - 获取模型列表
- `DELETE /api/models/{id}` - 删除模型

## 🧠 支持的ML模型类型
1. **mLSTM** - 多层LSTM，适合长期预测
2. **Transformer** - 注意力机制，捕捉复杂模式
3. **KAN** - Kolmogorov-Arnold网络，函数拟合
4. **Optimized KAN** - 优化版KAN，提升效率
5. **TCN** - 时间卷积网络，并行训练

## 📊 数据流程
1. **数据上传** → Excel文件 → 数据预处理
2. **模型训练** → 选择模型 → 异步训练 → 保存模型
3. **预测分析** → 选择产品+模型 → 生成预测 → 保存结果
4. **结果查看** → 历史记录 → 详情展示 → 数据导出

## 🗄️ 数据库设计
```sql
-- prediction_history 表
CREATE TABLE prediction_history (
    id INTEGER PRIMARY KEY,
    product_id TEXT,
    product_name TEXT,
    model_type TEXT,
    model_id TEXT,
    start_date DATE,
    future_days INTEGER,
    created_at TIMESTAMP,
    file_path TEXT
);
```

## 📝 API响应格式
```json
{
  "status": "success|error",
  "data": {},
  "message": "操作说明",
  "meta": {},
  "analysis": {},
  "chart_data": {}
}
```

## 🎨 前端组件架构
- **DataView.vue** - 数据管理和上传
- **TrainingView.vue** - 模型训练控制台
- **PredictionView.vue** - 预测分析主界面
- **HistoryView.vue** - 历史预测详情查看
- **ManagementView.vue** - 模型管理和性能监控

## 🔧 开发规范

### Python代码风格
- 使用 `snake_case` 命名
- 类型注解: `def predict(data: pd.DataFrame) -> Dict[str, Any]:`
- 错误处理: `try-except` 包装API调用

### JavaScript代码风格
- 使用 `camelCase` 命名
- Vue3 Composition API: `ref()`, `reactive()`
- Axios异步调用: `async/await`

### 文件命名规范
- Python文件: `model_trainer.py`
- Vue组件: `PredictionView.vue`
- 配置文件: `config.json`

## ⚠️ 常见问题解决

### 训练相关
```python
# 内存不足 - 调整batch_size
BATCH_SIZE = 16  # 降低批次大小
```

### 预测精度
```python
# 数据预处理 - 标准化
from sklearn.preprocessing import StandardScaler
scaler = StandardScaler()
```

### 前端错误处理
```javascript
// 统一错误处理
const handleError = (error) => {
  ElMessage.error(error.response?.data?.message || '操作失败');
};
```

## 🚨 重要注意事项
1. **PowerShell语法**: 使用 `;` 连接命令，避免 `&&`
2. **路径分隔符**: Windows使用 `\` 或 `/`
3. **模型文件**: 训练后自动保存到 `saved_models/`
4. **预测结果**: JSON格式存储在 `predictions/`
5. **数据库备份**: 定期备份 `prediction_history.db`

## 🔄 开发工作流
1. **修改后端** → 重启 `uv run server/api.py`
2. **修改前端** → 热重载自动更新
3. **新增模型** → 添加trainer + predictor + 更新api.py
4. **数据库变更** → 手动SQL更新 + 代码同步

## 📦 核心依赖版本
```python
# requirements.txt 核心依赖
flask==3.1.1
torch==2.7.1+cu128
pandas==2.3.0
scikit-learn==1.7.0
flask-cors==6.0.0
```

```javascript
// package.json 核心依赖
"vue": "^3.x",
"element-plus": "^2.x",
"echarts": "^5.x",
"axios": "^1.x"
```

## 🎯 编程提示
- **添加新API**: 在`api.py`添加路由 + Swagger文档
- **新增页面**: 在`views/`创建Vue组件 + 路由配置
- **数据库操作**: 使用SQLite3原生查询
- **文件存储**: JSON格式，按模型类型分目录
- **错误处理**: 前后端统一错误格式
- **图表展示**: 使用ECharts响应式图表

---
*📝 此文档为LLM编程提供核心上下文，包含项目的关键信息和开发规范*