供应商申诉优化

总览

• /home/supplierPunishCount 除 qualityIssueNum/ qualityLackNum/ qualityReturnNum/ qualityExchangeNum 外的字段，以及 /home/supplierMoney/detail、/home/supplierMoney/punish/detail 供旧版小程序使用；「我的处罚」相关页面使用上表接口。
• 质检问题汇总页 不提供处罚/申诉操作，统一在「我的处罚」处理。

通用约定

• 全部 POST + JSON，返回 { "code": 0, "msg": "success", "data": … }；code != 0 时 msg 直接 toast。
• 时间格式 yyyy-MM-dd HH:mm:ss；金额均为保留 2 位小数的数字。
• 统计方式：两个统计页顶部都有「按月 / 按场次」切换，对应入参 statType（1 按月，默认；2 按场次），汇总数字按所选条件统计。
• 时间范围：month（2026-10）与 roundNo（场次 2026-10-14），都不传 = 当月；传了 roundNo 时月份取该场次所在月。statType=2 且不传 roundNo 时，后端取所选月份最近一个场次，并在出参 roundNo 返回。按 场次日期归属月份，不是按处罚时间。
• 倒计时：列表/详情/统计都返回 serverTime，剩余时间 = appealDeadline - serverTime，本地时钟只用于每秒递减，避免手机时间不准。
• 处罚项：「我的处罚」把三种来源统一成一条处罚项，用 sourceType + sourceId 唯一标识（列表 key 用 itemKey）。

是否可申诉、截止时间都由后端算好（canAppeal / appealDeadline），前端不用自己判断规则。

页面与接口对应

枚举

类目（category → subCategory → 三级类型）

缺货/退货扎数按类目类型集合统计，只统计质检环节处罚（punish_link=1），人工下发、代卖等其他环节的处罚不计入；条件为 pid=0、data_status=0、handle_status IN (0,1)。换货扎数独立取 exchange_log，19、22 不计扎数。

质检类型按处罚环节归类：处罚类型 1、6、7、8、9、11、12、13、15 在质检环节（punish_link=1）和其他环节（人工下发、代卖等）都会出现。只有质检环节的按上表归入「质检处罚」下的缺货 / 退货 / 降级；其他环节的同类型处罚统一归「其他处罚 · 其他处罚（34）」，明细、统计、二级类目卡、typeOptions 同一口径，质检问题汇总的缺货 / 退货扎数也只算质检环节。前端不用判断，按接口返回的 category / subCategory 展示即可。

二级类目 subCategory 有效编码仅以上 9 个，按表中顺序下发。以上树由 ① 的 typeOptions 下发，前端不要写死；「售后处罚」被后台开关关闭时，typeOptions 和 subCategories 里都不会出现 32。

状态

供应商端接口

POST/home/supplierMoney

首页金额接口，其中 monthPunishAmount 用于「本月履约情况 —— 我的处罚 本月扣款 ¥320.00」。

// 响应 data（仅列出本页相关字段）
{ "dayMoney": 126.90, "...": "...", "monthPunishAmount": 320.00 }

POST/home/supplierPunishCount

首页「本月履约情况 —— 质检问题汇总 N 扎」 读 qualityIssueNum。四个字段固定统计当月，与请求里的 startRoundNo/ endRoundNo 无关；其余字段（stockOut、salesReturnNum 等）口径不同，首页卡片不要用。

// 响应 data（仅列出本页相关字段）
{ "stockOut": 3, "...": "...", "qualityIssueNum": 19, "qualityLackNum": 8, "qualityReturnNum": 8, "qualityExchangeNum": 3 }

POST/punish/center/summary

我的处罚统计，按月或按场次。首页「本月扣款」取 /home/supplierMoney 的 monthPunishAmount，见接口 POST /home/supplierMoney。

请求参数

响应 data

示例

// 请求：按月
{ "statType": 1, "month": "2026-10" }
// 请求：按场次（首次切换不传 roundNo，后端取最近场次）
{ "statType": 2, "roundNo": "2026-10-14" }
// 响应 data（按月）
{
  "statType": 1, "month": "2026-10", "roundNo": null, "roundOptions": ["2026-10-14", "2026-10-12"],
  "startRoundNo": "2026-10-01", "endRoundNo": "2026-10-31",
  "actualAmount": 320.00, "totalAmount": 350.00, "appealSuccessAmount": 30.00, "totalCount": 12,
  "pendingAmount": 0.00, "pendingCount": 0,
  "categories": [{
    "category": 1, "categoryName": "质检处罚",
    "actualAmount": 240.00, "totalAmount": 260.00, "appealSuccessAmount": 20.00, "totalCount": 9,
    "subCategories": [
      { "subCategory": 11, "subCategoryName": "缺货", "actualAmount": 60.00, "totalAmount": 60.00, "appealSuccessAmount": 0.00, "totalCount": 3 },
      { "subCategory": 14, "subCategoryName": "降级", "actualAmount": 40.00, "totalAmount": 40.00, "appealSuccessAmount": 0.00, "totalCount": 2 }
    ]
  }],
  "typeOptions": [{ "category": 1, "categoryName": "质检处罚", "subCategories": [
    { "subCategory": 11, "subCategoryName": "缺货", "types": [
      { "sourceType": 1, "punishType": 6, "name": "缺货补货" },
      { "sourceType": 1, "punishType": 9, "name": "缺货不补" } ] } ] }],
  "serverTime": "2026-10-21 10:00:00"
}

POST/punish/center/list

处罚明细。按处罚时间倒序。

请求参数（包含 ① 的 statType / month / roundNo）

响应 data

{ total, records[], serverTime }，records[] 字段：

示例

// 请求
{ "statType": 1, "month": "2026-10", "category": 1, "sourceType": 1, "punishType": 7,
  "deductStatus": null, "appealStatus": null, "pageIndex": 1, "pageSize": 20 }
// 响应 data
{ "total": 4, "serverTime": "2026-10-21 10:00:00", "records": [{
    "itemKey": "1_922652537", "sourceType": 1, "sourceId": 922652537,
    "category": 1, "categoryName": "质检处罚", "subCategory": 12, "subCategoryName": "退货",
    "punishType": 7, "typeName": "退货不补", "title": "退货处罚",
    "roundNo": "2026-10-09", "punishTime": "2026-10-09 17:16:00",
    "productName": "卡罗拉", "rankNum": 2, "skuDesc": "中熟", "productFullName": "卡罗拉B级中熟",
    "num": 5, "orderItemUrl": "https://…",
    "reason": "花材品质不达标", "orderSn": "T2026100910033425",
    "punishAmount": 45.00, "returnedAmount": 0.00, "actualAmount": 45.00,
    "deductStatus": 2, "deductStatusName": "已扣款", "appealStatus": 0, "appealStatusName": "未申诉",
    "statusTag": 1, "statusTagName": "待申诉",
    "complainType": 3, "canAppeal": true, "nextAppealNo": 1, "appealDeadline": "2026-10-21 17:16:00",
    "canCancelAppeal": false, "latestComplainId": null, "latestComplain": null }] }

POST/punish/center/detail

请求参数

响应 data = 列表项全部字段 + 以下字段

处罚不存在、不属于本人、已被运营直接撤销、已取消、处罚金额为 0，或为城市仓处罚、供应商拒不开票处罚时返回失败「处罚不存在」。

POST/home/qualityIssue/summary

请求参数

响应 data

// 请求：按月
{ "statType": 1, "month": "2026-10" }
// 请求：按场次
{ "statType": 2, "roundNo": "2026-10-14" }
// 响应 data（按月）
{
  "statType": 1, "month": "2026-10", "roundNo": null, "roundCount": 2, "saleNum": 50, "lackNum": 2, "returnNum": 5, "exchangeNum": 3,
  "roundOptions": ["2026-10-14", "2026-10-12"],
  "rounds": [{
    "roundNo": "2026-10-14", "productKinds": 5, "saleNum": 32, "lackNum": 2, "returnNum": 3, "exchangeNum": 2,
    "punishCount": 5, "punishAmount": 120.00,
    "items": [{ "productId": 1, "productName": "高原红", "rankNum": 1, "saleNum": 8, "lackNum": 1, "returnNum": 1, "exchangeNum": 2, "skuDesc": "卷边", "productFullName": "高原红A级卷边" }]
  }]
}

• 「查看处罚明细」跳我的处罚并定位质检 Tab：summary 传 {statType:2, roundNo}，list 传 {statType:2, roundNo, category:1}。列表 total 等于场次卡 punishCount，已扣款/已退回项 actualAmount 之和等于 punishAmount。
• 缺货/退货扎数按类目类型集合统计有效处罚，只统计质检环节处罚（punish_link=1），人工下发、代卖等其他环节的处罚不计入；申诉成功的不计入。缺货类型为 1、6、9；退货类型为 7、8、11、12；与二级类目 11/12 一致。换货独立取 exchange_log 的 SUM(num)，过滤本人、场次区间、status=0、num>0，包含扫码及批量换货；type 18、19、22、25 的处罚数量不参与扎数统计。只有换货的场次也进入 roundOptions。

POST/comment/complain

提交申诉。成功后刷新列表/详情/统计。

缺货赔付申诉（complainType=6）可能的失败提示

• 缺货赔付记录不存在 / 缺货赔付未扣款，不能申诉 / 缺货赔付金额异常
• 缺货赔付扣款后72小时内才可以申诉
• 同条缺货赔付记录最多申诉1次

POST/comment/complain/cancel

撤回申诉：{ "id": latestComplainId }，仅 canCancelAppeal = true 时显示按钮（只有处罚申诉支持撤回）。

列表/详情展示规则

客服只展示 ID：详情 operatorId（下发人）、列表 latestComplain.operatorId 与详情 complainHistory[].operatorId（处理人）显示「客服：ID」，0 或 null 显示「系统」；operatorName 恒为 null；sourceDesc 不含客服或质检员姓名。适用于 /punish/center/* 与 /home/qualityIssue/summary。

状态标签

列表/详情统一读取 statusTag / statusTagName；按下表优先判断待扣款。申诉状态筛选仍用 appealStatus，不增加「已确认」筛选项。驳回后可二诉时仍显示「申诉拒绝」，同时显示再次申诉按钮及倒计时。

金额

• 卡片金额显示 punishAmount；returnedAmount > 0 时加删除线，可附「实扣 ¥ actualAmount」（部分退回时实扣不为 0）。

提示条

按钮

运营后台

POST/order/complain/list

入参（申诉来源相关）

records[] 字段（申诉来源相关）

• 「关联订单/商品/售后」列：1 用 orderItemComment，2 用 refundInfo，6 用 orderPaidInfo。
• 「退回金额」列：已同意时显示 returnMoney。
• 城市仓/分销商名称（wareName / partnerName / platformStr）对 2 和 6 都会回填。
• 导出（exportFlag=1）包含「申诉来源」「实际扣款金额」两列，类型 6 的「关联订单号」取赔付记录订单号。

POST/order/complain/check

可能的失败提示

• 缺货赔付申诉同意时需要填写退回金额 / 退回金额不能小于等于0
• 退回金额不能超过实际扣款金额，最多可退：x 元
• 驳回申诉必须填写驳回原因
• 缺货赔付记录不存在 / 缺货赔付未扣款，不能退回
• 已有其他已创建、已同意的申诉，无法通过该条申诉 id:x

审核后 12 小时内的「撤销」（/order/complain/revoke）也支持类型 6，撤销时会扣回已退金额；canRevoke 字段照常返回。

联调注意

• 待扣款（质检处罚待运营审核）会出现在明细里，但不计入实际处罚/总处罚、不可申诉；运营审核通过后变为已扣款，开始 48h 申诉窗口。
• 不展示：运营直接撤销的处罚、已取消/删除的处罚、处罚金额为 0 的处罚（含退款支出、缺货赔付）、城市仓处罚、供应商拒不开票处罚。申诉成功的处罚会展示为「已退回」。
• 0 元处罚不计入统计（实际处罚、共 N 笔、待扣款、各类目/二级类目笔数、首页「本月扣款」、质检场次卡「共 N 条处罚 · ¥X」），与明细列表一致。质检汇总的缺货/退货扎数是质检数量，仍包含 0 元处罚对应的扎数。
• 城市仓处罚、供应商拒不开票处罚不属于「我的处罚」：下拉选项、统计、明细、首页「本月扣款」、质检场次卡均不包含，详情返回「处罚不存在」。
• 售后处罚（退款支出、缺货赔付）可由后台 Nacos 开关整体关闭；关闭后统计、明细、下拉里都没有 32，前端无需判断。
• 退款支出不含极速退款（售后类型 1、2、4、5，未发货退款，供应商不承担）、退运费（7）和质检处罚退款（8，已在处罚中体现）；这几类不出现在明细、统计、首页「本月扣款」里。
• 运营端「售后申诉」Tab 用于历史查看；处理统一在「商品申诉」Tab。
• 测试环境：先部署 admin（能审核 6），再部署 supplier（能提交 6）。