库存使用审批流程-前端调用说明.md 12.9 KB

Edit Raw Blame History


库存使用审批流程 - 前端调用说明
📋 目录

业务流程概述
接口列表
完整流程示例
接口详细说明
注意事项

🔄 业务流程概述
库存使用审批流程包含以下步骤：


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

📡 接口列表


接口
方法
路径
说明


批量创建使用记录
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

请求示例：
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

请求示例：
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}

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

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


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


说明：


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

步骤4：标记已领取（审批通过后）
接口： PUT /api/Extend/LqInventoryUsage/MarkReceived/{applicationId}

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

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


说明：


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

步骤5：查询批次信息
接口： GET /api/Extend/LqInventoryUsage/GetBatchInfo

请求示例：
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

请求示例：
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（可选）

⚠️ 注意事项

审批人ID和申请门店ID必填


创建使用记录时，approverId 和 applicationStoreId 必须传入
系统会自动创建申请记录并提交审批

兼容旧数据


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

审批流程


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

标记已领取


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

单价和合计金额


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

URL编码


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


🔍 状态说明
审批状态（approvalStatus）

待审批: 申请已创建，等待提交审批
审批中: 申请已提交，等待审批
已通过: 审批通过
未通过: 审批不通过
已退回: 申请被退回

领取状态（isReceived）

0: 未领取
1: 已领取

📊 数据流程
创建使用记录 → 创建申请记录（审批中） → 审批申请 → 标记已领取
     ↓                ↓                    ↓            ↓
  批次ID          申请ID              审批记录      领取记录

🎯 前端页面建议

创建使用记录页面


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

申请列表页面


显示所有申请记录
显示审批状态、是否已领取
支持筛选：审批状态、是否已领取、门店等

审批页面


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

批次详情页面


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

统计页面


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