jzg/修改出入口比例接口对接文档.md

修改出入口比例接口对接文档

1. 概述

• 功能：修改 ins_fee_orders 表中交强险、商业险、驾意险的入口比例和出口比例，并标记是否已手动修改。
• Base URL：{host}/supplementOrder

---

2. 修改出入口比例

2.1 接口信息

项目	说明
URL	/supplementOrder/updateFeeRatio
Method	POST
Content-Type	application/json

2.2 请求参数

{
  "orderNo": "OR2026072300001",
  "jqInletRatio": 10,
  "syInletRatio": 20,
  "jyInletRatio": 5,
  "jqExportRatio": 8,
  "syExportRatio": 15,
  "jyExportRatio": 3
}

字段	类型	必填	说明
orderNo	String	是	订单号
jqInletRatio	BigDecimal	否	交强险入口比例（0-100，服务端自动除以100，如传 10 表示 10%）
syInletRatio	BigDecimal	否	商业险入口比例（0-100）
jyInletRatio	BigDecimal	否	驾意险入口比例（0-100）
jqExportRatio	BigDecimal	否	交强险出口比例（0-100）
syExportRatio	BigDecimal	否	商业险出口比例（0-100）
jyExportRatio	BigDecimal	否	驾意险出口比例（0-100）

说明：6个比例字段均为可选，仅更新传入的非 null 值。前端传入 0-100 的百分比数值，服务端自动除以 100 后保存。

2.3 返回结果

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "orderNo": "OR2026072300001",
    "jqInletRatio": 0.10,
    "syInletRatio": 0.20,
    "jyInletRatio": 0.05,
    "jqExportRatio": 0.08,
    "syExportRatio": 0.15,
    "jyExportRatio": 0.03,
    "ratioModified": 1
  }
}

失败响应

{
  "code": 500,
  "message": "根据订单号查询订单费用表查无数据，订单号：OR2026072300001",
  "data": null
}

---

3. 获取订单详情（含比例修改标识）

3.1 接口信息

项目	说明
URL	/supplementOrder/getOrderDetail
Method	GET

3.2 请求参数

参数	类型	必填	说明
ordersNo	String	是	订单号
from	String	否	share=分享链接进入，其他=订单列表进入

3.3 响应新增字段

在 data.insFeeOrders 对象中新增字段：

字段	类型	说明
ratioModified	Integer	出入口比例是否已手动修改 0 - 未修改 1 - 已修改

示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order": { "...": "..." },
    "insFeeOrders": {
      "orderNo": "OR2026072300001",
      "jqPremium": "950.00",
      "syPremium": "3000.00",
      "jyPremium": "200.00",
      "jqInletRatio": 0.10,
      "syInletRatio": 0.20,
      "jyInletRatio": 0.05,
      "jqExportRatio": 0.08,
      "syExportRatio": 0.15,
      "jyExportRatio": 0.03,
      "ratioModified": 1,
      "...": "..."
    },
    "costRatio": { "...": "..." }
  }
}

---

4. 处理逻辑说明

1. 参数校验：校验 orderNo 是否为空，查询 ins_fee_orders 表中是否存在该订单。
2. 选择性更新：仅更新请求中传入的非 null 比例字段，未传入的字段保持原值不变。
3. 百分比转换：前端传入 0-100 的数值，服务端调用 covertPercent() 除以 100 后保存（如前端传 10，保存为 0.10）。
4. 关联比例联动（入口比例变化时）：
   • 若新的入口比例 小于 手续费比例，则手续费比例强制调整为入口比例，跟单比例置为 0
   • 若新的入口比例 大于等于 手续费比例，则跟单比例 = 入口比例 - 手续费比例
5. 留点比例重算：留点比例 = 入口比例/税费因子 + 加投比例 - (出口比例 + 分销比例)
6. 含分销出口比例重算：含分销出口比例 = 出口比例 + 分销比例
7. 费用重算：根据更新后的所有比例，调用 calculatePremiumByRule 重新计算每个险种的：
   • 入口应收金额、手续费金额、跟单金额、加投金额、留点金额、出口金额、出口留点金额
8. 汇总重算：重新计算总应收金额 totalReceivablePremium 和总应付金额 totalPayablePremium
9. 修改标识：更新成功后自动将 ratio_modified 字段置为 1（已修改）。
10. 返回数据：返回完整的 InsFeeOrders 对象（含重算后的所有费用）。

---

5. 数据库变更

ALTER TABLE ins_fee_orders ADD COLUMN ratio_modified TINYINT DEFAULT 0 COMMENT '出入口比例是否已手动修改 0-未修改 1-已修改';