ShopTRAINING/.codelf/quick-reference.md

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

🎯 项目概述

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

🚀 快速启动

# 后端启动
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. 结果查看 → 历史记录 → 详情展示 → 数据导出

🗄️ 数据库设计

-- 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响应格式

{
  "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

⚠️ 常见问题解决

训练相关

# 内存不足 - 调整batch_size
BATCH_SIZE = 16  # 降低批次大小

预测精度

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

前端错误处理

// 统一错误处理
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更新 + 代码同步

📦 核心依赖版本

# 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

// 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编程提供核心上下文，包含项目的关键信息和开发规范