# 出入库记录导入导出功能说明

## 功能概述

本系统提供了完整的出入库记录导入导出功能，支持Excel格式的数据导入和导出。

## 导入功能

### 导入接口
- **接口地址**: `POST /smErpInventoryRecords/import`
- **权限要求**: `supermarket_smErpInventoryRecords_import`
- **请求参数**: Excel文件（multipart/form-data）

### 导入字段说明

| 字段名 | 说明 | 是否必填 | 示例 |
|--------|------|----------|------|
| 单据编号 | 出入库单据编号，系统自动生成 | 是 | INV202502140001 |
| 单据日期 | 出入库日期 | 是 | 2025-02-14 |
| 单据类型 | 出入库类型（采购入库、采购退货、盘点入库等） | 是 | 采购入库 |
| 经办人名称 | 经办人姓名 | 否 | 张三 |
| 货商名称 | 供应商名称 | 否 | 某某供应商 |
| 备注 | 备注信息 | 否 | 正常入库 |
| 订单类型 | 1入库 2出库 | 是 | 1 |
| 总金额 | 总金额（分） | 否 | 10000 |
| 商品名称 | 商品名称 | 否 | 苹果 |
| 收货数量 | 收货数量 | 否 | 100 |
| 单价 | 单价（分） | 否 | 100 |
| 包装单位 | 包装单位名称 | 否 | 箱 |

### 导入规则

1. **数据校验**：
   - 单据编号不能为空且不能重复
   - 单据日期不能为空
   - 单据类型不能为空

2. **业务逻辑**：
   - 导入的记录默认审批状态为"已通过"
   - 经办人名称会转换为用户ID（如果找不到则使用当前用户）
   - 货商名称会转换为货商ID（如果找不到则设为null）
   - 商品名称会查找对应的商品ID
   - 包装单位会查找对应的单位ID

3. **错误处理**：
   - 导入过程中会记录详细的错误信息
   - 支持部分成功导入（部分数据成功，部分失败）

## 导出功能

### 明细导出接口
- **接口地址**: `GET /smErpInventoryRecords/export`
- **权限要求**: `supermarket_smErpInventoryRecords_export`
- **请求参数**: 
  - `smErpInventoryRecords`: 查询条件
  - `ids`: 指定导出的ID数组

### 汇总导出接口
- **接口地址**: `GET /smErpInventoryRecords/exportSummary`
- **权限要求**: `supermarket_smErpInventoryRecords_export`
- **请求参数**: 
  - `smErpInventoryRecords`: 查询条件
  - `ids`: 指定导出的ID数组

### 明细导出字段说明

| 字段名 | 说明 | 示例 |
|--------|------|------|
| 单据编号 | 出入库单据编号 | INV202502140001 |
| 单据日期 | 出入库日期 | 2025-02-14 |
| 单据类型 | 出入库类型（中文显示） | 采购入库 |
| 经办人 | 经办人姓名 | 张三 |
| 货商 | 货商名称 | 某某供应商 |
| 备注 | 备注信息 | 正常入库 |
| 订单类型 | 入库/出库（中文显示） | 入库 |
| 总金额(元) | 明细总金额（元） | 100.00 |
| 创建人 | 创建人 | admin |
| 创建时间 | 创建时间 | 2025-02-14 10:00:00 |
| 商品名称 | 单个商品名称 | 苹果 |
| 收货数量 | 单个商品收货数量 | 100 |
| 货商名称 | 货商名称 | 某某供应商 |
| 单价(元) | 商品单价（元） | 1.00 |
| 包装单位 | 包装单位名称 | 箱 |
| 规格 | 商品规格 | 500ml |
| 内装数 | 包装内装数量 | 12 |

### 汇总导出字段说明

| 字段名 | 说明 | 示例 |
|--------|------|------|
| 单据编号 | 出入库单据编号 | INV202502140001 |
| 单据日期 | 出入库日期 | 2025-02-14 |
| 单据类型 | 出入库类型（中文显示） | 采购入库 |
| 经办人 | 经办人姓名 | 张三 |
| 货商 | 货商名称 | 某某供应商 |
| 备注 | 备注信息 | 正常入库 |
| 订单类型 | 入库/出库（中文显示） | 入库 |
| 总金额(元) | 汇总总金额（元） | 500.00 |
| 创建人 | 创建人 | admin |
| 创建时间 | 创建时间 | 2025-02-14 10:00:00 |
| 商品名称 | 商品名称 | 苹果 |
| 汇总数量 | 该商品总数量（基础单位） | 300 |
| 货商名称 | 货商名称 | 某某供应商 |
| 汇总单价(元) | 平均单价（元） | 1.67 |
| 期初库存 | 期初库存数量 | 100.0 |
| 当前库存 | 当前库存数量 | 400.0 |
| 包装单位 | 基础包装单位名称 | 瓶 |
| 规格 | 商品规格 | 500ml |
| 内装数 | 基础包装内装数量 | 1 |

### 导出规则

1. **明细导出**：
   - 每个商品明细占一行
   - 如果一个出入库记录有多个商品，会生成多行数据
   - 每行显示单个商品的详细信息
   - 显示该商品使用的包装单位信息

2. **汇总导出**：
   - 按商品汇总，每个商品占一行
   - 汇总该商品在所有相关记录中的数量和金额
   - 显示期初库存和当前库存信息
   - 计算平均单价
   - **数量转换**：所有数量都转换为基础单位
   - **单位显示**：显示基础包装单位信息

3. **包装单位转换规则**：
   - 明细导出：显示实际使用的包装单位
   - 汇总导出：统一转换为基础单位
   - 转换公式：基础单位数量 = 包装单位数量 × 内装数
   - 例如：2箱 × 12瓶/箱 = 24瓶（基础单位）

4. **数据查询**：
   - 支持按条件筛选导出
   - 支持按ID数组导出指定记录
   - 默认按创建时间倒序排列

5. **数据转换**：
   - 自动关联查询经办人姓名
   - 自动关联查询货商名称
   - 自动关联查询商品信息
   - 单据类型自动转换为中文显示
   - 订单类型自动转换为中文显示
   - 金额从分转换为元显示
   - 包装单位信息自动关联

6. **单据类型映射**：
   - 1 → 采购申请
   - 2 → 采购订单
   - 3 → 采购入库
   - 4 → 采购退货
   - 5 → 零售出库
   - 6 → 零售退货
   - 7 → 库存盘点

7. **订单类型映射**：
   - 1 → 入库
   - 2 → 出库
   - 0 → 无盈亏

### 明细导出示例

假设有一个出入库记录包含3个商品：
- 苹果：100个，单价100分（1元），总金额10000分（100元），包装单位：箱，内装数：12
- 香蕉：50个，单价80分（0.8元），总金额4000分（40元），包装单位：箱，内装数：20
- 橙子：30个，单价120分（1.2元），总金额3600分（36元），包装单位：瓶，内装数：1

明细导出的Excel将包含3行数据：
```
单据编号 | 单据日期 | 单据类型 | 经办人 | 商品名称 | 收货数量 | 单价(元) | 总金额(元) | 包装单位 | 规格 | 内装数
INV001   | 2025-02-14 | 采购入库 | 张三 | 苹果 | 100 | 1.00 | 100.00 | 箱 | 500ml | 12
INV001   | 2025-02-14 | 采购入库 | 张三 | 香蕉 | 50  | 0.80 | 40.00 | 箱 | 1kg | 20
INV001   | 2025-02-14 | 采购入库 | 张三 | 橙子 | 30  | 1.20 | 36.00 | 瓶 | 500ml | 1
```

### 汇总导出示例

假设有多个出入库记录，包含相同的商品：
- 苹果：记录1中100箱，记录2中200箱，记录3中50箱（内装数：12瓶/箱）
- 香蕉：记录1中50箱，记录2中30箱（内装数：20个/箱）
- 橙子：记录1中30瓶，记录3中20瓶（内装数：1个/瓶）

汇总导出的Excel将包含3行数据（按商品汇总，数量转换为基础单位）：
```
商品名称 | 汇总数量(瓶) | 汇总单价(元) | 总金额(元) | 期初库存 | 当前库存 | 经办人 | 包装单位 | 规格 | 内装数
苹果     | 4200        | 1.00        | 4200.00   | 1200.0  | 5400.0  | 张三 | 瓶 | 500ml | 1
香蕉     | 1600        | 0.80        | 1280.00   | 1000.0  | 2600.0  | 李四 | 个 | 1kg | 1
橙子     | 50          | 1.20        | 60.00     | 30.0    | 80.0    | 王五 | 个 | 500ml | 1
```

**数量转换说明**：
- 苹果：100箱 + 200箱 + 50箱 = 350箱 × 12瓶/箱 = 4200瓶
- 香蕉：50箱 + 30箱 = 80箱 × 20个/箱 = 1600个
- 橙子：30瓶 + 20瓶 = 50瓶 × 1个/瓶 = 50个

## 使用示例

### 导入示例

```bash
# 使用curl导入Excel文件
curl -X POST \
  http://localhost:8080/smErpInventoryRecords/import \
  -H 'Authorization: Bearer your-token' \
  -F 'file=@inventory_records.xlsx'
```

### 导出示例

```bash
# 导出所有记录明细
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/export' \
  -H 'Authorization: Bearer your-token'

# 导出指定ID的记录明细
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/export?ids=1,2,3' \
  -H 'Authorization: Bearer your-token'

# 按条件导出明细
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/export?inventoryType=采购入库' \
  -H 'Authorization: Bearer your-token'

# 导出所有记录汇总
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/exportSummary' \
  -H 'Authorization: Bearer your-token'

# 导出指定ID的记录汇总
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/exportSummary?ids=1,2,3' \
  -H 'Authorization: Bearer your-token'

# 按条件导出汇总
curl -X GET \
  'http://localhost:8080/smErpInventoryRecords/exportSummary?inventoryType=采购入库' \
  -H 'Authorization: Bearer your-token'
```

## 注意事项

1. **文件格式**：支持.xlsx格式的Excel文件
2. **数据量**：建议单次导入不超过1000条记录
3. **编码格式**：Excel文件应使用UTF-8编码
4. **权限控制**：需要相应的导入导出权限
5. **事务处理**：导入操作支持事务回滚
6. **错误处理**：导入失败会返回详细的错误信息
7. **明细显示**：明细导出时会为每个商品明细生成一行数据
8. **汇总显示**：汇总导出时会按商品汇总，每个商品一行
9. **中文转换**：单据类型和订单类型会自动转换为中文显示
10. **库存信息**：汇总导出会显示期初库存和当前库存信息
11. **包装单位**：明细导出显示实际使用的包装单位，汇总导出统一转换为基础单位
12. **数量转换**：汇总导出时所有数量都会根据内装数转换为基础单位
13. **单位关联**：如果商品没有指定包装单位，会自动关联基础包装单位

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 400 | 导入数据不能为空 | 检查Excel文件是否包含数据 |
| 400 | 单据编号已存在 | 修改单据编号或删除已存在的记录 |
| 400 | 单据类型不能为空 | 填写单据类型字段 |
| 400 | 单据日期不能为空 | 填写单据日期字段 |
| 500 | 处理失败 | 检查数据格式和业务逻辑 |

## 更新日志

- 2025-02-14: 完成导入导出功能开发
- 2025-02-14: 修复Excel字段映射错误
- 2025-02-14: 添加数据校验和错误处理
- 2025-02-14: 完善文档说明
- 2025-02-14: 优化导出功能，显示所有商品名称
- 2025-02-14: 添加单据类型和订单类型中文转换
- 2025-02-14: 去掉审批状态和审批原因字段
- 2025-02-14: 改为明细导出，每个商品占一行
- 2025-02-14: 添加汇总导出功能，按商品汇总显示
- 2025-02-14: 汇总导出包含期初库存和当前库存信息