# 药店销售预测系统 - 模型管理规则

## 📋 统一模型命名规范

### 文件名格式

#### 1. 产品训练模式 (Product Mode)
```
{model_type}_product_{product_id}_{version}.pth
```
**示例：**
- `tcn_product_P001_v1.pth`
- `mlstm_product_P002_v2.pth`
- `kan_product_P001_v1.pth`
- `transformer_product_P001_v1.pth`

#### 2. 店铺训练模式 (Store Mode)
```
{model_type}_store_{store_id}_{product_id}_{version}.pth
```
**示例：**
- `tcn_store_S001_P001_v1.pth`
- `mlstm_store_S002_P001_v1.pth`
- `kan_store_S001_P002_v2.pth`

#### 3. 全局训练模式 (Global Mode)
```
{model_type}_global_{product_id}_{aggregation_method}_{version}.pth
```
**示例：**
- `tcn_global_P001_sum_v1.pth`
- `mlstm_global_P001_mean_v1.pth`
- `transformer_global_P002_weighted_v1.pth`

### 模型类型标识符

| 模型类型 | 标识符 | 说明 |
|---------|-------|------|
| TCN | `tcn` | 时间卷积网络 |
| mLSTM | `mlstm` | 多层长短期记忆网络 |
| KAN | `kan` | Kolmogorov-Arnold网络 |
| 优化KAN | `optimized_kan` | 优化版KAN网络 |
| Transformer | `transformer` | 注意力机制模型 |

### 聚合方法标识符

| 聚合方法 | 标识符 | 说明 |
|---------|-------|------|
| 求和 | `sum` | 所有店铺销量求和 |
| 平均 | `mean` | 所有店铺销量平均值 |
| 加权平均 | `weighted` | 基于店铺规模的加权平均 |
| 最大值 | `max` | 取各店铺最大销量 |

## 📁 目录结构

```
项目根目录/
├── saved_models/                    # 统一模型存储目录
│   ├── tcn_product_P001_v1.pth     # 产品模式模型
│   ├── tcn_store_S001_P001_v1.pth  # 店铺模式模型
│   ├── tcn_global_P001_sum_v1.pth  # 全局模式模型
│   └── ...                         # 其他模型文件
├── server/
│   └── utils/
│       └── model_manager.py        # 统一模型管理器
└── ...
```

## 📦 模型文件内容结构

每个模型文件包含以下标准化内容：

```python
{
    # 模型状态
    'model_state_dict': {...},          # PyTorch模型参数
    
    # 数据预处理器
    'scaler_X': MinMaxScaler(...),      # 特征缩放器
    'scaler_y': MinMaxScaler(...),      # 目标变量缩放器
    
    # 模型配置
    'config': {
        'model_type': 'tcn',             # 模型类型
        'input_dim': 8,                  # 输入特征维度
        'output_dim': 7,                 # 输出维度
        'sequence_length': 30,           # 输入序列长度
        'forecast_horizon': 7,           # 预测时间窗口
        'hidden_size': 64,               # 隐藏层大小
        # ... 其他模型特定参数
    },
    
    # 评估指标
    'metrics': {
        'mse': 150.0,                    # 均方误差
        'rmse': 12.25,                   # 均方根误差
        'mae': 9.5,                      # 平均绝对误差
        'r2': 0.85,                      # 决定系数
        'mape': 15.2,                    # 平均绝对百分比误差
        'training_time': 45.6            # 训练时间(秒)
    },
    
    # 训练历史
    'loss_history': {
        'train': [0.8, 0.6, 0.4, ...],  # 训练损失历史
        'test': [0.9, 0.7, 0.5, ...],   # 测试损失历史
        'epochs': [1, 2, 3, ...]         # 轮次
    },
    
    # 管理信息
    'model_manager_info': {
        'product_id': 'P001',            # 产品ID
        'product_name': '感冒灵颗粒',     # 产品名称
        'model_type': 'tcn',             # 模型类型
        'version': 'v1',                 # 版本号
        'store_id': 'S001',              # 店铺ID (可选)
        'training_mode': 'product',      # 训练模式
        'aggregation_method': 'sum',     # 聚合方法 (可选)
        'created_at': '2025-06-21T22:03:23.357844',  # 创建时间
        'filename': 'tcn_product_P001_v1.pth'        # 文件名
    },
    
    # 其他信息
    'loss_curve_path': 'saved_models/TCN_product_感冒灵颗粒_loss_curve.png'  # 损失曲线图路径
}
```

## 🔧 模型管理器API

### 主要方法

#### 1. 保存模型
```python
model_path = model_manager.save_model(
    model_data=model_data,
    product_id='P001',
    model_type='tcn',
    version='v1',
    store_id='S001',                    # 可选，店铺模式需要
    training_mode='product',            # 'product', 'store', 'global'
    aggregation_method='sum',           # 可选，全局模式需要
    product_name='感冒灵颗粒'
)
```

#### 2. 列出模型
```python
# 列出所有模型
models = model_manager.list_models()

# 按条件过滤
models = model_manager.list_models(
    product_id='P001',                  # 按产品过滤
    model_type='tcn',                   # 按模型类型过滤
    store_id='S001',                    # 按店铺过滤
    training_mode='product'             # 按训练模式过滤
)
```

#### 3. 解析文件名
```python
info = model_manager.parse_model_filename('tcn_product_P001_v1.pth')
# 返回：
# {
#     'model_type': 'tcn',
#     'product_id': 'P001',
#     'version': 'v1',
#     'training_mode': 'product',
#     'store_id': None,
#     'aggregation_method': None
# }
```

#### 4. 获取特定模型
```python
model = model_manager.get_model_by_id('tcn_product_P001_v1')
```

## 🚀 版本管理策略

### 版本号规则
- **v1**: 初始版本
- **v2, v3, ...**: 后续优化版本
- **自动递增**: 同一配置下重新训练自动生成新版本

### 版本冲突处理
- 相同产品、模型类型、训练模式的模型会自动生成新版本号
- 避免意外覆盖之前训练的模型
- 支持模型版本对比和回滚

## 📊 兼容性支持

### 支持的旧格式
系统可以解析和处理以下旧格式文件名：
- `transformer_model_product_P001_v1.pth`
- `P001_mlstm_v1_global_model.pt`
- `kan_optimized_model_product_P001.pth`

### 迁移策略
- 旧格式模型可以正常读取和使用
- 重新训练时会使用新的标准化命名
- 提供迁移工具将旧格式转换为新格式

## 🛠️ 使用示例

### 1. 训练并保存模型
```python
from core.predictor import PharmacyPredictor

predictor = PharmacyPredictor()

# 产品模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='tcn',
    epochs=50,
    training_mode='product'
)

# 店铺模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='mlstm',
    epochs=50,
    training_mode='store',
    store_id='S001'
)

# 全局模式训练
metrics = predictor.train_model(
    product_id='P001',
    model_type='transformer',
    epochs=50,
    training_mode='global',
    aggregation_method='sum'
)
```

### 2. 加载和预测
```python
from predictors.model_predictor import load_model_and_predict

# 使用特定模型进行预测
predictions = load_model_and_predict(
    product_id='P001',
    model_type='tcn',
    training_mode='product',
    store_id=None
)
```

## 📈 性能和监控

### 存储效率
- 统一目录避免文件分散
- 标准化命名便于查找和管理
- 支持大量模型文件的高效检索

### 元数据管理
- 每个模型包含完整的训练信息
- 支持模型性能对比和分析
- 便于模型版本管理和回滚

## 🔄 更新日志

### v2.1.0 (2025-06-21)
- ✅ 实现统一模型命名规范
- ✅ 创建标准化模型管理器
- ✅ 支持三种训练模式的文件名格式
- ✅ 添加完整的元数据管理
- ✅ 实现版本自动管理
- ✅ 提供向后兼容性支持

---

**注意事项：**
1. 所有新训练的模型都将使用新的命名规范
2. 旧格式模型仍可正常使用，但建议逐步迁移
3. 模型文件保存在项目根目录的 `saved_models/` 目录下
4. 删除模型时请确保相关损失曲线图片也被清理