合同管理分成信息接口文档

1. 接口概述

本接口集用于管理合同管理分成信息（适配 contract_management_share 表），包含保存、修改、分页查询、单条查询（按ID/合同ID）等核心能力，满足合同管理分成数据的全生命周期操作。

2. 接口公共信息

2.1 基础信息

项	值
接口基础路径	`/app/contractManagementShare`
请求格式	JSON（POST请求）/ Query String（GET请求）
响应格式	JSON
服务部署地址	`http://fee-service`

2.2 统一响应格式

{
  "code": "响应码",
  "msg": "响应消息",
  "count": "影响行数（增删改接口）",
  "page": "当前页码（分页接口）",
  "row": "每页条数（分页接口）",
  "total": "总记录数（分页接口）",
  "data": "业务数据（查询接口）"
}

2.3 响应码说明

响应码	说明	备注
0	操作成功	正常业务响应
1	系统异常	系统内部错误
2	参数错误	必填参数缺失或格式错误
3	数据不存在	查询的记录不存在
4	数据已存在	重复数据冲突
5	业务逻辑错误	业务规则校验失败

3. 数据库表结构

contract_management_share 表结构
| 字段名 | 类型 | 长度 | 是否为空 | 默认值 | 说明 |
|--------|------|------|----------|--------|------|
| id | bigint | 20 | NO | AUTO_INCREMENT | 主键ID |
| contract_id | varchar | 50 | NO | | 合同ID（业务唯一标识） |
| management_ratio | decimal(10,4) | | YES | NULL | 管理费率（如0.05表示5%） |
| our_company_amount | decimal(18,2) | | YES | NULL | 我方金额（元） |
| our_committee_share | decimal(18,2) | | YES | NULL | 我方佣金分成（元） |
| our_company_receivable | decimal(18,2) | | YES | NULL | 我方应收金额（元） |
| create_time | datetime | | NO | CURRENT_TIMESTAMP | 创建时间 |
| update_time | datetime | | NO | CURRENT_TIMESTAMP | 更新时间 |
| create_user | varchar | 50 | YES | NULL | 创建人 |
| update_user | varchar | 50 | YES | NULL | 更新人 |
| remark | varchar | 500 | YES | NULL | 备注 |

4. 接口详情

4.1 保存合同管理分成信息

接口信息

接口地址：/saveContractManagementShare
请求方法：POST
功能描述：新增合同管理分成信息

请求参数

参数名	类型	必填	说明	验证规则
contractId	String	是	合同ID	长度1-50字符，不能为空
managementRatio	String/Number	否	管理费率	0-1之间的小数，如0.05
ourCompanyAmount	String/Number	否	我方金额	正数，保留两位小数
ourCommitteeShare	String/Number	否	我方佣金分成	正数，保留两位小数
ourCompanyReceivable	String/Number	否	我方应收金额	正数，保留两位小数
createUser	String	否	创建人	长度1-50字符
remark	String	否	备注	长度1-500字符

响应示例

成功响应：
json { "code": 0, "msg": "保存合同管理分成信息成功", "count": 1 }

错误响应：
json { "code": 2, "msg": "参数错误：contractId不能为空", "count": 0 }

4.2 修改合同管理分成信息

接口信息

接口地址：/updateContractManagementShare
请求方法：POST
功能描述：修改已存在的合同管理分成信息

请求参数

参数名	类型	必填	说明	验证规则
id	Long	是	主键ID	大于0的整数
contractId	String	是	合同ID	长度1-50字符
managementRatio	String/Number	否	管理费率	0-1之间的小数
ourCompanyAmount	String/Number	否	我方金额	正数，保留两位小数
ourCommitteeShare	String/Number	否	我方佣金分成	正数，保留两位小数
ourCompanyReceivable	String/Number	否	我方应收金额	正数，保留两位小数
updateUser	String	否	更新人	长度1-50字符
remark	String	否	备注	长度1-500字符

响应示例

{
  "code": 0,
  "msg": "修改合同管理分成信息成功",
  "count": 1
}

4.3 分页查询合同管理分成信息列表

接口信息

接口地址：/queryContractManagementShare
请求方法：GET
功能描述：多条件分页查询合同管理分成信息列表

请求参数

参数名	类型	必填	说明	查询方式
id	Long	否	主键ID	精确匹配
contractId	String	否	合同ID	精确匹配
managementRatio	String	否	管理费率	范围查询
ourCompanyAmount	String	否	我方金额	范围查询
ourCommitteeShare	String	否	我方佣金分成	范围查询
ourCompanyReceivable	String	否	我方应收金额	范围查询
createUser	String	否	创建人	模糊查询
startCreateTime	String	否	开始时间	yyyy-MM-dd HH:mm:ss
endCreateTime	String	否	结束时间	yyyy-MM-dd HH:mm:ss
page	Integer	否	页码	默认1，从1开始
row	Integer	否	每页条数	默认10，最大100

响应示例

{
  "code": 0,
  "msg": "查询合同管理分成信息成功",
  "page": 1,
  "row": 10,
  "total": 1,
  "data": [
    {
      "id": 1001,
      "contractId": "CON20251224001",
      "managementRatio": "0.06",
      "ourCompanyAmount": "12000.00",
      "ourCommitteeShare": "720.00",
      "ourCompanyReceivable": "11280.00",
      "createTime": "2025-01-12 10:30:00",
      "updateTime": "2025-01-12 11:30:00",
      "createUser": "张三",
      "updateUser": "李四",
      "remark": "季度分成"
    }
  ]
}

4.4 根据ID查询单条合同管理分成信息

接口信息

接口地址：/getContractManagementShareById
请求方法：GET
功能描述：根据主键ID查询单条合同管理分成信息

请求参数

参数名	类型	必填	说明
id	Long	是	主键ID

响应示例

{
  "code": 0,
  "msg": "查询合同管理分成信息成功",
  "data": {
    "id": 1001,
    "contractId": "CON20251224001",
    "managementRatio": "0.06",
    "ourCompanyAmount": "12000.00",
    "ourCommitteeShare": "720.00",
    "ourCompanyReceivable": "11280.00",
    "createTime": "2025-01-12 10:30:00",
    "updateTime": "2025-01-12 11:30:00",
    "createUser": "张三",
    "updateUser": "李四",
    "remark": "季度分成"
  }
}

4.5 根据合同ID查询合同管理分成信息

接口信息

接口地址：/getContractManagementShareByContractId
请求方法：GET
功能描述：根据合同ID查询关联的所有分成信息

请求参数

参数名	类型	必填	说明
contractId	String	是	合同ID

响应示例

{
  "code": 0,
  "msg": "查询合同管理分成信息成功",
  "data": [
    {
      "id": 1001,
      "contractId": "CON20251224001",
      "managementRatio": "0.06",
      "ourCompanyAmount": "12000.00",
      "ourCommitteeShare": "720.00",
      "ourCompanyReceivable": "11280.00",
      "createTime": "2025-01-12 10:30:00",
      "updateTime": "2025-01-12 11:30:00",
      "createUser": "张三",
      "updateUser": "李四",
      "remark": "季度分成"
    }
  ]
}