完善整理数据源替换流程和项目将指南

项目快速上手指南.md

@@ -1,240 +1,174 @@
-# 项目快速上手指南 (v2.0 - 2025年7月版)
+# 智能药品销售预测系统：技术白皮书与核心SOP
 
-欢迎加入项目！本指南旨在帮助你快速理解项目的核心功能、最新的技术架构和开发流程。
+## 1. 项目概述
 
-## 1. 项目核心功能
+本文档旨在为新成员提供一个全面的、由浅入深的项目技术指南，并系统性地沉淀项目在迭代演进过程中的核心设计思想、关键决策和标准作业程序（SOP）。
 
-这是一个基于历史销售数据的 **智能销售预测系统**，其核心是实现一个 **"数据 -> 训练 -> 模型 -> 预测 -> 可视化"** 的完整闭环。
+### 1.1. 核心价值
 
-所有功能均通过Web界面操作：
+本系统是一个基于深度学习和机器学习模型的智能预测平台，旨在解决药品零售行业的核心痛点：
-1.  **模型训练**: 用户可以选择某个**药品**、某个**店铺**或**全局**数据，然后选择一种机器学习算法（如Transformer、KAN等）进行训练。训练过程是**异步**的，并能通过WebSocket实时反馈进度。
-2.  **销售预测**: 使用已经训练好的模型，对未来的销量进行预测。
-3.  **结果可视化**: 将历史销量和预测销量在同一个图表中展示出来，方便用户直观地看到趋势。
-4.  **模型与历史管理**: 提供对已训练模型和历史预测记录的查询、详情查看和删除功能。
 
-## 2. 技术栈
+*   **精准库存管理**：通过对未来销量的精确预测，指导采购与备货，降低库存成本，避免缺货损失。
+*   **智能化决策支持**：为营销活动、人员排班、资金规划等提供量化的、数据驱动的决策依据。
+*   **多维度洞察**：支持从“单品”、“店铺”到“区域全局”等多个维度进行训练和预测，满足不同层级的业务分析需求。
 
-| 层面 | 本项目技术 | 说明 |
+### 1.2. 技术栈
-| :--- | :--- | :--- |
-| **后端框架** | **Flask** | 轻量级的Python Web框架，用于提供API接口。 |
-| **前端框架** | **Vue.js** | 用于构建用户交互界面的现代化JavaScript框架。 |
-| **核心算法库** | **PyTorch** | 实现深度学习算法的核心库。 |
-| **数据处理** | **Pandas** | Python中用于数据分析和处理的核心库。 |
-| **数据库** | **SQLite** | 一个轻量级的本地文件数据库，用于记录模型元数据和预测历史。 |
-| **实时通信** | **Flask-SocketIO** | 用于后端在训练时向前端实时推送日志和进度。 |
-| **异步任务** | **multiprocessing** | Python标准库，用于将耗时的训练任务放到独立的子进程中执行，避免阻塞API服务。 |
 
-## 3. 系统架构与数据流
+*   **后端**: 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`
-|                      用户 (Browser - Vue.js)                      |
-+-----------------------------------------------------------------+
-      | (1. HTTP/WebSocket请求)
-+-----------------------------------------------------------------+
-|                 后端API层 (Backend API - Flask)                   |
-|   - api.py: 定义所有RESTful接口 (e.g., /api/training)           |
-|   - 接收请求, 验证参数, 调用核心服务层                           |
-+-----------------------------------------------------------------+
-      | (2. 调用核心服务)
-+-----------------------------------------------------------------+
-|                  核心服务与管理层 (Core Services)                  |
-|   - training_process_manager.py: 异步训练任务管理器 (关键)      |
-|   - model_manager.py: 模型保存、加载、版本控制 (关键)           |
-|   - model_registry.py: 算法与训练器的注册表 (关键)              |
-+-----------------------------------------------------------------+
-      | (3. 执行具体任务)
-+-----------------------------------------------------------------+
-|                算法实现与数据处理层 (Algorithm & Data)             |
-|   - trainers/*.py: 具体的算法训练逻辑 (e.g., kan_trainer.py)    |
-|   - predictors/model_predictor.py: 模型加载与预测逻辑           |
-|   - models/*.py: PyTorch模型定义 (e.g., kan_model.py)           |
-|   - utils/data_utils.py: 数据预处理和转换工具                   |
-+-----------------------------------------------------------------+
-      | (4. 读写物理文件)
-+-----------------------------------------------------------------+
-|                       物理存储层 (Storage)                        |
-|   - data/*.parquet: 原始时序数据                                |
-|   - saved_models/*.pth: 训练好的模型文件 (权重、配置、缩放器)     |
-|   - saved_predictions/*.json: 详细的预测结果文件                |
-|   - prediction_history.db: SQLite数据库 (存储元数据和文件路径索引) |
-+-----------------------------------------------------------------+
-```
-
-## 4. 核心工作流详解：“数据 -> 训练 -> 预测”
-
-#### **步骤一：数据准备**
-- **原始数据**: 存储在 [`data/timeseries_training_data_sample_10s50p.parquet`](data/timeseries_training_data_sample_10s50p.parquet)。
-- **数据存储模式**: 本项目采用“数据库作索引，文件系统存内容”的设计模式。
-    - **元数据 (索引)**: 存储在根目录的 `prediction_history.db` SQLite数据库中。它只记录轻量级的元信息（如模型版本、预测参数）和指向真实数据文件的**路径**。
-    - **真实数据 (内容)**:
-        - **模型**: 训练好的模型（`.pth`文件）存放在 [`saved_models/`](saved_models/) 目录。
-        - **预测结果**: 详细的预测数据（`.json`文件）存放在 [`saved_predictions/`](saved_predictions/) 目录。
-
-#### **步骤二：模型训练 (异步)**
-1.  **API触发**: 前端调用 `POST /api/training` ([`server/api.py`](server/api.py:815))。
-2.  **任务提交**: `api.py` 将训练请求提交给**训练进程管理器** (`training_process_manager`)，并立即返回一个任务ID，不阻塞主服务。
-3.  **动态执行**:
-    *   管理器在**新的子进程**中运行任务。
-    *   它通过**模型注册表** (`model_registry`) 找到 `model_type` 对应的训练器函数（例如，`kan` -> `kan_trainer.py` 中的函数）。
-    *   训练器加载数据，进行归一化，然后执行PyTorch训练循环。
-4.  **模型保存**:
-    *   训练完成后，调用**模型管理器** (`model_manager`) 的 `save_model` 方法。
-    *   模型（权重、配置、缩放器）被打包保存在 [`saved_models/`](saved_models/) 目录下，命名如 `kan_product_P001_v1.pth`。
-    *   模型的元数据（路径、版本、指标）被写入数据库的 `model_versions` 表。
-
-#### **步骤三：模型预测 (同步)**
-1.  **API触发**: 前端调用 `POST /api/prediction` ([`server/api.py`](server/api.py:1273))。
-2.  **模型定位**: `api.py` 调用**模型管理器** (`model_manager`)，根据参数从数据库中找到对应的模型文件路径。
-3.  **加载与预测**:
-    *   核心逻辑在 [`server/predictors/model_predictor.py`](server/predictors/model_predictor.py) 的 `load_model_and_predict` 函数中。
-    *   该函数加载 `.pth` 文件，并利用其中的 `config` 和 `state_dict` **精确重建模型实例**。
-    *   执行**自回归预测**：预测一天，将结果作为下一天输入的一部分，循环往复。
-4.  **结果保存**:
-    *   完整的预测结果（历史、预测、分析等）被保存为一个JSON文件到 [`saved_predictions/`](saved_predictions/) 目录。
-    *   该次预测的元数据（包括JSON文件路径）被写入数据库的 `prediction_history` 表。
-5.  **返回与渲染**: 完整的JSON结果被返回给前端，前端使用图表库进行可视化。
-
-## 5. 如何添加一个新的算法？(开发者指南)
-
-假设你要添加一个名为 `NewNet` 的新算法。
-
-**目标**: 让 `NewNet` 出现在前端的“模型类型”下拉框中，并能成功训练和预测。
-
-1.  **创建模型定义文件**:
-    *   在 `server/models/` 目录下，创建 `newnet_model.py`。
-    *   在其中定义你的 `NewNet` 模型类，继承自 `torch.nn.Module`。
-
-2.  **创建训练器文件**:
-    *   在 `server/trainers/` 目录下，创建 `newnet_trainer.py`。
-    *   复制一份现有训练器（如 `kan_trainer.py`）的内容作为模板。
-    *   **关键修改**:
-        *   导入你的 `NewNet` 模型。
-        *   在训练函数中，实例化你的 `NewNet` 模型。
-        *   在保存checkpoint时，确保 `config` 字典里包含了重建 `NewNet` 所需的所有超参数。
-        *   在文件末尾，**注册你的训练器**: `register_trainer('newnet', your_training_function)`。
-
-3.  **创建预测器逻辑 (如果需要)**:
-    *   大多数情况，你可以复用默认的预测器。打开 [`server/predictors/model_predictor.py`](server/predictors/model_predictor.py)。
-    *   在 `load_model_and_predict` 函数中，添加一个 `elif loaded_model_type == 'newnet':` 分支，确保它能根据 `config` 正确地创建 `NewNet` 模型实例。
-    *   在文件末尾，**注册你的预测器**: `register_predictor('newnet', default_pytorch_predictor)`。如果你的模型有特殊的预测逻辑，可以自定义一个预测函数并注册它。
-
-4.  **更新前端界面**:
-    *   打开 `server/api.py` 中的 `get_model_types` 函数。
-    *   在 `model_meta` 字典中添加 `'newnet'` 的元数据，包括名称、描述和标签类型。
-    *   **无需修改前端代码**，前端的下拉框会自动从这个API获取最新的模型列表。
-
-完成以上步骤后，重启服务，你就可以在界面上选择并使用你的新算法了。这个插件式的设计大大简化了新算法的集成过程。
-
-## 6. 系统维护与扩展
-
-随着系统的持续运行，会不断产生模型文件、预测结果等历史产物。理解如何管理这些产物对于保持系统的健康至关重要。
-
-### 6.1. 历史产物管理 (Artifacts Management)
-
-**问题**:
-随着时间推移，`saved_models/` 和 `saved_predictions/` 目录下的文件会越来越多，导致项目体积变得臃肿。
-
-**当前状态**:
-系统目前依赖**手动清理**。您可以通过Web界面删除单个模型或单条预测历史，程序会自动删除对应的文件。
-
-**推荐的解决方案**:
-为了实现自动化管理，推荐创建一个独立的维护脚本，并实施**数据保留策略 (Data Retention Policy)**。
-
-#### **自动化清理策略**
-
-1.  **创建清理脚本**:
-    *   可以在 `server/tools/` 目录下创建一个新脚本，例如 `cleanup_artifacts.py`。
-
-2.  **定义保留规则**:
-    *   **对于预测结果 (`.json` in `saved_predictions/`)**:
-        *   **基于时间**: 只保留最近30天的记录。
-        *   **基于数量**: 只保留最新的1000条记录。
-    *   **对于模型 (`.pth` in `saved_models/`)**:
-        *   **基于版本**: 只保留每个模型（同一种药品、同一种算法）最新的3个版本。
-        *   **保留最佳模型**: 始终保留性能最佳的 `best` 版本，不参与自动清理。
-
-3.  **执行脚本**:
-    *   脚本的逻辑是：连接数据库，查询出所有符合清理条件的记录，然后安全地删除硬盘上对应的文件，最后再删除数据库中的条目。
-    *   这个脚本可以通过服务器的定时任务（如Linux的Cron Job或Windows的Task Scheduler）设置为每日自动执行。
-
-#### **企业级方案：归档到冷存储**
-
-对于需要长期保留数据以备审计的场景，更专业的做法是将旧文件归档至廉价的云对象存储（如阿里云OSS, AWS S3等），而不是直接删除。数据库中仅更新文件路径指向云端地址即可。
 
 ---
 
-## 核心概念扫盲：算法、模型、训练与预测
+## 2. 核心架构设计
 
-对于初次接触AI和数据科学的开发者来说，这些术语可能会令人困惑。本章节旨在用最通俗易懂的方式，解释本项目核心的AI部分是如何工作的。
+系统采用经典的前后端分离架构，并通过模块化的设计，实现了业务逻辑、AI能力与数据处理的有效解耦。
 
-### 1. 一个简单的比喻：学生备考
+### 2.1. 架构分层图
 
-让我们把整个AI预测系统想象成一个准备参加数学考试的学生：
+```
++---------------------+      +-----------------------+      +---------------------+
+|      前端 (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)               |
++--------------------------+      +---------------------------+
+```
 
-*   **历史数据 (Data)**：就像是学生的**教科书和练习册** (`pharmacy_sales.xlsx` 文件)。里面包含了大量的历史题目（过去的销售情况）和对应的正确答案。
+### 2.2. 核心工作流：“数据 -> 智能”的闭环
-*   **算法 (Algorithm)**：是学生的**学习方法和大脑结构** (本项目中的 `KAN` 神经网络)。它定义了学生如何去理解问题、寻找规律，但算法本身不包含任何知识。它只是一套空的学习框架。
-*   **训练 (Training)**：就是学生**学习和复习**的过程 (`server/trainers/kan_trainer.py` 脚本)。学生通过不断地做练习册上的题（读取历史数据），然后对照答案（真实的销售额），分析自己错在哪里（计算损失/Loss），然后反思并修正自己的解题思路（反向传播与优化）。这个过程会重复很多遍（Epochs），直到学生在模拟考试（测试集）中取得好成绩。
-*   **模型 (Model)**：是学生学习完成后，**学到的所有知识和解题技巧** (保存在 `saved_models/` 下的 `.pth` 文件)。它不再是空的大脑框架，而是包含了所有规律和知识、准备好上考场的“成型的知识体系”。
-*   **预测 (Prediction)**：就是学生**正式上考场考试**的过程 (`server/predictors/model_predictor.py` 脚本)。我们给学生一套他从未见过的新题目（例如，提供最近30天的数据，让他预测未来7天），学生利用他已经学到的知识（加载`.pth`模型文件），给出他认为最可能的答案（未来的销售额）。
 
-### 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返回的历史数据和预测数据渲染成趋势图。
 
-**Q: 训练和预测所使用的算法有区别吗？**
+---
 
-**A:** 核心算法（大脑结构）是**完全相同**的，都是 `KAN` 网络。但它们所做的事情（功能）截然不同。
+## 3. 项目演进全景回顾
 
-*   **训练 (`train_product_model_with_kan`)**
+### 第一阶段：奠基与探索 (早期修复与重构)
-    *   **目标**：**创造一个模型**。
-    *   **输入**：大量的历史数据（特征+答案）。
-    *   **过程**：是一个**学习和迭代**的过程。它会反复调整算法内部的参数（权重），目标是让预测结果与真实答案的差距越来越小。这是一个计算量巨大、非常耗时的过程。
-    *   **输出**：一个 `.pth` 文件，这就是训练好的模型。
 
-*   **预测 (`load_model_and_predict`)**
+此阶段的核心目标是**打通系统最基础的“训练->预测”闭环**，并解决一系列阻碍核心功能运行的初始Bug。
-    *   **目标**：**使用一个已有的模型**。
-    *   **输入**：一小段最近的历史数据（只有特征，没有答案）。
-    *   **过程**：是一个**计算和应用**的过程。它加载训练好的`.pth`模型文件，将输入数据“喂”给模型，模型根据已经固化的参数，直接计算出结果。这个过程非常快。
-    *   **输出**：对未来的预测数据（JSON格式）。
 
-**总结**：训练是“从0到1”打造模型的过程，预测是“使用这个1”来解决实际问题的过程。
+*   **设计思路**：采用“问题驱动”的模式，从最表层的UI失败开始，逐层深入，定位并修复了从数据流、模型算法到前后端通信的多个核心问题。
+*   **关键改动与修复**：
+    1.  **数据流重构**：修复了 `predictor.py` 中数据处理流程中断，导致特征丢失的根本性问题。
+    2.  **模型算法修复**：
+        *   根治了所有PyTorch模型因**维度不匹配**而无法学习（R²恒为0）的严重Bug。
+        *   修复了 `mLSTM` 模型因**算法设计缺陷**导致预测结果无效的问题。
+    3.  **配置持久化**：系统性地修复了所有训练器，确保在保存模型时，会将**完整的、可用于重新实例化模型的配置**写入检查点，解决了除Transformer外所有模型预测失败的问题。
+    4.  **版本管理统一**：引入了 `ModelManager` 作为系统中**唯一**负责版本管理、模型命名和IO的组件，彻底解决了因命名和路径不统一导致模型无法被找到的混乱状况。
+    5.  **前后端链路打通**：通过修复**JSON序列化**、**API响应结构**、**数据时间戳连续性**和**图表日期格式化**等一系列问题，最终成功实现了所有预测视图的图表渲染。
 
-### 3. 模型的具体实现是怎样的？
+### 第二阶段：涅槃与重生 (核心数据源替换)
 
-1.  **我们如何得到模型？**
+此阶段的核心目标是将项目的数据源，从一个简单的、理想化的样本数据，彻底更换为**全新的、结构更复杂、更贴近真实业务场景的核心数据集**。这是一次“换引擎”级别的大手术。
-    *   我们运行训练脚本 (`uv run train_model`)。
-    *   该脚本调用 `kan_trainer.py` 中的 `train_product_model_with_kan` 函数。
-    *   这个函数会加载销售数据，对数据进行预处理（例如，将“星期一”转换为数字1，将所有数据缩放到0-1之间以便于神经网络处理）。
-    *   然后，它将数据切分成“用连续30天的数据，预测未来7天销量”这样的样本对。
-    *   最后，它通过成千上万次的学习迭代，将学到的知识保存为一个 `.pth` 文件。
 
-2.  **预测的具体实现是怎样的？**
+#### **“更换数据源”标准作业程序 (SOP)**
-    *   我们通过API请求预测。
-    *   API调用 `model_predictor.py` 中的 `load_model_and_predict` 函数。
-    *   该函数首先根据请求，找到对应的 `.pth` 模型文件并加载它。
-    *   然后，它获取预测开始日期前最新的30天真实数据。
-    *   它将这30天数据输入模型，得到对未来第1天的预测销量。
-    *   **关键一步（自回归）**：它将第1天的预测结果，当作“真实发生过”的数据，拼接到历史数据的末尾，并丢掉最老的一天，形成一个新的30天数据序列。
-    *   它用这个新的序列去预测第2天的销量。
-    *   ……如此循环往复，直到预测出未来7天的全部结果。
 
-### 4. 我需要具备哪些技术才能理解？
+我们在此次重构中，沉淀出了一套可复用的、用于安全更换核心数据源的SOP。
 
-这是一个很好的问题，可以分层来看：
+**第1步：分析与评估 (Analysis & Assessment)**
 
-*   **初级（能使用和调试）**：
+*   **目标**：全面理解新旧数据源的差异，识别风险，制定策略。
-    *   **Python基础**：能读懂基本的Python代码和逻辑。
+*   **动作**：
-    *   **Pandas库**：了解如何操作和处理表格数据（DataFrame）。我们项目中的数据预处理大量使用Pandas。
+    *   对比新旧 `.parquet` 文件的Schema（表结构）。
-    *   **理解本章节内容**：对训练和预测有宏观概念，知道输入什么、输出什么即可。
+    *   识别出**“断裂性变更”**，例如：列名不同 (`subbh` vs `store_id`)、数据类型变化、特征缺失（如 `is_promotion`）。
+    *   **决策**：放弃“直接修改代码以适应新数据”的高风险方案，选择**“适配器模式”**，以最小的侵入性实现兼容。
 
-*   **中级（能修改和优化）**：
+**第2步：构建数据适配器 (Adapter Construction)**
-    *   **PyTorch框架**：了解PyTorch的基本概念，如 `Tensor`（张量）、`nn.Module`（模型结构）、`Optimizer`（优化器）、`DataLoader`（数据加载器）。我们的 `KAN` 模型就是用PyTorch构建的。
-    *   **机器学习基础概念**：了解什么是特征工程、训练集/测试集、损失函数、过拟合与欠拟合等。
 
-*   **高级（能设计和创新）**：
+*   **目标**：创建一个独立的、统一的数据入口，将“新数据”动态转换为“旧代码能理解的格式”。
-    *   **深度学习理论**：深入理解神经网络、反向传播等原理。
+*   **动作**：
-    *   **时间序列分析**：了解ARIMA、LSTM、Transformer等其他时间序列预测模型的原理和优劣。
+    *   创建 `server/utils/new_data_loader.py`。
+    *   在该模块中，集中实现所有的数据转换逻辑：
+        *   **列名重映射**：`{'subbh': 'store_id', 'hh': 'product_id', ...}`。
+        *   **特征填充**：为缺失的 `is_promotion` 列创建代理并填充默认值 `0`。
+        *   **数据类型转换**：将日期列统一转换为 `datetime` 对象。
 
-**给您的建议**：
+**第3步：全面重构 (Refactoring)**
-您现在完全不需要焦虑。从“初级”开始，先尝试理解数据的流转，即数据是如何从文件加载，被Pandas处理，然后输入给训练器或预测器的。当您能熟练地进行使用和调试后，再逐步去了解PyTorch和机器学习的细节。边学边做是最高效的方式。
+
+*   **目标**：将系统中所有直接读取旧数据的代码，全部重构为通过新的数据适配器获取数据。
+*   **动作**：
+    *   系统性地修改了所有数据消费端，包括：`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` 数据库文件。系统会在下次运行时自动重建。