供应链管理平台产品系统Vibe Coding

项目立项原因
一、业务背景
1889 供应链协同平台需要接入天马等作为货品供应商，实现 商品、库存、订单、售后、物流 全链路自动化的双向数据同步，替代人工手工操作。
二、核心痛点（立项前的问题）
痛点 具体表现 库存不同步 天马库存变化无法自动推送到 1889，导致超卖或库存积压，需人工对账 折扣丢失 天马改了折扣但推不到 1889，4244 个货号折扣从未成功推送，业务人员以为设置了但 1889 看不到 售后流程断裂 1889 的售后退货无法自动同步到天马（problem_type 映射错误，"七天无理由"被错判成"快递问题"），天马要求上传图片导致退货失败 退回地址不可控 用户寄回地址与天马实际核销仓地址不一致，售后单无法核销，地址全靠人工复制粘贴 快递运费断裂 天马运费接口返回短名（中通），映射表配长名（中通快递），精确匹配断裂导致 151 条省份运费从未推送到 1889 全人工操作 新增快递需逐渠道手动激活；售后地址需手动查天马接口再粘贴；库存推送阈值无弹性配置
三、项目目标
1. 库存同步 ：定时拉取天马库存 → 写中间表对比变化 → 按推送阈值规则推 1889，支持手动单条推送
2. 折扣同步 ：天马折扣变化自动推送 1889，历史遗漏批量补推
3. 售后自动化 ：1889 售后单 → 自动映射退货原因 → 推天马创建售后申请 → 同步退回快递单号 → 监测退回地址一致性
4. 退回地址监测 ：定时对比天马实际退回地址与基准地址，不一致自动报警
5. 快递运费管理 ：天马运费自动同步推 1889，供应商新增快递一键全渠道启用
6. 多供应商解耦 ：通过`IProductSource` 接口抽象，天马只是第一个供应商，后续接入其他供应商零改动

1、项目背景与设计思路
由于货源方与销售平台（ERP）之间数据割裂，订单、库存、运费、售后全靠人工登录双系统操作，效率低且易出错。本项目采用 SaaS 化标准化管理模式，销售平台（1889）作为固定的核心方，深度对接多个货源方（如天马、第三方 ERP），提供专属的配置化接口服务。旨在开发一个纯数据桥接中间件，实现两大系统间的全自动化数据交互，降低人工成本，提升发货准确率和业务响应速度。

2、软件功能、核心功能模块
系统包含四大核心模块：

订单同步：自动拉取销售平台配货中订单，经过库存/余额校验和仓库/货号/尺码映射后，调用货源方 API 下单，并回写运单号至销售平台。

库存同步：定时拉取货源方库存快照，通过 MD5 对比找出变化 SKU，根据鞋类/非鞋类规则转换尺码，按批推送至销售平台并记录日志。

运费同步：同步货源方运费规则，区分自营仓与非自营仓（含快递映射），批量更新销售平台运费策略。

售后同步：实现双向售后同步，定时拉取 1889 售后申请（四阶段：A 申请 / B 状态查询 / C 失败重试 / D 退货快递回传），自动调货源方售后 API 并回写处理结果。

3、业务流程与功能路径
以订单为例，业务路径为：
Hangfire 每 30 秒拉取 1889 订单（Type=3 配货中）
→ 映射仓库、货号、尺码
→ 前置检查（库存 / 余额 / 地址完整性）
→ 调用货源方下单 API 获取运单号
→ 回写销售平台物流信息
异常闭环：若失败则自动重试 3 次，仍失败则转人工，并在订单页展示具体原因，实现全链路异常闭环。由于是单货源方的 SaaS 化统一管理，所有操作均围绕固定货源方的标准接口进行深度优化，无需频繁适配多货源逻辑，大大提升了系统的稳定性与维护效率。

思考过程
项目实现（最终定稿版）
1、整体架构和设计思路
采用前后端分离架构 + 中间件设计模式。后端基于 .NET 8 + SqlSugar ORM 构建高并发的 API 网关和定时任务引擎，使用 Hangfire + Redis 持久化任务队列，保障任务不丢失并支持多 Worker 并发调度（5 个 Worker 实例）。前端采用 Vue 3 + Vite + Element Plus + TypeScript 构建 SaaS 化"配置中心"管理后台，支持非研发人员自助配置（仓库映射、尺码规则、快递映射、预警阈值等），契合"固定单货源方"的统一标准化管理需求。

数据层采用多存储隔离策略：

MySQL 存储核心业务映射数据和配置信息，保证强一致性，含结构化运行日志（integration_log / sync_task_log，按 365 天 retention 自动清理）；
Serilog 按天分目录落文件日志（warning / error / fatal），便于回溯排查；
Redis（DB 5） 作为 Hangfire 任务存储和业务缓存，避免与 MySQL 共享时的 InnoDB 锁竞争，同时用于订单去重和热点配置缓存。
该架构设计使系统具备高吞吐、高可用及极佳的可维护性。

2、负责模块和结果
独立负责订单、库存、运费、售后四大同步引擎的架构设计与核心代码编写，并搭建 Vue 可视化配置中心。

订单同步：通过 Hangfire 每 30 秒高效拉取，引入"前置预校验 + 数据库唯一索引幂等去重"机制，实现日均数千单的自动化下单回写，历史订单零重复。

库存同步：基于 MD5 哈希的增量对比机制，将每日对货源方接口的无效请求量降低了 90% 以上。结合尺码转换引擎（区分鞋类 PickNonEuSize 与非鞋类尺码映射），实现库存数据分钟级精准同步。

运费