# 销售报价导入功能 - 前端联调文档

## 一、功能概述

销售报价模块支持多Sheet模板导入，模板结构参考销售台账：
1. **报价单数据Sheet**：包含报价单基本信息
2. **报价产品数据Sheet**：包含产品明细信息

---

## 二、模板结构

### 2.1 报价单数据Sheet

| 字段 | 说明 | 是否必填 |
|------|------|----------|
| 报价单号 | 报价单编号（不填自动生成） | 否 |
| 客户名称 | 客户名称 | 是 |
| 业务员 | 销售人员姓名 | 否 |
| 报价日期 | 格式yyyy-MM-dd | 否 |
| 有效期至 | 格式yyyy-MM-dd | 否 |
| 付款方式 | 如"月结30天" | 否 |
| 交货周期 | 如"7天" | 否 |
| 备注 | 其他说明 | 否 |

### 2.2 报价产品数据Sheet

| 字段 | 说明 | 是否必填 |
|------|------|----------|
| 报价单号 | 关联报价单数据Sheet的报价单号 | 是 |
| 产品大类 | 产品分类名称 | 是 |
| 规格型号 | 产品规格型号 | 是 |
| 单位 | 计量单位 | 否 |
| 数量 | 报价数量 | 是 |
| 含税单价 | 单价（元） | 是 |
| 含税总价 | 总价（元） | 否（不填自动计算） |
| 备注 | 产品备注 | 否 |

---

## 三、接口详情

### 3.1 下载报价导入模板

**请求**
```
GET /sales/quotation/downloadTemplate
```

**响应**
- Excel文件下载，包含两个Sheet：
  - 报价单数据（含示例数据）
  - 报价产品数据（含示例数据）

### 3.2 导入报价单

**请求**
```
POST /sales/quotation/import
Content-Type: multipart/form-data

file: [Excel文件]
```

**响应**
```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "batchNo": "QT_IMP_20260612143000",
        "fileName": "报价单.xlsx",
        "totalCount": 5,
        "successCount": 5,
        "newCount": 5,
        "failCount": 0,
        "status": "completed",
        "createTime": "2026-06-12 14:30:00",
        "createUserName": "张三"
    }
}
```

**业务逻辑**

1. **模板检查**：导入前检查报价审批模板是否存在
   - 不存在：返回错误"请先配置报价审批模板，无法导入"
   - 存在：继续导入

2. **报价单号处理**：
   - 如果填写了报价单号，使用填写的单号
   - 如果未填写，自动生成单号（格式：QT + 日期 + 序号）
   - 报价单号已存在则跳过

3. **产品关联**：通过报价单号将产品数据关联到对应的报价单

4. **审批流程**：导入成功后自动创建审批流程

5. **降价记录**：相同规格型号的产品对比历史价格，自动记录降价

**错误码**

| 错误信息 | 说明 |
|----------|------|
| 请先配置报价审批模板，无法导入 | 系统未配置报价审批模板 |
| 读取文件失败 | Excel文件格式错误 |
| 报价单数据为空，请检查模板内容 | 报价单Sheet无数据 |

### 3.3 查询导入记录

**请求**
```
GET /sales/quotation/importLog/list?pageNum=1&pageSize=10
```

**响应**
```json
{
    "code": 200,
    "data": {
        "total": 20,
        "records": [
            {
                "id": 1,
                "batchNo": "QT_IMP_20260612143000",
                "fileName": "报价单.xlsx",
                "totalCount": 5,
                "successCount": 5,
                "newCount": 5,
                "failCount": 0,
                "status": "completed",
                "createUserName": "张三",
                "createTime": "2026-06-12 14:30:00"
            }
        ]
    }
}
```

### 3.4 查询降价历史

**请求**
```
GET /sales/quotation/priceHistory/list?quotationProductId=123
```

**响应**
```json
{
    "code": 200,
    "data": [
        {
            "id": 1,
            "productName": "电池组件A",
            "specification": "MODEL-A-100W",
            "oldPrice": 150.00,
            "newPrice": 120.00,
            "priceChange": -30.00,
            "changeReason": "降价",
            "importBatch": "QT_IMP_20260612143000",
            "importTime": "2026-06-12 14:30:00",
            "createUserName": "张三"
        }
    ]
}
```

---

## 四、业务流程

```
下载模板
    │
    ▼
填写报价单数据Sheet（每行一个报价单）
填写报价产品数据Sheet（通过报价单号关联）
    │
    ▼
上传文件
    │
    ▼
检查审批模板是否存在
    │
    ├── 不存在 ──► 错误："请先配置报价审批模板，无法导入"
    │
    └── 存在 ──► 解析两个Sheet数据
    │
    ▼
遍历报价单数据
    │
    ├── 检查报价单号是否已存在 ──► 已存在则跳过
    │
    ├── 创建报价单记录
    ├── 关联产品数据（通过报价单号匹配）
    ├── 记录降价历史（对比历史价格）
    └── 创建审批流程
    │
    ▼
返回导入结果
```

---

## 五、示例数据

**报价单数据Sheet**
| 报价单号 | 客户名称 | 业务员 | 付款方式 | 交货周期 |
|----------|----------|--------|----------|----------|
| QT202606120001 | 示例客户 | 张三 | 月结30天 | 7天 |

**报价产品数据Sheet**
| 报价单号 | 产品大类 | 规格型号 | 单位 | 数量 | 含税单价 | 含税总价 |
|----------|----------|----------|------|------|----------|----------|
| QT202606120001 | 电池组件 | MODEL-A-100W | 片 | 100 | 150.00 | 15000.00 |
| QT202606120001 | 电池组件 | MODEL-B-200W | 片 | 50 | 200.00 | 10000.00 |

---

## 六、数据库变更

需执行：`docs/sales_quotation_price_history.sql`