业务流程说明
履约保证金扣减业务规则、操作流程及注意事项 — 供业务沟通与开发实现参考
气合网平台合同执行过程中，若买卖任一方发生违约行为（如未按期交货、数量短缺等）， 守约方有权发起履约保证金扣减申请。
扣减流程采用"发起方申请 → 被申请方确认/拒绝 → 系统执行"的双方协商机制， 不经平台单方审批，保障双方权益对等。该功能为低频非常规业务场景， 仅在合同执行状态为「标记违约」时可触发。
命名约定：本模块统一使用「履约保证金」，与系统中的「履约保证金」（另一业务）相区分。 二者逻辑独立，本原型仅涵盖履约保证金的扣减流程。
（违约类型/金额/原因/附件）
状态→「待对方确认」
查看申请详情
更新履约保证金余额
状态→「已确认」
状态→「已拒绝」
通知买方
重新提交申请
超期 → 自动关闭
状态→「已关闭」
通知双方
注：虚线为系统自动通知；实线为用户主动操作；「系统」泳道代表气合网平台后端逻辑。
注：「已确认」「已关闭」「已撤回」为终态，不可再流转
| 角色 | 可执行操作 | 触发条件 |
|---|---|---|
| 买方 |
| 合同执行状态为「标记违约」 |
| 卖方 |
| 合同执行状态为「标记违约」 |
| 平台管理员 |
| 无限制，管理后台专属 |
扣减金额规则
- • 支持部分扣减，金额须 > 0 且 ≤ 当前履约保证金余额
- • 单次申请对应一条违约事项；多次违约需分别发起独立申请
- • 扣减金额由申请方自主填写，被申请方可因金额争议拒绝
- • 履约保证金余额扣减至 0 后不可再发起新申请
违约类型（枚举）
佐证材料要求
- • 支持上传 PDF、图片（JPG/PNG）、Excel 格式，单文件建议 ≤ 20 MB
- • 建议提供：合同扫描件、计量报告、违约通知书、催货函件、往来邮件等
- • 被申请方确认/拒绝时，同样可附上反驳材料
- • 附件存储于对象存储（OSS），数据库仅保存文件 URL
超时处理规则
- • 申请提交后，被申请方须在 7 个工作日内确认或拒绝
- • 超时后系统自动将申请状态更新为「已关闭」，并通知双方
- • 申请关闭后，发起方可就同一合同重新发起新的扣减申请
- • 「已关闭」记录保留，不可删除，供审计追溯
重新申请规则
- • 申请被拒绝后，发起方可就同一合同重新发起申请（入口在扣减详情抽屉底部）
- • 重新申请时建议修改金额或补充更完整的证明材料
- • 重新申请后，前一条拒绝记录仍保留，不会被覆盖
- • 同一合同同一时间只允许存在一条「待对方确认」状态的申请
记录导出规则（管理后台）
- • 管理员可在「扣减记录」页面导出当前筛选结果为 Excel 文件
- • 导出字段：扣减单号、合同编号、申请方、被申请方、违约类型、扣减金额、履约保证金变化、状态、申请时间、处理时间
- • 导出范围受当前 Tab（全部/待确认/已完成）及搜索条件约束
合同订单主入口，切换买家/卖家视角
- 标记违约 + 无记录 → 「履约保证金扣减」按钮（红色），发起申请
- 待确认（发起方）→ 「待确认」按钮（橙色边框），点击查看进度
- 待确认（接收方）→ 「处理扣减」按钮（橙色实色），进入处理流程
- 已确认 → 「扣减详情」按钮（绿色边框），查看执行结果
- 已拒绝 → 「扣减详情」按钮（红色边框），底部可重新申请
- 订单详情按钮（灰色置灰）：系统已有功能，原型中不可点击
平台管理视角，查看所有扣减申请记录
- Tab 筛选：全部 / 待确认 / 已完成
- 支持搜索单号、合同编号、申请方
- 点击「查看」查看扣减详情及操作时间线
- 「导出记录」按钮：导出当前筛选结果为 Excel
供业务沟通和开发实现参考
- 时序图、状态机、角色权限表、业务规则、开发注意事项
提交申请前，后端须检查同一合同是否已存在「待对方确认」状态的记录；若存在则拒绝重复提交，返回提示信息。前端检查不能代替后端校验。
申请「已确认」后，需同步更新合同表 performanceBondRemaining 字段，确保订单列表与管理后台数据实时一致。建议在事务中执行扣减和余额更新，避免部分失败。
需实现定时任务（Cron Job），每日检查「待对方确认」超过 7 个工作日的申请，自动更新状态为「已关闭」并推送通知。注意工作日计算需排除法定节假日。
申请提交 → 通知被申请方；对方处理（确认/拒绝）→ 通知申请方；系统超时关闭 → 通知双方。通知渠道可为站内信 + 短信，需持久化通知记录。
确认/拒绝操作须严格校验当前用户角色，禁止对己方发起的申请执行确认/拒绝。前端判断不可信，API 层必须二次校验 applicantRole 与当前用户身份。
所有扣减申请记录不可物理删除，需完整保留供审计和纠纷处理。已关闭/已撤回记录可软删除（is_deleted 标志），但后台管理仍可查询。
管理后台导出接口需支持分页全量导出（不受分页限制），返回 Excel 流（application/vnd.openxmlformats-officedocument.spreadsheetml.sheet），文件名含导出时间戳。大数据量建议异步导出+下载链接。
附件存于 OSS，数据库仅存文件 URL。上传时校验文件类型（白名单：pdf/jpg/png/xlsx），单文件限制 20MB，单次申请附件总数建议 ≤ 10 个。