# 库存使用审批流程 - 前端调用说明

## 📋 目录
- [业务流程概述](#业务流程概述)
- [接口列表](#接口列表)
- [完整流程示例](#完整流程示例)
- [接口详细说明](#接口详细说明)
- [注意事项](#注意事项)

## 🔄 业务流程概述

库存使用审批流程包含以下步骤：

1. **创建使用记录并提交审批** - 批量创建库存使用记录，同时创建申请记录并提交审批
2. **查询申请记录** - 根据批次ID查询申请记录，查看审批状态
3. **审批申请** - 审批人（财务老师或库管）审批申请（通过/不通过）
4. **标记已领取** - 审批通过后，标记申请已领取
5. **查询批次信息** - 查询批次详细信息，包括使用记录和申请记录
6. **门店领取统计** - 按月份统计每个门店的领取总金额

## 📡 接口列表

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 批量创建使用记录 | POST | `/api/Extend/LqInventoryUsage/BatchCreate` | 创建使用记录并提交审批（审批人ID和申请门店ID必填） |
| 查询申请记录 | GET | `/api/Extend/LqInventoryUsage/GetApplicationByBatchId` | 根据批次ID查询申请记录 |
| 审批申请 | POST | `/api/Extend/LqInventoryUsage/Approve/{applicationId}` | 审批申请（通过/不通过） |
| 标记已领取 | PUT | `/api/Extend/LqInventoryUsage/MarkReceived/{applicationId}` | 标记申请已领取 |
| 查询批次信息 | GET | `/api/Extend/LqInventoryUsage/GetBatchInfo` | 查询批次详细信息 |
| 门店领取统计 | POST | `/api/Extend/LqInventoryUsage/GetStoreReceiveStatistics` | 按月份统计门店领取总金额 |

## 🚀 完整流程示例

### 步骤1：创建使用记录并提交审批

**接口：** `POST /api/Extend/LqInventoryUsage/BatchCreate`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/BatchCreate',
  method: 'POST',
  data: {
    approverId: '13110190690',  // 审批人ID（财务老师或库管，必填）
    applicationStoreId: '1649328471923847168',  // 申请门店ID（必填）
    remarks: '测试审批流程',  // 备注（可选）
    usageItems: [
      {
        productId: '763978766132184325',  // 产品ID（必填）
        storeId: '1649328471923847168',  // 门店ID（必填）
        usageTime: '2025-01-09T10:00:00',  // 使用时间（必填）
        usageQuantity: 10,  // 使用数量（必填，必须大于0）
        relatedConsumeId: ''  // 关联消耗ID（可选）
      },
      {
        productId: '763979169120912645',
        storeId: '1649328471923847168',
        usageTime: '2025-01-09T10:00:00',
        usageQuantity: 20,
        relatedConsumeId: ''
      }
    ]
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "batchId": "768041985045955845",  // 批次ID，后续查询需要使用
//     "successCount": 2,
//     "failCount": 0,
//     "successIds": ["768041987361211653", "768041987361211654"],
//     "failItems": []
//   }
// }
```

**说明：**
- 系统会自动计算单价（从产品表获取）和合计金额（单价×数量）
- 创建使用记录后会自动创建申请记录，状态为"审批中"
- 保存返回的 `batchId`，后续查询需要使用

### 步骤2：查询申请记录（可选）

**接口：** `GET /api/Extend/LqInventoryUsage/GetApplicationByBatchId`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/GetApplicationByBatchId',
  method: 'GET',
  params: {
    batchId: '768041985045955845'  // 批次ID
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "success": true,
//     "data": {
//       "id": "768041987952608518",  // 申请ID
//       "usageBatchId": "768041985045955845",
//       "applicationUserId": "admin",
//       "applicationUserName": "管理员",
//       "applicationStoreId": "1649328471923847168",
//       "applicationTime": 1765280681000,
//       "approvalStatus": "审批中",  // 审批状态：待审批/审批中/已通过/未通过
//       "isReceived": 0,  // 是否已领取：0-未领取，1-已领取
//       "receiveTime": null,
//       "receiveUser": null,
//       "remarks": "测试审批流程",
//       "approvalRecords": []  // 审批记录列表
//     }
//   }
// }

// 注意：如果是旧数据（没有申请记录），返回：
// {
//   "code": 200,
//   "data": {
//     "success": false,
//     "message": "该批次没有对应的申请记录",
//     "data": null
//   }
// }
```

### 步骤3：审批申请

**接口：** `POST /api/Extend/LqInventoryUsage/Approve/{applicationId}`

**请求示例（通过）：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/Approve/768041987952608518',
  method: 'POST',
  params: {
    result: '通过',  // 审批结果：通过/不通过
    opinion: '同意申请'  // 审批意见（可选）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": null
// }
```

**请求示例（不通过）：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/Approve/768041987952608518',
  method: 'POST',
  params: {
    result: '不通过',
    opinion: '库存不足，暂不批准'
  }
});
```

**说明：**
- 只有状态为"审批中"的申请才能进行审批操作
- 审批通过后，状态变为"已通过"
- 审批不通过后，状态变为"未通过"

### 步骤4：标记已领取（审批通过后）

**接口：** `PUT /api/Extend/LqInventoryUsage/MarkReceived/{applicationId}`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/MarkReceived/768041987952608518',
  method: 'PUT'
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": null
// }
```

**说明：**
- 只有审批状态为"已通过"的申请才能标记为已领取
- 标记后会记录领取时间和领取人

### 步骤5：查询批次信息

**接口：** `GET /api/Extend/LqInventoryUsage/GetBatchInfo`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/GetBatchInfo',
  method: 'GET',
  params: {
    batchId: '768041985045955845'  // 批次ID
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "batchId": "768041985045955845",
//     "createTime": 1765280681000,
//     "createUser": "admin",
//     "createUserName": "管理员",
//     "totalCount": 2,
//     "effectiveCount": 2,
//     "ineffectiveCount": 0,
//     "totalUsageQuantity": 30,
//     "totalUsageAmount": 220.00,  // 总使用金额
//     "usageRecords": [
//       {
//         "id": "768041987361211653",
//         "productId": "763978766132184325",
//         "productName": "卸妆油",
//         "productPrice": 10.00,
//         "storeId": "1649328471923847168",
//         "storeName": "绿纤总部",
//         "usageTime": 1736388000000,
//         "usageQuantity": 10,
//         "usageTotalValue": 100.00  // 该条记录的总金额
//       },
//       // ... 更多记录
//     ],
//     "applicationInfo": {  // 申请记录信息（如果是旧数据，此字段为null）
//       "id": "768041987952608518",
//       "applicationUserId": "admin",
//       "applicationUserName": "管理员",
//       "applicationStoreId": "1649328471923847168",
//       "applicationTime": 1765280681000,
//       "approvalStatus": "已通过",
//       "isReceived": 1,
//       "receiveTime": 1765280756000,
//       "receiveUser": "admin",
//       "remarks": "测试审批流程"
//     }
//   }
// }
```

**说明：**
- 兼容旧数据：如果该批次没有申请记录（旧数据），`applicationInfo` 字段为 `null`
- 包含该批次的所有使用记录详情
- 包含申请记录信息（如果有）

### 步骤6：门店领取统计（可选）

**接口：** `POST /api/Extend/LqInventoryUsage/GetStoreReceiveStatistics`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqInventoryUsage/GetStoreReceiveStatistics',
  method: 'POST',
  data: {
    year: 2025,  // 统计年份（必填）
    month: 11,  // 统计月份（必填，1-12）
    storeId: ''  // 门店ID（可选，不传则统计所有门店）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "success": true,
//     "data": [
//       {
//         "storeId": "1649328471923847168",
//         "storeName": "绿纤总部",
//         "applicationCount": 5,  // 申请数量
//         "totalAmount": 1500.00  // 领取总金额
//       },
//       // ... 更多门店
//     ],
//     "total": 10,
//     "message": "查询成功，共10个门店"
//   }
// }
```

**说明：**
- 只统计审批通过且已领取的申请
- 按门店分组统计
- 按总金额降序排列

## 📝 接口详细说明

### 1. 批量创建使用记录

**必填参数：**
- `approverId`: 审批人ID（财务老师或库管）
- `applicationStoreId`: 申请门店ID
- `usageItems`: 使用记录列表（至少一条）
  - `productId`: 产品ID
  - `storeId`: 门店ID
  - `usageTime`: 使用时间
  - `usageQuantity`: 使用数量（必须大于0）

**可选参数：**
- `batchId`: 批次ID（不传则自动生成）
- `remarks`: 备注

**自动计算：**
- `unitPrice`: 单价（从产品表获取）
- `totalAmount`: 合计金额（单价×数量）

### 2. 查询申请记录

**参数：**
- `batchId`: 批次ID（必填）

**返回说明：**
- 如果存在申请记录：返回完整的申请信息
- 如果不存在申请记录（旧数据）：返回 `success=false`，`data=null`

### 3. 审批申请

**参数：**
- `applicationId`: 申请ID（路径参数）
- `result`: 审批结果（查询参数，必填，值：通过/不通过）
- `opinion`: 审批意见（查询参数，可选）

**状态要求：**
- 只有状态为"审批中"的申请才能进行审批操作

### 4. 标记已领取

**参数：**
- `applicationId`: 申请ID（路径参数）

**状态要求：**
- 只有审批状态为"已通过"的申请才能标记为已领取

### 5. 查询批次信息

**参数：**
- `batchId`: 批次ID（必填）

**兼容性：**
- 兼容旧数据：如果该批次没有申请记录，`applicationInfo` 字段为 `null`

### 6. 门店领取统计

**参数：**
- `year`: 统计年份（必填，范围：2020-2100）
- `month`: 统计月份（必填，范围：1-12）
- `storeId`: 门店ID（可选）

## ⚠️ 注意事项

1. **审批人ID和申请门店ID必填**
   - 创建使用记录时，`approverId` 和 `applicationStoreId` 必须传入
   - 系统会自动创建申请记录并提交审批

2. **兼容旧数据**
   - 查询申请记录时，如果该批次没有申请记录（旧数据），会返回 `success=false`
   - 查询批次信息时，如果该批次没有申请记录，`applicationInfo` 字段为 `null`
   - 前端需要兼容这两种情况

3. **审批流程**
   - 申请创建后，状态为"审批中"
   - 只有"审批中"状态的申请才能进行审批操作
   - 审批通过后，状态变为"已通过"
   - 审批不通过后，状态变为"未通过"

4. **标记已领取**
   - 只有"已通过"状态的申请才能标记为已领取
   - 标记后会记录领取时间和领取人

5. **单价和合计金额**
   - 系统会自动计算单价（从产品表获取）和合计金额（单价×数量）
   - 前端无需手动计算

6. **URL编码**
   - 审批接口的参数如果包含中文，需要进行URL编码
   - 例如：`result=通过` 需要编码为 `result=%E9%80%9A%E8%BF%87`

## 🔍 状态说明

### 审批状态（approvalStatus）
- `待审批`: 申请已创建，等待提交审批
- `审批中`: 申请已提交，等待审批
- `已通过`: 审批通过
- `未通过`: 审批不通过
- `已退回`: 申请被退回

### 领取状态（isReceived）
- `0`: 未领取
- `1`: 已领取

## 📊 数据流程

```
创建使用记录 → 创建申请记录（审批中） → 审批申请 → 标记已领取
     ↓                ↓                    ↓            ↓
  批次ID          申请ID              审批记录      领取记录
```

## 🎯 前端页面建议

1. **创建使用记录页面**
   - 表单包含：产品选择、门店选择、使用时间、使用数量
   - 必须选择审批人（财务老师或库管）
   - 必须选择申请门店
   - 提交后显示批次ID

2. **申请列表页面**
   - 显示所有申请记录
   - 显示审批状态、是否已领取
   - 支持筛选：审批状态、是否已领取、门店等

3. **审批页面**
   - 显示申请详情
   - 显示使用记录列表
   - 审批操作：通过/不通过，可填写审批意见

4. **批次详情页面**
   - 显示批次基本信息
   - 显示使用记录列表（包含单价和合计金额）
   - 显示申请记录信息（如果有）
   - 兼容旧数据（没有申请记录的情况）

5. **统计页面**
   - 选择年份和月份
   - 显示每个门店的领取统计
   - 显示总金额、申请数量等