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

## 1. 接口概述

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

## 2. 接口公共信息

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

### 2.2 统一响应格式
```json
{
  "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字符 |

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

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

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

#### 响应示例
```json
{
  "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": "季度分成"
    }
  ]
}
```