合作成本和店内支出-前端调用说明.md 21.7 KB

Edit Raw Blame History


合作成本和店内支出 - 前端调用说明
📋 目录

业务流程概述
合作成本接口列表
店内支出接口列表
完整流程示例
接口详细说明
数据验证说明
注意事项

🔄 业务流程概述
合作成本管理
合作成本用于记录门店每月的合作项目成本，用于店长工资计算中的毛利计算。

核心功能：


创建合作成本 - 录入门店某年某月的合作成本金额
查询合作成本 - 支持列表查询和详情查询，可按门店、年份、月份筛选
更新合作成本 - 修改已创建的合作成本记录
删除合作成本 - 删除合作成本记录（逻辑删除）
导入合作成本 - 通过Excel批量导入合作成本数据
导出合作成本 - 导出合作成本数据为Excel文件

店内支出管理
店内支出用于记录门店每月的各项支出，用于店长工资计算中的毛利计算。

核心功能：


创建店内支出 - 录入门店的支出明细（支持分类、单价、数量、金额等）
查询店内支出 - 支持列表查询和详情查询，可按门店、分类、日期范围筛选
更新店内支出 - 修改已创建的店内支出记录
删除店内支出 - 删除店内支出记录（逻辑删除）
导入店内支出 - 通过Excel批量导入店内支出数据
导出店内支出 - 导出店内支出数据为Excel文件

📡 合作成本接口列表


接口
方法
路径
说明


获取合作成本详情
GET
/api/Extend/LqCooperationCost/{id}
根据ID获取合作成本详情


获取合作成本列表
GET
/api/Extend/LqCooperationCost
分页查询合作成本列表，支持多条件筛选


获取全部数据（不分页）
GET
/api/Extend/LqCooperationCost/Actions/GetNoPagingList
获取全部数据，用于导出


创建合作成本
POST
/api/Extend/LqCooperationCost
创建新的合作成本记录


更新合作成本
PUT
/api/Extend/LqCooperationCost/{id}
更新合作成本记录


删除合作成本
DELETE
/api/Extend/LqCooperationCost/{id}
删除合作成本记录（逻辑删除）


导出合作成本
GET
/api/Extend/LqCooperationCost/Actions/Export
导出合作成本数据为Excel


导入合作成本
POST
/api/Extend/LqCooperationCost/Actions/Import
通过Excel导入合作成本数据


📡 店内支出接口列表


接口
方法
路径
说明


获取店内支出详情
GET
/api/Extend/LqStoreExpense/{id}
根据ID获取店内支出详情


获取店内支出列表
GET
/api/Extend/LqStoreExpense
分页查询店内支出列表，支持多条件筛选


获取全部数据（不分页）
GET
/api/Extend/LqStoreExpense/Actions/GetNoPagingList
获取全部数据，用于导出


创建店内支出
POST
/api/Extend/LqStoreExpense
创建新的店内支出记录


更新店内支出
PUT
/api/Extend/LqStoreExpense/{id}
更新店内支出记录


删除店内支出
DELETE
/api/Extend/LqStoreExpense/{id}
删除店内支出记录（逻辑删除）


导出店内支出
GET
/api/Extend/LqStoreExpense/Actions/Export
导出店内支出数据为Excel


导入店内支出
POST
/api/Extend/LqStoreExpense/Actions/Import
通过Excel导入店内支出数据


🚀 完整流程示例
合作成本管理流程
步骤1：创建合作成本
接口： POST /api/Extend/LqCooperationCost

请求示例：
const response = await request({
  url: '/api/Extend/LqCooperationCost',
  method: 'POST',
  data: {
    storeId: '1649328471923847172',  // 门店ID（必填）
    storeName: '绿纤华润店',  // 门店名称（可选，不传则自动查询）
    year: 2025,  // 年份（必填）
    month: '202511',  // 月份（必填，格式：YYYYMM，如202511表示2025年11月）
    totalAmount: 3000.00,  // 合计金额（必填）
    remarks: '测试数据-合作成本'  // 备注说明（可选）
  }
});

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


说明：


如果未提供门店名称，系统会根据门店ID自动查询并填充
月份格式必须为YYYYMM（如：202511表示2025年11月）
同一门店、同一年份、同一月份只能有一条有效记录（如果已存在会报错）

步骤2：查询合作成本列表
接口： GET /api/Extend/LqCooperationCost

请求示例：
const response = await request({
  url: '/api/Extend/LqCooperationCost',
  method: 'GET',
  params: {
    currentPage: 1,  // 当前页码（必填）
    pageSize: 10,  // 每页数量（必填）
    storeId: '1649328471923847172',  // 门店ID（可选）
    storeName: '绿纤华润店',  // 门店名称（可选，模糊查询）
    year: 2025,  // 年份（可选）
    month: '202511',  // 月份（可选，格式：YYYYMM）
    sidx: 'CreateTime',  // 排序字段（可选，默认：CreateTime）
    sort: 'desc'  // 排序方式（可选，asc/desc，默认：desc）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "list": [
//       {
//         "id": "768041985045955845",
//         "storeId": "1649328471923847172",
//         "storeName": "绿纤华润店",
//         "year": 2025,
//         "month": "202511",
//         "totalAmount": 3000.00,
//         "remarks": "测试数据-合作成本",
//         "createUser": "admin",
//         "createTime": "2025-01-10T10:00:00",
//         "updateUser": "admin",
//         "updateTime": "2025-01-10T10:00:00"
//       }
//     ],
//     "pagination": {
//       "total": 1,
//       "pageSize": 10,
//       "currentPage": 1
//     }
//   }
// }

步骤3：更新合作成本
接口： PUT /api/Extend/LqCooperationCost/{id}

请求示例：
const response = await request({
  url: `/api/Extend/LqCooperationCost/${id}`,
  method: 'PUT',
  data: {
    storeId: '1649328471923847172',
    storeName: '绿纤华润店',
    year: 2025,
    month: '202511',
    totalAmount: 3500.00,  // 修改金额
    remarks: '更新后的备注'
  }
});

步骤4：删除合作成本
接口： DELETE /api/Extend/LqCooperationCost/{id}

请求示例：
const response = await request({
  url: `/api/Extend/LqCooperationCost/${id}`,
  method: 'DELETE'
});

步骤5：导出合作成本
接口： GET /api/Extend/LqCooperationCost/Actions/Export

请求示例：
const response = await request({
  url: '/api/Extend/LqCooperationCost/Actions/Export',
  method: 'GET',
  params: {
    storeId: '1649328471923847172',  // 可选
    year: 2025,  // 可选
    month: '202511'  // 可选
  },
  responseType: 'blob'  // 重要：设置响应类型为blob
});

// 下载文件
const blob = new Blob([response.data]);
const url = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.setAttribute('download', `合作成本表_${new Date().getTime()}.xlsx`);
document.body.appendChild(link);
link.click();
document.body.removeChild(link);

步骤6：导入合作成本
接口： POST /api/Extend/LqCooperationCost/Actions/Import

请求示例：
const formData = new FormData();
formData.append('file', file);  // file是File对象

const response = await request({
  url: '/api/Extend/LqCooperationCost/Actions/Import',
  method: 'POST',
  data: formData,
  headers: {
    'Content-Type': 'multipart/form-data'
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "导入成功",
//   "data": {
//     "successCount": 10,
//     "failCount": 2,
//     "failMessages": [
//       "第3行：门店ID不存在",
//       "第5行：该门店2025年11月的记录已存在"
//     ]
//   }
// }


Excel格式要求：


第一行为表头：门店ID、门店名称、年份、月份、合计金额、备注
门店ID和门店名称至少填写一个
月份格式：YYYYMM（如：202511）
合计金额必须为数字

店内支出管理流程
步骤1：创建店内支出
接口： POST /api/Extend/LqStoreExpense

请求示例：
const response = await request({
  url: '/api/Extend/LqStoreExpense',
  method: 'POST',
  data: {
    storeId: '1649328471923847172',  // 门店ID（必填）
    storeName: '绿纤华润店',  // 门店名称（可选，不传则自动查询）
    expenseCategoryId: '11156146041171400',  // 支出分类ID（可选）
    expenseCategoryName: '日常支出',  // 支出分类名称（可选）
    expenseDate: '2025-11-15T00:00:00',  // 支出日期（必填）
    unitPrice: 2000.00,  // 单价（可选）
    quantity: 1,  // 数量（可选）
    amount: 2000.00,  // 金额（必填）
    memo: '测试数据-店内支出',  // 备注说明（可选）
    attachment: [],  // 附件（可选，FileControlsModel数组）
    relatedReimbursementId: '',  // 关联报销申请ID（可选）
    relatedPurchaseRecordId: ''  // 关联购买记录ID（可选）
  }
});

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


说明：


如果未提供门店名称，系统会根据门店ID自动查询并填充
金额字段为必填，单价和数量为可选（如果提供了单价和数量，系统会验证：金额 = 单价 × 数量）
支持附件上传（FileControlsModel格式）

步骤2：查询店内支出列表
接口： GET /api/Extend/LqStoreExpense

请求示例：
const response = await request({
  url: '/api/Extend/LqStoreExpense',
  method: 'GET',
  params: {
    currentPage: 1,  // 当前页码（必填）
    pageSize: 10,  // 每页数量（必填）
    storeId: '1649328471923847172',  // 门店ID（可选）
    storeName: '绿纤华润店',  // 门店名称（可选，模糊查询）
    expenseCategoryId: '11156146041171400',  // 支出分类ID（可选）
    expenseDateStart: '2025-11-01',  // 支出日期开始（可选）
    expenseDateEnd: '2025-11-30',  // 支出日期结束（可选）
    sidx: 'ExpenseDate',  // 排序字段（可选，默认：ExpenseDate）
    sort: 'desc'  // 排序方式（可选，asc/desc，默认：desc）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "list": [
//       {
//         "id": "768041985045955845",
//         "storeId": "1649328471923847172",
//         "storeName": "绿纤华润店",
//         "expenseCategoryId": "11156146041171400",
//         "expenseCategoryName": "日常支出",
//         "expenseDate": "2025-11-15T00:00:00",
//         "unitPrice": 2000.00,
//         "quantity": 1,
//         "amount": 2000.00,
//         "memo": "测试数据-店内支出",
//         "attachment": [],
//         "relatedReimbursementId": "",
//         "relatedPurchaseRecordId": "",
//         "createUser": "admin",
//         "createTime": "2025-01-10T10:00:00",
//         "updateUser": "admin",
//         "updateTime": "2025-01-10T10:00:00"
//       }
//     ],
//     "pagination": {
//       "total": 1,
//       "pageSize": 10,
//       "currentPage": 1
//     }
//   }
// }

步骤3：更新店内支出
接口： PUT /api/Extend/LqStoreExpense/{id}

请求示例：
const response = await request({
  url: `/api/Extend/LqStoreExpense/${id}`,
  method: 'PUT',
  data: {
    storeId: '1649328471923847172',
    storeName: '绿纤华润店',
    expenseCategoryId: '11156146041171400',
    expenseCategoryName: '日常支出',
    expenseDate: '2025-11-15T00:00:00',
    unitPrice: 2500.00,  // 修改单价
    quantity: 1,
    amount: 2500.00,  // 修改金额
    memo: '更新后的备注',
    attachment: []
  }
});

步骤4：删除店内支出
接口： DELETE /api/Extend/LqStoreExpense/{id}

请求示例：
const response = await request({
  url: `/api/Extend/LqStoreExpense/${id}`,
  method: 'DELETE'
});

步骤5：导出店内支出
接口： GET /api/Extend/LqStoreExpense/Actions/Export

请求示例：
const response = await request({
  url: '/api/Extend/LqStoreExpense/Actions/Export',
  method: 'GET',
  params: {
    storeId: '1649328471923847172',  // 可选
    expenseCategoryId: '11156146041171400',  // 可选
    expenseDateStart: '2025-11-01',  // 可选
    expenseDateEnd: '2025-11-30'  // 可选
  },
  responseType: 'blob'  // 重要：设置响应类型为blob
});

// 下载文件（同合作成本导出）

步骤6：导入店内支出
接口： POST /api/Extend/LqStoreExpense/Actions/Import

请求示例：
const formData = new FormData();
formData.append('file', file);  // file是File对象

const response = await request({
  url: '/api/Extend/LqStoreExpense/Actions/Import',
  method: 'POST',
  data: formData,
  headers: {
    'Content-Type': 'multipart/form-data'
  }
});

// 响应示例（同合作成本导入）


Excel格式要求：


第一行为表头：门店ID、门店名称、支出分类ID、支出分类名称、支出日期、单价、数量、金额、备注
门店ID和门店名称至少填写一个
支出日期格式：YYYY-MM-DD 或 YYYY-MM-DD HHss
金额必须为数字

📝 接口详细说明
合作成本接口
1. 获取合作成本详情
接口： GET /api/Extend/LqCooperationCost/{id}

路径参数：


id：合作成本记录ID（必填）


响应示例：
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "768041985045955845",
    "storeId": "1649328471923847172",
    "storeName": "绿纤华润店",
    "year": 2025,
    "month": "202511",
    "totalAmount": 3000.00,
    "remarks": "测试数据-合作成本",
    "createUser": "admin",
    "createTime": "2025-01-10T10:00:00",
    "updateUser": "admin",
    "updateTime": "2025-01-10T10:00:00"
  }
}

2. 获取合作成本列表
接口： GET /api/Extend/LqCooperationCost

查询参数：


currentPage：当前页码（必填，默认：1）
pageSize：每页数量（必填，默认：10）
storeId：门店ID（可选）
storeName：门店名称（可选，模糊查询）
year：年份（可选）
month：月份（可选，格式：YYYYMM）
sidx：排序字段（可选，默认：CreateTime）
sort：排序方式（可选，asc/desc，默认：desc）


响应格式： 同列表查询标准格式
3. 创建合作成本
接口： POST /api/Extend/LqCooperationCost

请求体：
{
  "storeId": "1649328471923847172",  // 门店ID（必填）
  "storeName": "绿纤华润店",  // 门店名称（可选）
  "year": 2025,  // 年份（必填）
  "month": "202511",  // 月份（必填，格式：YYYYMM）
  "totalAmount": 3000.00,  // 合计金额（必填）
  "remarks": "备注说明"  // 备注（可选）
}


验证规则：


门店ID必填
年份必填，必须大于0
月份必填，格式必须为YYYYMM（6位数字）
合计金额必填，必须大于等于0
同一门店、同一年份、同一月份只能有一条有效记录

4. 更新合作成本
接口： PUT /api/Extend/LqCooperationCost/{id}

路径参数：


id：合作成本记录ID（必填）


请求体： 同创建接口
5. 删除合作成本
接口： DELETE /api/Extend/LqCooperationCost/{id}

路径参数：


id：合作成本记录ID（必填）


说明： 执行逻辑删除，不会真正删除数据
店内支出接口
1. 获取店内支出详情
接口： GET /api/Extend/LqStoreExpense/{id}

路径参数：


id：店内支出记录ID（必填）


响应示例：
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "768041985045955845",
    "storeId": "1649328471923847172",
    "storeName": "绿纤华润店",
    "expenseCategoryId": "11156146041171400",
    "expenseCategoryName": "日常支出",
    "expenseDate": "2025-11-15T00:00:00",
    "unitPrice": 2000.00,
    "quantity": 1,
    "amount": 2000.00,
    "memo": "测试数据-店内支出",
    "attachment": [],
    "relatedReimbursementId": "",
    "relatedPurchaseRecordId": "",
    "createUser": "admin",
    "createTime": "2025-01-10T10:00:00",
    "updateUser": "admin",
    "updateTime": "2025-01-10T10:00:00"
  }
}

2. 获取店内支出列表
接口： GET /api/Extend/LqStoreExpense

查询参数：


currentPage：当前页码（必填，默认：1）
pageSize：每页数量（必填，默认：10）
storeId：门店ID（可选）
storeName：门店名称（可选，模糊查询）
expenseCategoryId：支出分类ID（可选）
expenseDateStart：支出日期开始（可选，格式：YYYY-MM-DD）
expenseDateEnd：支出日期结束（可选，格式：YYYY-MM-DD）
sidx：排序字段（可选，默认：ExpenseDate）
sort：排序方式（可选，asc/desc，默认：desc）


响应格式： 同列表查询标准格式
3. 创建店内支出
接口： POST /api/Extend/LqStoreExpense

请求体：
{
  "storeId": "1649328471923847172",  // 门店ID（必填）
  "storeName": "绿纤华润店",  // 门店名称（可选）
  "expenseCategoryId": "11156146041171400",  // 支出分类ID（可选）
  "expenseCategoryName": "日常支出",  // 支出分类名称（可选）
  "expenseDate": "2025-11-15T00:00:00",  // 支出日期（必填）
  "unitPrice": 2000.00,  // 单价（可选）
  "quantity": 1,  // 数量（可选）
  "amount": 2000.00,  // 金额（必填）
  "memo": "备注说明",  // 备注（可选）
  "attachment": [],  // 附件（可选，FileControlsModel数组）
  "relatedReimbursementId": "",  // 关联报销申请ID（可选）
  "relatedPurchaseRecordId": ""  // 关联购买记录ID（可选）
}


验证规则：


门店ID必填
支出日期必填
金额必填，必须大于等于0
如果提供了单价和数量，系统会验证：金额 = 单价 × 数量

4. 更新店内支出
接口： PUT /api/Extend/LqStoreExpense/{id}

路径参数：


id：店内支出记录ID（必填）


请求体： 同创建接口
5. 删除店内支出
接口： DELETE /api/Extend/LqStoreExpense/{id}

路径参数：


id：店内支出记录ID（必填）


说明： 执行逻辑删除，不会真正删除数据
✅ 数据验证说明
合作成本验证规则

门店ID验证


必填
如果门店ID不存在，会报错

年份验证


必填
必须为整数，大于0

月份验证


必填
格式必须为YYYYMM（6位数字，如：202511）
月份必须在1-12之间

合计金额验证


必填
必须为数字，大于等于0

唯一性验证


同一门店、同一年份、同一月份只能有一条有效记录
如果已存在，创建时会报错


店内支出验证规则

门店ID验证


必填
如果门店ID不存在，会报错

支出日期验证


必填
格式：YYYY-MM-DD 或 YYYY-MM-DD HHss

金额验证


必填
必须为数字，大于等于0

单价和数量验证


如果同时提供了单价和数量，系统会验证：金额 = 单价 × 数量
如果验证失败，会报错


⚠️ 注意事项
合作成本注意事项

月份格式


月份必须使用YYYYMM格式（如：202511表示2025年11月）
不要使用YYYY-MM格式

唯一性约束


同一门店、同一年份、同一月份只能有一条有效记录
如果需要修改，请使用更新接口，不要重复创建

门店名称自动填充


如果未提供门店名称，系统会根据门店ID自动查询并填充
建议前端也自动填充，提升用户体验

导入Excel格式


第一行必须是表头
门店ID和门店名称至少填写一个
月份格式必须为YYYYMM（6位数字）


店内支出注意事项

金额计算


如果同时提供了单价和数量，系统会验证：金额 = 单价 × 数量
建议前端在用户输入单价和数量时自动计算金额

附件上传


附件使用FileControlsModel格式
支持多个附件

关联字段


relatedReimbursementId：关联报销申请ID（可选）
relatedPurchaseRecordId：关联购买记录ID（可选）
这些字段用于数据追溯，建议填写

导入Excel格式


第一行必须是表头
门店ID和门店名称至少填写一个
支出日期格式：YYYY-MM-DD 或 YYYY-MM-DD HHss


通用注意事项

GET请求参数


所有GET请求使用params传参，不使用data
分页参数currentPage和pageSize必填

文件下载


导出接口返回的是文件流，需要设置responseType: 'blob'
下载文件时需要创建Blob对象并触发下载

文件上传


导入接口需要使用FormData格式
设置Content-Type: 'multipart/form-data'

错误处理


所有接口返回标准格式：{code, msg, data}
code === 200表示成功，其他表示失败
失败时查看msg字段获取错误信息

数据删除


删除操作执行的是逻辑删除，不会真正删除数据
删除后的数据在列表中不会显示，但可以通过数据库查询

店长工资计算


合作成本和店内支出数据用于店长工资计算中的毛利计算
确保数据的准确性和及时性，避免影响工资计算结果