# 投标保证金迁移到销售管理 - 前端联调方案 ## 变更概述 投标保证金原先挂在「供应商管理(SRM)」下,按供应商/询价单/采购订单登记,业务上并不成立:投标保证金是我方向**客户(招标方)**缴纳的款项,中标后与销售订单/销售台账挂钩,未中标才跟踪退款。本次迁移: | 项目 | 变更前 | 变更后 | |------|--------|--------| | 所属模块 | 供应商管理 SRM | 销售管理 CRM | | 菜单 | 采购管理(2602)→ 投标保证金 | 销售管理(2617)→ 投标保证金 | | 数据表 | srm_bid_bond | crm_bid_bond | | 业务对象 | 供应商 / 询价单 / 采购订单 | 客户(招标方)/ 销售订单(销售台账) | | 中标标记 | won 布尔值 | bid_result 枚举(待开标/已中标/未中标) | | 权限串 | srm:bid-bond:* | crm:bid-bond:* | 前端页面路径:`crm/bidBond/index`,组件名 `CrmBidBond`,菜单 id 沿用 602630(按钮 602631~602634),历史角色授权不丢失,仅权限串变化——需要给已授权角色补充 `crm:bid-bond:*` 按钮权限。 ## 涉及页面 - 销售管理 → 投标保证金(新页面,列表 + 新增/编辑弹窗) - 原供应商管理 → 投标保证金(删除) ## 业务流程与数据带入 1. 录入保证金时先选**客户(招标方)**;客户决定可选的销售订单范围。 2. 选择销售订单后,只能看到该客户名下、状态为**已审核(status=20)**的销售订单(即销售台账口径),并自动带出订单号与订单金额。 3. 选中销售订单视同已中标:后端自动把「待开标」改为「已中标」,并把「退回状态」默认为「无需退回」。 4. 未中标:退回状态默认「未退回」,之后按实际退款进度更新为「部分退回」/「已退回」,并填写退回金额与日期。 5. 换客户时必须清空已选销售订单(订单归属变了),前端需要在客户变化时重置销售订单字段。 ## API | 方法 | 路径 | 权限 | 说明 | |------|------|------|------| | GET | /crm/bid-bond/page | crm:bid-bond:query | 分页查询 | | GET | /crm/bid-bond/get | crm:bid-bond:query | 查询详情 | | POST | /crm/bid-bond/create | crm:bid-bond:create | 新增 | | PUT | /crm/bid-bond/update | crm:bid-bond:update | 修改 | | DELETE | /crm/bid-bond/delete | crm:bid-bond:delete | 删除 | | GET | /crm/bid-bond/sale-order-list | crm:bid-bond:query | 查询该客户可关联的销售订单(仅已审核) | **分页查询参数:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | pageNo | Integer | 是 | 页码 | | pageSize | Integer | 是 | 每页条数 | | no | String | 否 | 保证金单号,模糊 | | customerId | Long | 否 | 客户 ID | | projectName | String | 否 | 项目名称,模糊 | | tenderNo | String | 否 | 招标编号,模糊 | | saleOrderNo | String | 否 | 关联销售订单号快照,模糊 | | bidResult | Integer | 否 | 中标结果:0 待开标、1 已中标、2 未中标 | | refundStatus | Integer | 否 | 退回状态:0 未退回、1 部分退回、2 已退回、3 无需退回 | | payDateStart / payDateEnd | Date | 否 | 缴纳日期区间(yyyy-MM-dd) | **新增/修改请求参数:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | id | Long | 修改必填 | 主键,新增不传 | | customerId | Long | 是 | 客户(招标方)ID | | projectName | String | 否 | 项目名称 | | tenderNo | String | 否 | 招标编号 | | saleOrderId | Long | 否 | 关联销售订单 ID(须为已审核且同客户) | | bondAmount | BigDecimal | 是 | 保证金金额,必须大于 0 | | payDate | Date | 否 | 缴纳日期 | | bidResult | Integer | 是 | 中标结果枚举 | | refundStatus | Integer | 否 | 不传时按中标结果默认:未中标/待开标=未退回,已中标=无需退回 | | refundAmount | BigDecimal | 否 | 退回金额 | | refundDate | Date | 否 | 退回日期 | | remark | String | 否 | 备注 | **响应字段(列表/详情):** | 字段 | 类型 | 说明 | |------|------|------| | id | Long | 主键 | | no | String | 保证金单号,后端生成 `BZyyyyMM + 4位随机数`,唯一,创建后不可修改 | | customerId / customerName | Long / String | 客户(招标方) | | projectName | String | 项目名称 | | tenderNo | String | 招标编号 | | saleOrderId | Long | 关联销售订单 ID | | saleOrderNo | String | 关联销售订单号(由销售订单实时回填,兼作快照) | | saleOrderAmount | BigDecimal | 关联销售订单金额(销售订单 totalPrice) | | bondAmount | BigDecimal | 保证金金额 | | payDate | Date | 缴纳日期 | | bidResult | Integer | 中标结果 | | refundStatus | Integer | 退回状态 | | refundAmount | BigDecimal | 退回金额 | | refundDate | Date | 退回日期 | | remark | String | 备注 | | createTime | DateTime | 创建时间 | **销售订单下拉响应字段(GET /crm/bid-bond/sale-order-list?customerId=):** | 字段 | 类型 | 说明 | |------|------|------| | id | Long | 销售订单 ID | | no | String | 销售订单号 | | customerId | Long | 客户 ID | | status | Integer | 订单状态(接口只返回 20 已审核) | | statusName | String | 状态名称 | | totalPrice | BigDecimal | 订单金额 | | contractNo | String | 合同号 | ## 字段展示规则 | 字段 | 展示位置 | 说明 | |------|----------|------| | 保证金单号 | 列表、详情 | BZ 开头 | | 客户(招标方) | 列表、详情、筛选 | 名称展示,提交 ID | | 项目名称 / 招标编号 | 列表、详情、筛选 | 项目名称与招标编号都支持模糊搜索 | | 关联销售订单 | 列表、详情、筛选 | 未关联显示「未关联」;筛选按订单号模糊 | | 订单金额 | 列表 | 关联后展示,未关联为空 | | 保证金金额 | 列表、详情 | 两位小数 | | 缴纳日期 | 列表、详情 | yyyy-MM-dd | | 中标结果 | 列表、详情、筛选 | 标签:待开标(蓝)/已中标(绿)/未中标(灰) | | 退回状态 | 列表、详情、筛选 | 标签:未退回(橙)/部分退回(蓝)/已退回(绿)/无需退回(灰) | | 退回金额 / 退回日期 | 列表、详情 | 仅在部分退回/已退回时有值 | | 备注 | 列表、详情 | | ## 业务规则说明 | 场景 | 规则 | |------|------| | 客户校验 | 客户必须存在,否则提示客户 ID 不存在,需刷新客户列表 | | 保证金金额 | 必须大于 0 | | 关联销售订单 | 必须存在、状态必须为「已审核(20)」、且订单客户与保证金客户一致 | | 未中标 + 关联订单 | 不允许,提示改为已中标或清空关联订单 | | 待开标 + 关联订单 | 后端自动改为已中标 | | 已中标 | 退回状态默认「无需退回」,不记录退款金额/日期 | | 未中标 | 退回状态默认「未退回」 | | 已退回 | 退回金额必须等于保证金金额,且退回日期必填 | | 部分退回 | 退回金额必须大于 0 且小于保证金金额,且退回日期必填 | | 未退回 / 无需退回 | 不允许填写退回金额(携带会被拒绝),前端提交前应清空 | | 单号 | 创建时后端生成,修改时不允许变更 | ## 数据迁移说明 - 新表 `crm_bid_bond`,迁移脚本:`sql/mysql/20261105_crm_bid_bond.sql`(已同步追加到 `docs/sql/config_export_all_20261104.sql`),幂等可重复执行。 - 旧表 `srm_bid_bond` 保留未删除,历史数据**不会自动迁移**:原记录按供应商登记,缺少客户(招标方)与销售订单,无法可靠映射。如需保留历史,请业务侧先确定供应商与客户的对应关系后再人工补录;确认无用后可另建清理脚本归档后删除。 - 旧菜单 602630~602634 已改用 `crm:bid-bond:*` 权限串,需要在「角色管理」里为销售相关角色勾选按钮权限;超级管理员无需配置。 ## 注意事项 - 销售订单下拉依赖 ERP 销售订单接口,仅返回已审核订单;如果客户刚建单未审核,需要先审批通过再回来选择。 - 已关联销售订单的保证金,若销售订单后续被作废/反审核,列表仍显示订单号快照,但订单金额为空(销售订单已查不到),不会阻断查看。 - 换客户会清空已选销售订单,避免出现「A 客户的保证金关联 B 客户订单」的错误。 - 前端提交前需把「未退回/无需退回」的退回金额与退回日期置空,否则后端会以状态与金额冲突拒绝保存。 - 操作按钮请使用 `crm:bid-bond:create / update / delete` 权限,不要沿用 `srm:bid-bond:*`。