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

## 📋 目录
- [业务流程概述](#业务流程概述)
- [合作成本接口列表](#合作成本接口列表)
- [店内支出接口列表](#店内支出接口列表)
- [完整流程示例](#完整流程示例)
- [接口详细说明](#接口详细说明)
- [数据验证说明](#数据验证说明)
- [注意事项](#注意事项)

## 🔄 业务流程概述

### 合作成本管理
合作成本用于记录门店每月的合作项目成本，用于店长工资计算中的毛利计算。

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

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

**核心功能：**
1. **创建店内支出** - 录入门店的支出明细（支持分类、单价、数量、金额等）
2. **查询店内支出** - 支持列表查询和详情查询，可按门店、分类、日期范围筛选
3. **更新店内支出** - 修改已创建的店内支出记录
4. **删除店内支出** - 删除店内支出记录（逻辑删除）
5. **导入店内支出** - 通过Excel批量导入店内支出数据
6. **导出店内支出** - 导出店内支出数据为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`

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

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

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

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

#### 步骤5：导出合作成本

**接口：** `GET /api/Extend/LqCooperationCost/Actions/Export`

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

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

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

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

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

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

#### 步骤5：导出店内支出

**接口：** `GET /api/Extend/LqStoreExpense/Actions/Export`

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

**请求示例：**
```javascript
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 HH:mm:ss
- 金额必须为数字

## 📝 接口详细说明

### 合作成本接口

#### 1. 获取合作成本详情

**接口：** `GET /api/Extend/LqCooperationCost/{id}`

**路径参数：**
- `id`：合作成本记录ID（必填）

**响应示例：**
```json
{
  "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`

**请求体：**
```json
{
  "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（必填）

**响应示例：**
```json
{
  "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`

**请求体：**
```json
{
  "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（必填）

**说明：** 执行逻辑删除，不会真正删除数据

## ✅ 数据验证说明

### 合作成本验证规则

1. **门店ID验证**
   - 必填
   - 如果门店ID不存在，会报错

2. **年份验证**
   - 必填
   - 必须为整数，大于0

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

4. **合计金额验证**
   - 必填
   - 必须为数字，大于等于0

5. **唯一性验证**
   - 同一门店、同一年份、同一月份只能有一条有效记录
   - 如果已存在，创建时会报错

### 店内支出验证规则

1. **门店ID验证**
   - 必填
   - 如果门店ID不存在，会报错

2. **支出日期验证**
   - 必填
   - 格式：YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss

3. **金额验证**
   - 必填
   - 必须为数字，大于等于0

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

## ⚠️ 注意事项

### 合作成本注意事项

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

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

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

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

### 店内支出注意事项

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

2. **附件上传**
   - 附件使用FileControlsModel格式
   - 支持多个附件

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

4. **导入Excel格式**
   - 第一行必须是表头
   - 门店ID和门店名称至少填写一个
   - 支出日期格式：YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss

### 通用注意事项

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

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

3. **文件上传**
   - 导入接口需要使用`FormData`格式
   - 设置`Content-Type: 'multipart/form-data'`

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

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

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