furniture-3d-system-Wu/furniture-3d-system/docs/限价与破价判定规则.md

限价与破价判定规则（业务确认版）

适用范围：限价管理 · 破价订单审核（/supply-chain/management/custom-table → 破价订单审核） 本文件为业务口径的唯一来源；规则变更请改本文件并注明生效时间。

一、限价与判定口径

1. 判定基准：以「商家实收」为准；商家实收 < 限价 × 数量 即判定破价。
2. 实付款与平台承担：实付款 + 平台承担（红包 / 消费券 / 平台券）= 商家实收；凭证必须同时包含「实付款」和「数量」。
3. 出资方字典
   • 商家承担：店铺优惠（官方立减、单品直降、店铺券）、政府补贴
   • 平台承担：红包、消费券、平台券、平台优惠、新品礼金
   • 买家承担：淘金币
   • 待定：首单礼金（等与运营确认后补录）
4. 限价维度：按货号限价——同一货号下所有规格/条码共用同一套限价。
5. 限价时间版本：按订单付款时点生效的限价判定（限价调整前后分别取当时版本），不做"用最新限价回算历史单"。
6. 成本变动规则（限价维护侧）：成本价上涨 5% 以内不动限价；成本价下调不变限价。
7. 非负责人限价：2026-10-07 00:00 前的 ID 价格不判定破价（此后按规则判定）。
8. 老链接分界：上架时间早于 2026-10-07 00:00 的链接（老链接）破价申诉通过；之后的按限价流程结束日期判定（上架时间需早于流程结束日期），并核对店铺款式编码 / 商品编码。
9. 负责人触发规则：非运营发起的流程，前两个月全公司运营同价（不归属个人）；两个月后按销量触发负责人（销量高者为负责人）。
10. 数据快照：破价单在生成时保存金额快照；退款/售后状态单独记录，退款不等于免责（仍需判断是否已调价）。
11. 离职人员：订单负责人已离职 → 自动标记「人员已离职」，不判定、不计乐捐。
12. 是否有检测报告：取素材平台「检测报告」接口（/api/external/certificate-reports，按 SPU 精确匹配，只认有报告文件的记录），进程内缓存 10 分钟； 接口未配置或读取失败时该列显示为空、筛选候选值为空。配置项：MATERIAL_LIBRARY_CERTIFICATE_REPORT_API_BASE_URL/API_KEY， 不填则复用素材平台 MATERIAL_LIBRARY_WHITE_BACKGROUND_API_*。
13. 手工换货单：聚水潭订单明细出现「被替换行（item_status=Replaced、数量归 0）」+「换入行（item_ext_data 含 item_source=手工换货/手工添加）」时按换货单处理：
    • 判定按换出行原编码的限价执行（客户在平台上购买的那个编码）；
    • 成交数量与商家实收取换入行（换货不改变订单成交金额）；换入行金额抓不到时回退订单主表商家实收 → 订单主表买家实付，都取不到才按 0（由运营申诉说明）；
    • 换货行配对成功后按原编码生成一条，不再按换入编码单独生成，避免同一订单重复生成两条破价单；
    • 配对优先按 sku_uuid 精确匹配，剩余行仅在一对一时顺序配对；复杂结构（多对多）暂不强行配对，相关行按各自编码现状处理。

二、申诉与审核

1. 申诉类型（4 组）
   • 链接时间：老链接，上架时间早于限价流程（凭证须含链接 ID + 创建时间）/ 京喜换主体 · 老店转新店
   • 优惠 / 活动：平台优惠 · 红包 · 券（非商家承担）/ 参与秒杀 · 百补 · 大促等平台活动（凭证须含活动开始与截止时间，且活动价未破价）/ 拼多多多件折扣（99折）
   • 流程申请：已走新品限价及限价调整（必填流程号，系统到「新品限价及限价调整」流程校验，查不到不允许提交）
   • 其他原因（须在备注中详细说明）
2. 申诉范围：链接时间 / 流程申请类支持链接级一次性申诉（默认勾选，覆盖该链接下全部破价订单，后续新单自动继承）；优惠 / 活动类按订单申诉。
3. 审核要点仅审核人可见；申诉人只看到凭证要求与示例图。
4. 凭证校验：必填校验 + 识别提示（识别结果仅提示，人工一键打回）；后续增加图片查重（hash / 相似度）与关键字段（订单号、链接 ID）一致性校验。
5. 乐捐：驳回计 ¥10/单（离职不计）；配套审计链（数据快照 + 申诉材料 + 审核记录），扣款执行交财务确认，保留异议通道。
6. 举证期限：待与运营确认后设置（避免事后无法追溯凭证）。

三、权限（由管理员统一管理）

路径：用户管理后台 → 权限配置 → 经营管理。限价管理相关的查看 / 导出 / 申诉都由管理员在这里开通。

能力	权限节点	动作
页面与数据查看（限价明细、破价订单审核）	限价管理	可见
导出（导出明细 / 导出明细（含图片）/ 破价订单导出 / 乐捐明细）	限价管理	下载
申诉 · 审核 · 生成 · 导入	限价管理	操作
规则配置（页面可见 + 保存参数）	限价管理 · 规则配置	可见 / 操作

• 没有「下载」权限时页面不展示导出入口，服务端导出接口同样鉴权（下载中心任务按「限价管理 · 下载」校验）。
• 没有「操作」权限时：不显示申诉/审核按钮，服务端也会拒绝申诉、审核、生成、导入。
• 申诉保留一条兜底：破价单的负责人本人，即使没有「操作」权限，也可以对本人负责的订单发起申诉（审核仍需「操作」）。
• 没有「规则配置」权限时，规则配置页签不显示、接口不可调用。

四、生成与运行

1. 按天增量：限价逻辑上线后，破价订单按天增量生成（每天只生成最新一天的破价单并入库），历史数据不再重复回算；破价订单审核页每天展示最新破价单。

2. 数据来源：聚水潭报表库（jst_Orders + jst_OrderItem / 天猫奇门 jst_qmcust_orderlist + _item），取 seller_income_amount、buyer_paid_amount、qty、shop_i_id、shop_sku_id、pay_date、退款状态，以及换货识别字段 item_status、item_ext_data（item_source、sku_uuid）。报表库查询较慢，逐日增量任务建议按天分片拉取。

3. 限价来源：钉钉流程（仅取已完结），共 4 个模板，同步脚本 scripts/sync-limit-workflows.mjs：

   • 「新品限价及限价调整」→ 货号取「货号(非商品编码)」，限价取「期望日常限价」； 其中的「调整限价明细表」子表（申请类型=调整原货号限价）只填「调整后限价」，该列同样作为限价取值 （2026-10-16 修复，此前这类调价会被漏掉）；
   • 「新品限价流程」→ 明细取系统产品限价页面（按流程链接 SPU 关联）。页面数据来自正式库 external.product_catalog_wide_v1（限价字段：expected_daily_limit_price / non_spu_owner_limit_price）， 本地库该视图为空时退回本地 IntakeNonIntegratedProduct(LimitRow)；
   • 「各中心特殊限价需求申请」→ 货号取「货号」，限价取「最低售价」；
   • 「GB特殊限价需求申请」→ 货号取「货号」，限价取「期望日常限价」（2026-10-16 纳入）。
   • 「产品限价页面」已确认（CONFIRMED）的限价全量纳入（2026-10-16）：来源正式库 external.product_catalog_wide_v1，给没有限价流程的货号兜底（如 CY012801=268.6）； 同货号与流程限价冲突时以流程为准，页面价只在流程没覆盖时生效。
   • 「限价期初数据」（业务整理的存量限价 Excel，2026-10-16 纳入）：放在期初数据目录 （LIMIT_SYNC_INITIAL_DIR，默认 <app>/期初数据；目录为空时用仓库自带 scripts/data/limit-sync/期初数据/限价期初数据*.xlsx），取目录里最新一份， 按「货号 + 负责人限价 + 更新日期」写入，作为最低优先级兜底（如 MKHDNZ0409260600468=279）。

   优先级：限价流程 > 产品限价页面（已确认）> 限价期初数据；低优先级只在货号没有更高优先级限价时生效。 例外（2026-10-16 确认）：期初数据的「更新日期」晚于流程完成时间时，以期初数据为准（谁新用谁）； 期初比流程旧则维持上面的优先级。 非负责人限价一律按最新口径计算（2026-10-16 确认）：负责人限价 × 1.05，且不低于 +10 元； 期初数据表 / 产品限价页面里的历史「非负责人限价」（倍数 1%～15% 不统一）不采用， 限价明细页、导出文件、破价判定三处都用同一公式。 写入规则：同货号多流程取审核通过时间最新的一条；限价为 0 或空的明细剔除；「申请与SPU负责人同价 / 活动限价」不覆盖负责人限价，只作为价格授权；流程「货号」列若填的是商品编码，用商品编码匹配产品档案换算为货号；无货号时同样用商品编码匹配。页面限价的时间按北京时间墙钟存（与流程完成时间一致）。

4. 覆盖率：暂不做未匹配清单与告警（后续优化）。

5. 正式站同步（服务器端）：scripts/sync-limit-workflows.mjs 已改成服务器可运行，连接信息全部取 服务器 shared/.env 里的既有变量（DATABASE_URL / JST_REPORT_DB_* / PROD_ARCHIVE_DB_*）， 不再依赖 Mac 本地路径：

   # 手动跑一次（正式站目录下，root 或能读 shared/.env 的账号）
   cd /opt/furniture-3d-system-prod/current/furniture-3d-system
   sudo -E bash -lc 'set -a; . /opt/furniture-3d-system-prod/shared/.env; set +a; \
     LIMIT_SYNC_OUT_DIR=/opt/furniture-3d-system-prod/shared/limit-workflow-sync/导出结果 \
     LIMIT_SYNC_INITIAL_DIR=/opt/furniture-3d-system-prod/shared/limit-workflow-sync/期初数据 \
     node scripts/run-limit-workflow-sync-production.cjs'
   
   # 安装每日定时器（systemd，与营销日销同一套样板）：每天北京时间 07:30
   sudo bash scripts/install-limit-workflow-sync-timer.sh
   systemctl list-timers --all 'furniture-limit-workflow-sync*' --no-pager
   journalctl -u furniture-limit-workflow-sync.service -n 200 --no-pager
   

   • 写库是全量重建 + 单事务：成功才提交；失败自动回滚，正式库保留上一版限价与授权。
   • 输出目录 LIMIT_SYNC_OUT_DIR（默认 <app>/导出结果）里的 限价流程_完整明细表.xlsx 每日覆盖， 旧版本进 历史版本/，默认保留最近 20 份（LIMIT_SYNC_HISTORY_KEEP）。
   • --skip-excel / LIMIT_SYNC_SKIP_EXCEL=1 可只写库不导 Excel。
   • 期初数据更新：把新的 限价期初数据*.xlsx 放进 shared/limit-workflow-sync/期初数据/ 即可，下次同步自动取最新。
   • SupplyChainBreachRuleConfig 不需要灌数：接口读取时用代码内置默认值，首次在「规则配置」保存时落库。

五、待办

• 限价流程数据接入 + 筛选逻辑（生效时间版本、货号维度）
• 非负责人限价 10-07 规则、负责人触发规则（前两个月同价 / 两个月后按销量）落到判定引擎
• 按天增量任务（cron / worker）与失败告警
• 凭证查重（hash / 相似度）、关键字段一致性校验
• 举证期限、乐捐财务对接流程
• 首单礼金 / 新品礼金出资方确认后补录出资方字典