ShopTRAINING/项目快速上手指南.md

# 智能药品销售预测系统：技术白皮书与核心SOP

## 1. 项目概述

本文档旨在为新成员提供一个全面的、由浅入深的项目技术指南，并系统性地沉淀项目在迭代演进过程中的核心设计思想、关键决策和标准作业程序（SOP）。

### 1.1. 核心价值

本系统是一个基于深度学习和机器学习模型的智能预测平台，旨在解决药品零售行业的核心痛点：

*   **精准库存管理**：通过对未来销量的精确预测，指导采购与备货，降低库存成本，避免缺货损失。
*   **智能化决策支持**：为营销活动、人员排班、资金规划等提供量化的、数据驱动的决策依据。
*   **多维度洞察**：支持从“单品”、“店铺”到“区域全局”等多个维度进行训练和预测，满足不同层级的业务分析需求。

### 1.2. 技术栈

*   **后端**: Python, Flask, Socket.IO, SQLAlchemy
*   **前端**: Vue.js, Element Plus, Chart.js
*   **AI框架**: PyTorch, XGBoost, Scikit-learn
*   **核心模型**: Transformer, KAN, mLSTM, TCN, CNN-BiLSTM-Attention, XGBoost
*   **数据存储**: SQLite (用于历史记录), Parquet (用于核心时序数据)
*   **版本与进程管理**: 自研的 `ModelManager` 和 `TrainingProcessManager`

---

## 2. 核心架构设计

系统采用经典的前后端分离架构，并通过模块化的设计，实现了业务逻辑、AI能力与数据处理的有效解耦。

### 2.1. 架构分层图

```
+---------------------+      +-----------------------+      +---------------------+
|      前端 (UI)      | <--> |     API层 (Flask)     | <--> |    核心逻辑层       |
| (Vue.js, Chart.js)  |      | (api.py, Socket.IO)   |      | (predictor.py)      |
+---------------------+      +-----------------------+      +---------------------+
                                       |                            |
                                       |                            |
             +-------------------------------------------------------+
             |
             v
+--------------------------+      +---------------------------+
|    AI能力层 (Trainers)   | <--> |     模型与算法 (Models)   |
| (kan_trainer.py, etc.)   |      | (kan_model.py, etc.)      |
+--------------------------+      +---------------------------+
             |                            |
             |                            |
             v                            v
+-------------------------------------------------------------------+
|                         数据与工具层 (Utils)                        |
| (new_data_loader.py, model_manager.py, training_process_manager.py) |
+-------------------------------------------------------------------+
             |
             v
+--------------------------+      +---------------------------+
|    数据存储 (Storage)    |      |      原始数据 (Data)      |
| (prediction_history.db)  |      | (*.parquet)               |
+--------------------------+      +---------------------------+
```

### 2.2. 核心工作流：“数据 -> 智能”的闭环

1.  **数据加载**: 所有的数据请求都由 `server/utils/new_data_loader.py` 统一处理。
2.  **模型训练**:
    *   前端通过 **API层** 发起训练请求。
    *   **进程管理器** (`TrainingProcessManager`) 创建一个独立的后台进程来处理该任务。
    *   **核心逻辑层** (`predictor.py`) 根据请求参数（如训练模式、范围），从数据加载器获取并预处理数据。
    *   **AI能力层** (具体的 `trainer.py`) 被调用，负责执行模型的训练、评估和保存。
    *   **模型管理器** (`ModelManager`) 负责将训练好的模型，以统一、规范的命名格式保存到磁盘。
3.  **模型预测**:
    *   前端通过 **API层** 发起预测请求。
    *   **模型管理器** 根据请求参数找到正确的模型文件。
    *   **核心预测器** (`model_predictor.py`) 加载模型，并从数据加载器获取预测所需的历史数据。
    *   根据模型类型（自回归 vs 直接输出），执行相应的预测逻辑。
    *   结果通过 **API层** 返回给前端，并在数据库中留下历史记录。
4.  **结果可视化**: 前端使用 `Chart.js` 将API返回的历史数据和预测数据渲染成趋势图。

---

## 3. 项目演进全景回顾

### 第一阶段：奠基与探索 (早期修复与重构)

此阶段的核心目标是**打通系统最基础的“训练->预测”闭环**，并解决一系列阻碍核心功能运行的初始Bug。

*   **设计思路**：采用“问题驱动”的模式，从最表层的UI失败开始，逐层深入，定位并修复了从数据流、模型算法到前后端通信的多个核心问题。
*   **关键改动与修复**：
    1.  **数据流重构**：修复了 `predictor.py` 中数据处理流程中断，导致特征丢失的根本性问题。
    2.  **模型算法修复**：
        *   根治了所有PyTorch模型因**维度不匹配**而无法学习（R²恒为0）的严重Bug。
        *   修复了 `mLSTM` 模型因**算法设计缺陷**导致预测结果无效的问题。
    3.  **配置持久化**：系统性地修复了所有训练器，确保在保存模型时，会将**完整的、可用于重新实例化模型的配置**写入检查点，解决了除Transformer外所有模型预测失败的问题。
    4.  **版本管理统一**：引入了 `ModelManager` 作为系统中**唯一**负责版本管理、模型命名和IO的组件，彻底解决了因命名和路径不统一导致模型无法被找到的混乱状况。
    5.  **前后端链路打通**：通过修复**JSON序列化**、**API响应结构**、**数据时间戳连续性**和**图表日期格式化**等一系列问题，最终成功实现了所有预测视图的图表渲染。

### 第二阶段：涅槃与重生 (核心数据源替换)

此阶段的核心目标是将项目的数据源，从一个简单的、理想化的样本数据，彻底更换为**全新的、结构更复杂、更贴近真实业务场景的核心数据集**。这是一次“换引擎”级别的大手术。

#### **“更换数据源”标准作业程序 (SOP)**

我们在此次重构中，沉淀出了一套可复用的、用于安全更换核心数据源的SOP。

**第1步：分析与评估 (Analysis & Assessment)**

*   **目标**：全面理解新旧数据源的差异，识别风险，制定策略。
*   **动作**：
    *   对比新旧 `.parquet` 文件的Schema（表结构）。
    *   识别出**“断裂性变更”**，例如：列名不同 (`subbh` vs `store_id`)、数据类型变化、特征缺失（如 `is_promotion`）。
    *   **决策**：放弃“直接修改代码以适应新数据”的高风险方案，选择**“适配器模式”**，以最小的侵入性实现兼容。

**第2步：构建数据适配器 (Adapter Construction)**

*   **目标**：创建一个独立的、统一的数据入口，将“新数据”动态转换为“旧代码能理解的格式”。
*   **动作**：
    *   创建 `server/utils/new_data_loader.py`。
    *   在该模块中，集中实现所有的数据转换逻辑：
        *   **列名重映射**：`{'subbh': 'store_id', 'hh': 'product_id', ...}`。
        *   **特征填充**：为缺失的 `is_promotion` 列创建代理并填充默认值 `0`。
        *   **数据类型转换**：将日期列统一转换为 `datetime` 对象。

**第3步：全面重构 (Refactoring)**

*   **目标**：将系统中所有直接读取旧数据的代码，全部重构为通过新的数据适配器获取数据。
*   **动作**：
    *   系统性地修改了所有数据消费端，包括：`api.py`, `core/predictor.py`, 以及 `trainers/` 目录下的**所有**训练器脚本。
    *   删除了所有旧的、已废弃的数据加载工具，确保了数据源的唯一性。

**第4步：端到端测试与迭代修复 (E2E Testing & Iterative Fixing)**

*   **目标**：在新数据源上，对系统的所有核心功能（所有训练模式、所有预测模式）进行完整测试，并修复因此次变更而引发的所有连锁Bug。
*   **关键修复成果**：
    *   **`NaN`值处理**：在聚合运算（如“按店铺训练”）后，增加了 `.fillna(0)` 数据清理步骤，解决了因数据稀疏性引入`NaN`值而导致的训练失败。
    *   **架构错配修复**：
        *   **问题**：`XGBoost` 和 `CnnBiLstmAttention` 模型在预测时，被错误地调用了为“自回归”模型设计的循环预测逻辑，导致在自定义预测天数时崩溃或返回无效结果。
        *   **修复**：在 `model_predictor.py` 中为这两类“直接多步输出”模型创建了**专属的、正确的、非循环的**预测逻辑分支。
    *   **全链路参数传递修复**：
        *   **问题**：“自定义全局训练”功能因新增的 `selected_stores` 和 `selected_products` 参数在 `api.py` -> `training_process_manager.py` -> `predictor.py` 的调用链中丢失而失败。
        *   **修复**：对整条调用链上的所有相关模块进行了**同步升级**，确保了复杂参数的完整、正确传递。
    *   **数据特性澄清**：确认了“负销量”是源于真实业务（如退货）的数据特性，并决策在代码层面**尊重**而非修改它，这是一个重要的技术决策。

**第5步：环境清理 (Environment Cleanup)**

*   **目标**：在最终验证前，确保一个完全纯净的、不受任何旧数据或旧模型干扰的系统环境。
*   **动作**：
    *   删除了 `saved_models` 和 `saved_predictions` 文件夹中的所有历史产物。
    *   删除了 `prediction_history.db` 数据库文件，并验证了系统具备自动重建的能力。

### 第三阶段：展望 (模型优化与能力升级)

在当前稳定的系统基础上，我们规划了以下四个方向的重点工作，以进一步提升系统的核心价值。

1.  **特征工程**：通过创造时间特征、滞后特征和滑动平均特征，充分挖掘新数据源的潜力，提升模型预测精度。
2.  **模型可解释性**：引入SHAP等工具，让AI模型不再是“黑盒”，为每一次预测提供清晰、量化的归因分析。
3.  **超参数调优**：引入Optuna等自动化调优框架，为每个模型找到其最佳的超参数组合，进一步压榨模型性能。
4.  **架构限制突破**：通过改造训练器和API，最终实现让所有模型都能在**训练时**自由指定预测天数，提升系统的灵活性和易用性。

---

## 4. 系统维护与扩展

### 4.1. 如何引入一个新模型？

1.  **创建模型文件**：在 `server/models/` 目录下，创建一个新的模型定义文件（如 `new_model.py`），确保它是一个标准的PyTorch `nn.Module`。
2.  **创建训练器文件**：在 `server/trainers/` 目录下，创建一个新的训练器文件（如 `new_model_trainer.py`）。
    *   参考现有训练器的结构，实现完整的“数据准备->训练循环->评估->保存”逻辑。
    *   在文件末尾，使用 `@register_trainer('new_model_id', train_function)` 将其注册到系统中。
3.  **（可选）创建专属预测器**：如果你的新模型不是标准的“自回归”模型（像XGBoost那样），则需要在 `server/predictors/model_predictor.py` 中为其创建一个专属的预测逻辑分支。
4.  **更新API**：`api.py` 会自动通过注册表发现你的新模型，无需修改。

### 4.2. 系统清理与数据管理

*   **清理旧模型**：可以直接删除 `saved_models/` 目录下的 `.pth` 文件。
*   **清理旧预测**：可以安全地删除 `saved_predictions/` 目录下的 `.json` 文件和根目录下的 `prediction_history.db` 数据库文件。系统会在下次运行时自动重建。