合同管理系统-前端调用说明.md 25.7 KB

Edit Raw Blame History


合同管理系统 - 前端调用说明
📋 目录

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

🔄 业务流程概述
合同管理系统包含以下核心功能：


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

📡 接口列表


接口
方法
路径
说明


创建合同
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

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

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

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

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

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

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

请求示例：
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-12个月之间）
查询门店信息（获取店名）
创建合同记录
自动生成月租明细（根据合同起始日期、结束日期、交租周期、缴租金额）
计算下次应交时间（最早未缴费明细的应缴日期 - 提前提醒天数）

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}
失败：返回错误信息


业务逻辑：


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

3. 删除合同
接口地址： DELETE /api/Extend/LqContract/{id}

路径参数：


参数名
类型
必填
说明


id
string
✅
合同ID


响应说明：


成功：{"code": 200, "msg": "操作成功", "data": null}
失败：返回错误信息


业务逻辑：


验证合同是否存在
逻辑删除该合同的所有月租明细（设置 isEffective = 0）
逻辑删除合同（设置 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}
失败：返回错误信息


业务逻辑：


验证明细是否存在
验证明细是否已缴费（已缴费的不能重复标记）
更新明细的缴费信息
重新计算合同的下次应交时间

8. 统计门店合同费用
接口地址： POST /api/Extend/LqContract/GetExpenseStatistics

请求参数：


参数名
类型
必填
说明


storeId
string
✅
门店ID


year
int
✅
统计年份（2020-2100）


month
int
✅
统计月份（1-12）


categories
string[]
❌
分类列表（可选，不传则统计所有分类，如：["租门店", "员工宿舍", "车辆", "场所"]）


响应说明：


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


业务逻辑：


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


响应数据结构：


storeId: 门店ID
storeName: 门店名称
year: 统计年份
month: 统计月份
totalAmount: 总费用（所有分类的费用总和）
categoryDetails: 按分类统计的费用明细数组


category: 分类名称
amount: 该分类的费用总额
detailCount: 该分类的明细数量
details: 明细列表
detailId: 明细ID
contractId: 合同ID
contractTitle: 合同标题
category: 分类
dueAmount: 应缴金额
isPaid: 是否已缴（0-未缴，1-已缴）
actualPaymentAmount: 实际缴费金额（如果已缴费）


使用示例：
// 统计某个门店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: ['租门店', '员工宿舍', '车辆', '场所']
  }
});

🔍 数据验证说明
月租明细生成规则

生成时机：


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

生成规则：


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

示例：


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


生成的明细：


2025-01-01，应缴金额：3000元
2025-04-01，应缴金额：3000元
2025-07-01，应缴金额：3000元
2025-10-01，应缴金额：3000元

下次应交时间计算规则

计算时机：


创建合同时自动计算
更新合同时自动重新计算
标记明细已缴费后自动重新计算

计算规则：


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

示例：


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


⚠️ 注意事项

日期格式：


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

金额精度：


所有金额字段保留2位小数
前端显示时注意格式化

删除操作：


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

明细重新生成：


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

数据一致性：


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

错误处理：


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

权限控制：


所有接口都需要在请求头中携带 Authorization: Bearer {token}
Token 需要通过登录接口获取

分页查询：


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


8. 统计门店合同费用
接口： POST /api/Extend/LqContract/GetExpenseStatistics

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