279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
# 出入库记录导入导出功能说明
|
||
|
||
## 功能概述
|
||
|
||
本系统提供了完整的出入库记录导入导出功能，支持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: 汇总导出包含期初库存和当前库存信息 |