# 合同管理系统 - 前端调用说明

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

## 🔄 业务流程概述

合同管理系统包含以下核心功能：

1. **创建合同** - 录入合同信息，系统自动生成月租明细
2. **查询合同** - 支持列表查询和详情查询
3. **更新合同** - 修改合同信息，如果影响明细会自动重新生成
4. **标记缴费** - 标记月租明细已缴费，系统自动更新下次应交时间
5. **删除合同** - 删除合同及所有关联明细（逻辑删除）

## 📡 接口列表

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建合同 | POST | `/api/Extend/LqContract/Create` | 创建合同并自动生成月租明细 |
| 更新合同 | PUT | `/api/Extend/LqContract/Update` | 更新合同信息，影响明细时自动重新生成 |
| 删除合同 | DELETE | `/api/Extend/LqContract/{id}` | 删除合同及所有明细（逻辑删除） |
| 获取合同列表 | GET | `/api/Extend/LqContract/GetList` | 分页查询合同列表，支持多条件筛选 |
| 获取合同详情 | GET | `/api/Extend/LqContract/GetInfo` | 根据合同ID获取详情，包含月租明细列表 |
| 获取月租明细列表 | GET | `/api/Extend/LqContract/GetRentDetails` | 根据合同ID获取所有月租明细 |
| 标记明细已缴费 | PUT | `/api/Extend/LqContract/MarkRentDetailPaid` | 标记某条明细已缴费，记录实际缴费信息 |
| 统计门店合同费用 | POST | `/api/Extend/LqContract/GetExpenseStatistics` | 统计某个门店指定月份的合同费用，支持按分类统计 |

## 🚀 完整流程示例

### 步骤1：创建合同

**接口：** `POST /api/Extend/LqContract/Create`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/Create',
  method: 'POST',
  data: {
    storeId: '1649328471923847168',  // 门店ID（必填）
    title: '门店租赁合同',  // 标题（必填）
    category: '租赁合同',  // 分类（可选）
    tenantName: '张三',  // 户名（可选）
    contractStartDate: '2025-01-01T00:00:00',  // 合同起始日期（必填）
    contractEndDate: '2025-12-31T23:59:59',  // 合同结束日期（必填）
    reminderDays: 7,  // 提前提醒天数（可选，默认0）
    deposit: 5000.00,  // 押金（可选，默认0）
    monthlyRent: 1000.00,  // 月租（必填）
    paymentAmount: 3000.00,  // 缴租金额（必填，通常=月租×交租周期）
    paymentCycle: 3,  // 交租周期（必填，单位：月，如1、3、6等）
    remarks: '季度交租',  // 备注（可选）
    attachment: ''  // 附件（可选）
  }
});

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

**说明：**
- 系统会自动根据合同信息生成月租明细
- 生成规则：从合同起始日期开始，每隔 `paymentCycle` 个月生成一条明细
- 应缴月份为每次交租对应的月份（格式：YYYY-MM-01）
- 应缴日期为应缴月份的第一天
- 应缴金额等于 `paymentAmount`
- 系统会自动计算下次应交时间（最早未缴费明细的应缴日期 - 提前提醒天数）

**示例：**
- 合同起始：2025-01-01
- 合同结束：2025-12-31
- 交租周期：3个月
- 缴租金额：3000元

生成的明细：
- 2025-01-01，应缴金额：3000元（1-3月）
- 2025-04-01，应缴金额：3000元（4-6月）
- 2025-07-01，应缴金额：3000元（7-9月）
- 2025-10-01，应缴金额：3000元（10-12月）

### 步骤2：查询合同列表

**接口：** `GET /api/Extend/LqContract/GetList`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/GetList',
  method: 'GET',
  params: {
    currentPage: 1,  // 当前页码（必填）
    pageSize: 10,  // 每页数量（必填）
    sidx: 'createTime',  // 排序字段（可选，默认createTime）
    sort: 'desc',  // 排序方式（可选，默认desc）
    storeId: '1649328471923847168',  // 门店ID（可选）
    storeName: '绿纤总部',  // 门店名称（可选，模糊查询）
    category: '租赁合同',  // 分类（可选）
    title: '合同',  // 标题（可选，模糊查询）
    contractStartDateBegin: '2025-01-01',  // 合同起始日期（开始）（可选）
    contractStartDateEnd: '2025-12-31',  // 合同起始日期（结束）（可选）
    contractEndDateBegin: '2025-01-01',  // 合同结束日期（开始）（可选）
    contractEndDateEnd: '2025-12-31',  // 合同结束日期（结束）（可选）
    isEffective: 1  // 是否有效（可选，1-有效，0-无效）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "pagination": {
//       "pageIndex": 1,
//       "pageSize": 10,
//       "total": 1
//     },
//     "list": [
//       {
//         "id": "768081482374710533",
//         "storeId": "1649328471923847168",
//         "storeName": "绿纤总部",
//         "title": "门店租赁合同",
//         "category": "租赁合同",
//         "tenantName": "张三",
//         "contractStartDate": 1735660800000,
//         "contractEndDate": 1767196799000,
//         "reminderDays": 7,
//         "deposit": 5000.00,
//         "nextPaymentDate": 1735056000000,
//         "monthlyRent": 1000.00,
//         "paymentAmount": 3000.00,
//         "paymentCycle": 3,
//         "remarks": "季度交租",
//         "attachment": "",
//         "createUser": "admin",
//         "createUserName": "管理员",
//         "createTime": 1765290098000,
//         "updateUser": "admin",
//         "updateUserName": "管理员",
//         "updateTime": 1765290098000,
//         "isEffective": 1
//       }
//     ]
//   }
// }
```

### 步骤3：查询合同详情

**接口：** `GET /api/Extend/LqContract/GetInfo`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/GetInfo',
  method: 'GET',
  params: {
    id: '768081482374710533'  // 合同ID（必填）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "id": "768081482374710533",
//     "storeId": "1649328471923847168",
//     "storeName": "绿纤总部",
//     "title": "门店租赁合同",
//     "category": "租赁合同",
//     "tenantName": "张三",
//     "contractStartDate": 1735660800000,
//     "contractEndDate": 1767196799000,
//     "reminderDays": 7,
//     "deposit": 5000.00,
//     "nextPaymentDate": 1735056000000,
//     "monthlyRent": 1000.00,
//     "paymentAmount": 3000.00,
//     "paymentCycle": 3,
//     "remarks": "季度交租",
//     "attachment": "",
//     "createUser": "admin",
//     "createUserName": "管理员",
//     "createTime": 1765290098000,
//     "updateUser": "admin",
//     "updateUserName": "管理员",
//     "updateTime": 1765290098000,
//     "isEffective": 1,
//     "rentDetails": [
//       {
//         "id": "768081482571842821",
//         "contractId": "768081482374710533",
//         "paymentMonth": 1735660800000,
//         "dueDate": 1735660800000,
//         "dueAmount": 3000.00,
//         "isPaid": 0,
//         "actualPaymentDate": null,
//         "actualPaymentAmount": null,
//         "remarks": null,
//         "createUser": "admin",
//         "createUserName": "管理员",
//         "createTime": 1765290098000,
//         "updateUser": null,
//         "updateUserName": "",
//         "updateTime": null,
//         "isEffective": 1
//       }
//       // ... 更多明细
//     ]
//   }
// }
```

### 步骤4：查询月租明细列表

**接口：** `GET /api/Extend/LqContract/GetRentDetails`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/GetRentDetails',
  method: 'GET',
  params: {
    contractId: '768081482374710533'  // 合同ID（必填）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": [
//     {
//       "id": "768081482571842821",
//       "contractId": "768081482374710533",
//       "paymentMonth": 1735660800000,
//       "dueDate": 1735660800000,
//       "dueAmount": 3000.00,
//       "isPaid": 0,
//       "actualPaymentDate": null,
//       "actualPaymentAmount": null,
//       "remarks": null,
//       "createUser": "admin",
//       "createUserName": "管理员",
//       "createTime": 1765290098000,
//       "updateUser": null,
//       "updateUserName": "",
//       "updateTime": null,
//       "isEffective": 1
//     }
//     // ... 更多明细
//   ]
// }
```

### 步骤5：标记明细已缴费

**接口：** `PUT /api/Extend/LqContract/MarkRentDetailPaid`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/MarkRentDetailPaid',
  method: 'PUT',
  data: {
    id: '768081482571842821',  // 明细ID（必填）
    actualPaymentDate: '2025-01-15T00:00:00',  // 实际缴费时间（必填）
    actualPaymentAmount: 3000.00,  // 实际缴费金额（必填）
    remarks: '已缴费'  // 备注（可选）
  }
});

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

**说明：**
- 标记成功后，系统会自动更新该明细的 `isPaid` 为 1
- 系统会自动重新计算合同的下次应交时间（找到最早未缴费明细，计算：应缴日期 - 提前提醒天数）

### 步骤6：更新合同

**接口：** `PUT /api/Extend/LqContract/Update`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/Update',
  method: 'PUT',
  data: {
    id: '768081482374710533',  // 合同ID（必填）
    storeId: '1649328471923847168',  // 门店ID（必填）
    title: '门店租赁合同-已更新',  // 标题（必填）
    category: '租赁合同',  // 分类（可选）
    tenantName: '张三',  // 户名（可选）
    contractStartDate: '2025-01-01T00:00:00',  // 合同起始日期（必填）
    contractEndDate: '2025-12-31T23:59:59',  // 合同结束日期（必填）
    reminderDays: 7,  // 提前提醒天数（可选）
    deposit: 5000.00,  // 押金（可选）
    monthlyRent: 1000.00,  // 月租（必填）
    paymentAmount: 6000.00,  // 缴租金额（必填）
    paymentCycle: 6,  // 交租周期（必填）
    remarks: '半年交租',  // 备注（可选）
    attachment: ''  // 附件（可选）
  }
});

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

**说明：**
- 如果修改了以下字段，系统会重新生成月租明细：
  - `contractStartDate`（合同起始日期）
  - `contractEndDate`（合同结束日期）
  - `paymentCycle`（交租周期）
  - `paymentAmount`（缴租金额）
- 重新生成时，会先逻辑删除所有旧明细，然后生成新明细
- 系统会自动重新计算下次应交时间

### 步骤7：删除合同

**接口：** `DELETE /api/Extend/LqContract/{id}`

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

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

**说明：**
- 删除合同会同时逻辑删除该合同的所有月租明细
- 删除后，合同和明细的 `isEffective` 字段会被设置为 0
- 删除后的合同在列表查询中不会显示（默认只查询有效的合同）

## 📝 接口详细说明

### 1. 创建合同

**接口地址：** `POST /api/Extend/LqContract/Create`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| storeId | string | ✅ | 门店ID（关联lq_mdxx.F_Id） |
| title | string | ✅ | 标题 |
| category | string | ❌ | 分类（string类型，自己填写） |
| tenantName | string | ❌ | 户名 |
| contractStartDate | datetime | ✅ | 合同起始日期 |
| contractEndDate | datetime | ✅ | 合同结束日期 |
| reminderDays | int | ❌ | 提前多少天提醒（默认0） |
| deposit | decimal | ❌ | 押金（默认0） |
| monthlyRent | decimal | ✅ | 月租 |
| paymentAmount | decimal | ✅ | 缴租金额（每次交租的金额，通常=月租×交租周期） |
| paymentCycle | int | ✅ | 交租周期（数字，表示几个月，如1、3、6等，范围1-12） |
| remarks | string | ❌ | 备注 |
| attachment | string | ❌ | 附件（存储附件路径或JSON） |

**响应说明：**
- 成功：`{"code": 200, "msg": "操作成功", "data": null}`
- 失败：返回错误信息

**业务逻辑：**
1. 验证合同日期（起始日期必须小于结束日期）
2. 验证交租周期（必须在1-12个月之间）
3. 查询门店信息（获取店名）
4. 创建合同记录
5. 自动生成月租明细（根据合同起始日期、结束日期、交租周期、缴租金额）
6. 计算下次应交时间（最早未缴费明细的应缴日期 - 提前提醒天数）

### 2. 更新合同

**接口地址：** `PUT /api/Extend/LqContract/Update`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | ✅ | 合同ID |
| storeId | string | ✅ | 门店ID |
| title | string | ✅ | 标题 |
| category | string | ❌ | 分类 |
| tenantName | string | ❌ | 户名 |
| contractStartDate | datetime | ✅ | 合同起始日期 |
| contractEndDate | datetime | ✅ | 合同结束日期 |
| reminderDays | int | ❌ | 提前提醒天数 |
| deposit | decimal | ❌ | 押金 |
| monthlyRent | decimal | ✅ | 月租 |
| paymentAmount | decimal | ✅ | 缴租金额 |
| paymentCycle | int | ✅ | 交租周期 |
| remarks | string | ❌ | 备注 |
| attachment | string | ❌ | 附件 |

**响应说明：**
- 成功：`{"code": 200, "msg": "操作成功", "data": null}`
- 失败：返回错误信息

**业务逻辑：**
1. 验证合同是否存在
2. 验证合同日期和交租周期
3. 判断是否需要重新生成明细（如果修改了合同起始日期、结束日期、交租周期或缴租金额）
4. 如果需要重新生成，先逻辑删除旧明细，再生成新明细
5. 重新计算下次应交时间

### 3. 删除合同

**接口地址：** `DELETE /api/Extend/LqContract/{id}`

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | ✅ | 合同ID |

**响应说明：**
- 成功：`{"code": 200, "msg": "操作成功", "data": null}`
- 失败：返回错误信息

**业务逻辑：**
1. 验证合同是否存在
2. 逻辑删除该合同的所有月租明细（设置 `isEffective = 0`）
3. 逻辑删除合同（设置 `isEffective = 0`）

### 4. 获取合同列表

**接口地址：** `GET /api/Extend/LqContract/GetList`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| currentPage | int | ✅ | 当前页码 |
| pageSize | int | ✅ | 每页数量 |
| sidx | string | ❌ | 排序字段（默认createTime） |
| sort | string | ❌ | 排序方式（默认desc） |
| storeId | string | ❌ | 门店ID |
| storeName | string | ❌ | 门店名称（模糊查询） |
| category | string | ❌ | 分类 |
| title | string | ❌ | 标题（模糊查询） |
| contractStartDateBegin | datetime | ❌ | 合同起始日期（开始） |
| contractStartDateEnd | datetime | ❌ | 合同起始日期（结束） |
| contractEndDateBegin | datetime | ❌ | 合同结束日期（开始） |
| contractEndDateEnd | datetime | ❌ | 合同结束日期（结束） |
| isEffective | int | ❌ | 是否有效（1-有效，0-无效） |

**响应说明：**
- 成功：返回分页数据，包含合同列表和分页信息
- 失败：返回错误信息

### 5. 获取合同详情

**接口地址：** `GET /api/Extend/LqContract/GetInfo`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | ✅ | 合同ID |

**响应说明：**
- 成功：返回合同详情，包含月租明细列表
- 失败：返回错误信息

### 6. 获取月租明细列表

**接口地址：** `GET /api/Extend/LqContract/GetRentDetails`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| contractId | string | ✅ | 合同ID |

**响应说明：**
- 成功：返回月租明细数组
- 失败：返回错误信息

### 7. 标记明细已缴费

**接口地址：** `PUT /api/Extend/LqContract/MarkRentDetailPaid`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | ✅ | 明细ID |
| actualPaymentDate | datetime | ✅ | 实际缴费时间 |
| actualPaymentAmount | decimal | ✅ | 实际缴费金额 |
| remarks | string | ❌ | 备注 |

**响应说明：**
- 成功：`{"code": 200, "msg": "操作成功", "data": null}`
- 失败：返回错误信息

**业务逻辑：**
1. 验证明细是否存在
2. 验证明细是否已缴费（已缴费的不能重复标记）
3. 更新明细的缴费信息
4. 重新计算合同的下次应交时间

### 8. 统计门店合同费用

**接口地址：** `POST /api/Extend/LqContract/GetExpenseStatistics`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| storeId | string | ✅ | 门店ID |
| year | int | ✅ | 统计年份（2020-2100） |
| month | int | ✅ | 统计月份（1-12） |
| categories | string[] | ❌ | 分类列表（可选，不传则统计所有分类，如：["租门店", "员工宿舍", "车辆", "场所"]） |

**响应说明：**
- 成功：返回统计结果，包含总费用和按分类的费用明细
- 失败：返回错误信息

**业务逻辑：**
1. 验证月份范围（1-12）
2. 查询门店信息
3. 查询该门店在指定月份的月租明细（关联合同表获取分类信息）
4. 如果指定了分类，则只统计指定分类的明细
5. 按分类分组统计，计算每个分类的费用总额
6. 返回总费用和按分类的费用明细

**响应数据结构：**
- `storeId`: 门店ID
- `storeName`: 门店名称
- `year`: 统计年份
- `month`: 统计月份
- `totalAmount`: 总费用（所有分类的费用总和）
- `categoryDetails`: 按分类统计的费用明细数组
  - `category`: 分类名称
  - `amount`: 该分类的费用总额
  - `detailCount`: 该分类的明细数量
  - `details`: 明细列表
    - `detailId`: 明细ID
    - `contractId`: 合同ID
    - `contractTitle`: 合同标题
    - `category`: 分类
    - `dueAmount`: 应缴金额
    - `isPaid`: 是否已缴（0-未缴，1-已缴）
    - `actualPaymentAmount`: 实际缴费金额（如果已缴费）

**使用示例：**
```javascript
// 统计某个门店2025年1月的所有合同费用
const response = await request({
  url: '/api/Extend/LqContract/GetExpenseStatistics',
  method: 'POST',
  data: {
    storeId: '1649328471923847168',
    year: 2025,
    month: 1
  }
});

// 只统计特定分类的费用（租门店、员工宿舍、车辆、场所）
const response2 = await request({
  url: '/api/Extend/LqContract/GetExpenseStatistics',
  method: 'POST',
  data: {
    storeId: '1649328471923847168',
    year: 2025,
    month: 1,
    categories: ['租门店', '员工宿舍', '车辆', '场所']
  }
});
```

## 🔍 数据验证说明

### 月租明细生成规则

1. **生成时机：**
   - 创建合同时自动生成
   - 更新合同时，如果修改了影响明细的字段，会重新生成

2. **生成规则：**
   - 从合同起始日期开始，每隔 `paymentCycle` 个月生成一条明细
   - 应缴月份：每次交租对应的月份（格式：YYYY-MM-01）
   - 应缴日期：应缴月份的第一天
   - 应缴金额：等于 `paymentAmount`
   - 生成到合同结束日期为止

3. **示例：**
   - 合同起始：2025-01-01
   - 合同结束：2025-12-31
   - 交租周期：3个月
   - 缴租金额：3000元
   
   生成的明细：
   - 2025-01-01，应缴金额：3000元
   - 2025-04-01，应缴金额：3000元
   - 2025-07-01，应缴金额：3000元
   - 2025-10-01，应缴金额：3000元

### 下次应交时间计算规则

1. **计算时机：**
   - 创建合同时自动计算
   - 更新合同时自动重新计算
   - 标记明细已缴费后自动重新计算

2. **计算规则：**
   - 查找该合同未缴费的明细中，应缴日期最早的一条
   - 下次应交时间 = 最早应缴日期 - 提前提醒天数（`reminderDays`）
   - 如果没有未缴费的明细，下次应交时间为 `null`

3. **示例：**
   - 最早未缴费明细的应缴日期：2025-01-01
   - 提前提醒天数：7天
   - 下次应交时间：2024-12-25（2025-01-01 - 7天）

## ⚠️ 注意事项

1. **日期格式：**
   - 所有日期字段使用 ISO 8601 格式：`YYYY-MM-DDTHH:mm:ss`
   - 时间戳字段返回的是毫秒级时间戳（需要除以1000转换为秒）

2. **金额精度：**
   - 所有金额字段保留2位小数
   - 前端显示时注意格式化

3. **删除操作：**
   - 删除是逻辑删除，不会物理删除数据
   - 删除后的合同在列表查询中默认不显示（`isEffective = 0`）
   - 如果需要查询已删除的合同，可以设置 `isEffective = 0`

4. **明细重新生成：**
   - 更新合同时，如果修改了合同起始日期、结束日期、交租周期或缴租金额，会重新生成明细
   - 重新生成时，旧明细会被逻辑删除，新明细会重新生成
   - 如果旧明细中有已缴费的记录，重新生成后这些记录也会被删除

5. **数据一致性：**
   - 系统会自动维护合同和明细的一致性
   - 删除合同时会自动删除所有明细
   - 更新合同时会自动处理明细的重新生成

6. **错误处理：**
   - 所有接口都会返回标准的响应格式：`{"code": 200, "msg": "操作成功", "data": ...}`
   - 如果发生错误，`code` 不为 200，`msg` 包含错误信息
   - 前端需要根据 `code` 判断操作是否成功

7. **权限控制：**
   - 所有接口都需要在请求头中携带 `Authorization: Bearer {token}`
   - Token 需要通过登录接口获取

8. **分页查询：**
   - 列表查询接口支持分页
   - 默认按创建时间倒序排列
   - 可以通过 `sidx` 和 `sort` 参数自定义排序

### 8. 统计门店合同费用

**接口：** `POST /api/Extend/LqContract/GetExpenseStatistics`

**请求示例：**
```javascript
const response = await request({
  url: '/api/Extend/LqContract/GetExpenseStatistics',
  method: 'POST',
  data: {
    storeId: '1649328471923847168',  // 门店ID（必填）
    year: 2025,  // 统计年份（必填）
    month: 1,  // 统计月份（必填，1-12）
    categories: ['租门店', '员工宿舍', '车辆', '场所']  // 分类列表（可选，不传则统计所有分类）
  }
});

// 响应示例
// {
//   "code": 200,
//   "msg": "操作成功",
//   "data": {
//     "storeId": "1649328471923847168",
//     "storeName": "绿纤总部",
//     "year": 2025,
//     "month": 1,
//     "totalAmount": 6000.00,
//     "categoryDetails": [
//       {
//         "category": "租赁合同",
//         "amount": 6000.00,
//         "detailCount": 2,
//         "details": [
//           {
//             "detailId": "768081482571842821",
//             "contractId": "768081482374710533",
//             "contractTitle": "门店租赁合同",
//             "category": "租赁合同",
//             "dueAmount": 3000.00,
//             "isPaid": 0,
//             "actualPaymentAmount": null
//           }
//         ]
//       }
//     ]
//   }
// }
```

**说明：**
- 统计该门店在指定月份的合同费用
- 支持按分类筛选（如：租门店、员工宿舍、车辆、场所等）
- 返回总费用和按分类的费用明细
- 每个分类包含该分类的费用总额、明细数量和明细列表

**使用场景：**
- 统计某个门店这个月的房租开销
- 按分类查看不同类型的合同费用
- 生成门店成本费用报表

## 📊 数据字段说明

### 合同字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 合同ID |
| storeId | string | 门店ID |
| storeName | string | 店名（冗余字段） |
| title | string | 标题 |
| category | string | 分类 |
| tenantName | string | 户名 |
| contractStartDate | long | 合同起始日期（时间戳，毫秒） |
| contractEndDate | long | 合同结束日期（时间戳，毫秒） |
| reminderDays | int | 提前提醒天数 |
| deposit | decimal | 押金 |
| nextPaymentDate | long | 下次应交时间（时间戳，毫秒，可能为null） |
| monthlyRent | decimal | 月租 |
| paymentAmount | decimal | 缴租金额 |
| paymentCycle | int | 交租周期（月） |
| remarks | string | 备注 |
| attachment | string | 附件 |
| createUser | string | 创建人ID |
| createUserName | string | 创建人姓名 |
| createTime | long | 创建时间（时间戳，毫秒） |
| updateUser | string | 更新人ID |
| updateUserName | string | 更新人姓名 |
| updateTime | long | 更新时间（时间戳，毫秒，可能为null） |
| isEffective | int | 是否有效（1-有效，0-无效） |

### 月租明细字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 明细ID |
| contractId | string | 合同ID |
| paymentMonth | long | 应缴月份（时间戳，毫秒） |
| dueDate | long | 应缴日期（时间戳，毫秒） |
| dueAmount | decimal | 应缴金额 |
| isPaid | int | 是否已缴（0-未缴，1-已缴） |
| actualPaymentDate | long | 实际缴费时间（时间戳，毫秒，可能为null） |
| actualPaymentAmount | decimal | 实际缴费金额（可能为null） |
| remarks | string | 备注 |
| createUser | string | 创建人ID |
| createUserName | string | 创建人姓名 |
| createTime | long | 创建时间（时间戳，毫秒） |
| updateUser | string | 更新人ID |
| updateUserName | string | 更新人姓名 |
| updateTime | long | 更新时间（时间戳，毫秒，可能为null） |
| isEffective | int | 是否有效（1-有效，0-无效） |