antissoft / lvqianmeiye_ERP

  # 库存使用审批流程 - 前端调用说明
  
  ## 📋 目录
  - [业务流程概述](#业务流程概述)
  - [接口列表](#接口列表)
  - [完整流程示例](#完整流程示例)
  - [接口详细说明](#接口详细说明)
  - [注意事项](#注意事项)
  
  ## 🔄 业务流程概述
  
  库存使用审批流程包含以下步骤：
  
  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. **统计页面**
     - 选择年份和月份
     - 显示每个门店的领取统计
     - 显示总金额、申请数量等