货件-货件跟踪 货件跟踪模块功能解析文档 1. 模块架构概述 货件跟踪模块是 Wimoor 系统中用于管理和跟踪 FBA 货件整个生命周期的重要功能模块。该模块采用前后端分离架构，前端使用 Vue 3 + Element Plus 开发，后端采用 Java + MyBatis Plus 开发，支持多物流系统集成。 1.1 系统架构 flowchart TD A[前端界面] --> B[API调用] B --> C[后端服务] C --> D[物流系统API] D --> E[物流服务商] C --> F[数据库] E --> D 1.2 核心组件 组件 职责 技术实现 货件列表页面 展示和管理货件列表 Vue 3 + Element Plus 货件表格组件 展示货件详细信息 Vue 3 + Element Plus 物流信息弹窗 展示物流详情和轨迹 Vue 3 + Element Plus 后端服务 处理业务逻辑和数据 Java + Spring Boot 物流系统集成 与外部物流系统交互 RESTful API 数据库 存储货件和物流信息 MySQL 2. 前端代码分析 2.1 核心页面结构 2.1.1 货件处理列表页面 ( index.vue ) 主要功能 ： 提供货件状态标签栏，支持按状态筛选货件 集成筛选和搜索功能 管理表格组件和头部组件的交互 关键代码分析 ： 状态标签切换逻辑：通过 activeName 变量控制当前选中的状态标签，根据不同标签设置不同的 orderStatus 值 数据传递：通过 getdata 方法接收头部组件的筛选条件，通过 tableRef.value.getshipmentData(obj) 传递给表格组件 标签点击事件：通过 handleClick 方法处理标签切换事件，更新筛选条件并重新加载数据 // 状态标签切换逻辑 function handleClick(){ if(activeName.value=="0"){ obj.orderStatus = "" obj.hasexceptionnum=null; }else if(activeName.value=="1"){ obj.orderStatus = 7 obj.hasexceptionnum=null; }else if(activeName.value=="2"){ obj.orderStatus = 5 obj.hasexceptionnum=null; }else if(activeName.value=="3"){ obj.orderStatus = 55 obj.hasexceptionnum=null; }else if(activeName.value=="4"){ obj.orderStatus = 6 obj.hasexceptionnum=null; }else if(activeName.value=="5"){ obj.orderStatus = 0 obj.hasexceptionnum=null; }else if(activeName.value=="6"){ obj.hasexceptionnum='ok'; obj.orderStatus = 6 } tableRef.value.getshipmentData(obj); headerRef.value.statusChange(obj); } 2.1.2 货件表格组件 ( table.vue ) 主要功能 ： 展示货件详细信息，包括货件编码、店铺、配送中心、创建日期等 提供物流信息查看、跟踪发货、异常处理等操作 支持表格排序和筛选 关键代码分析 ： 数据加载：通过 loadtableData 方法加载货件数据，构建请求参数并调用后端 API 物流信息查看：通过 showTransInfoDailog 方法打开物流信息弹窗，传递货件相关参数 跟踪发货：通过 shipmentfollow 方法跳转到货件跟踪页面 异常处理：通过 refreshShipmentDialog 和 ignoreShipmentWarn 方法处理异常货件 // 加载货件数据 function loadtableData(params){ params.groupid = parmashead.value.store; params.marketplaceid =parmashead.value.country; params.warehouseid =parmashead.value.warehouse; params.fbacenter=parmashead.value.fbacenter; if(parmashead.value.start!==undefined){ params.fromdate = parmashead.value.start; params.enddate =parmashead.value.end; }else{ const end = new Date() const start = new Date() start.setTime(start.getTime() - 3600 * 1000 * 24 * 7) params.fromdate =dateFormat(start); params.enddate =dateFormat(end); } params.auditstatus = parmashead.value.orderStatus; if(parmashead.value.seachtype!==undefined){ params.searchtype =parmashead.value.seachtype; }else{ params.searchtype ="sku"; } params.search = parmashead.value.searchwords; params.company =parmashead.value.company; params.channel= parmashead.value.channel; params.transtype =parmashead.value.transtype; params.checkdown=parmashead.value.checkdown; params.checkinv=parmashead.value.checkinv; params.areCasesRequired=parmashead.value.areCasesRequired; params.hasexceptionnum=parmashead.value.hasexceptionnum; params.hasreferenceid=parmashead.value.hasreferenceid; var tagtypes=["primary","success","info","warning","danger"]; shipmenthandlingApi.getshipList(params).then((res)=>{ var indexv=0; res.data.records.forEach(itemv=>{ if(oldcheckinv[itemv.checkinv]==undefined){ indexv=(indexv+1)%5; itemv.tagtype=tagtypes[indexv]; oldcheckinv[itemv.checkinv]=indexv; }else{ itemv.tagtype=tagtypes[oldcheckinv[itemv.checkinv]]; } }); tableData.records = res.data.records; tableData.total =res.data.total; }) } 2.1.3 物流信息弹窗 ( transinfo.vue ) 主要功能 ： 支持多种物流系统（ZH和ZM） 展示货件基本信息、收件人和发件人地址 以时间线形式展示物流轨迹 展示货箱详情表格 关键代码分析 ： 物流数据加载：通过 loadTransDetialInfo 方法加载物流详细信息，根据物流系统类型调用不同的处理方法 ZH物流系统处理：通过 loadZhApiDetail 方法处理ZH物流系统的数据 ZM物流系统处理：通过 loadZmApiDetail 方法处理ZM物流系统的数据 // 加载物流详细信息 function loadTransDetialInfo(companyid,shipmentid,ordernum){ var html=""; loading.value=true; shipment.value=""; zmData.value=""; transportationApi.shipTransDetial({"companyid": companyid,"shipmentid":shipmentid,"ordernum":ordernum}).then(res=>{ loading.value=false; if(res && res.data.ftype=="ZH"){ systemType.value=res.data.ftype; loadZhApiDetail(res.data,companyid,shipmentid); } if(res && res.data.ftype=="ZM"){ systemType.value=res.data.ftype; loadZmApiDetail(res.data); } }) dialogTransVisible.value=true; } 2.2 前端 API 调用 2.2.1 货件数据 API shipmenthandlingApi.getshipList(params) ：获取货件列表数据 参数 ：筛选条件，包括店铺、国家、仓库、日期、状态等 返回值 ：货件列表数据，包括货件编码、状态、物流信息等 2.2.2 物流信息 API transportationApi.shipTransDetial(params) ：获取物流详细信息 参数 ：公司ID、货件ID、订单号 返回值 ：物流详细信息，包括服务类型、运费、轨迹等 2.2.3 货件操作 API shipmentApi.refreshShipmentRec(params) ：刷新货件接收状态 参数 ：货件ID 返回值 ：同步结果 shipmentApi.ignoreShipment(params) ：忽略货件异常 参数 ：货件ID 返回值 ：忽略结果 2.3 前端状态管理 组件状态 ：使用 Vue 3 的 ref 和 reactive 管理组件内部状态 数据传递 ：通过 props 和 emit 实现组件间数据传递 路由跳转 ：使用 Vue Router 实现页面跳转 3. 后端代码分析 3.1 核心实体 3.1.1 货件实体 ( Shipment.java ) 主要属性 ： 买家ID、货件名称、目的地 重量、体积、状态 货箱列表、商品列表 关联关系 ： 一对多：一个货件包含多个货箱 一对多：一个货件包含多个商品 3.2 核心服务 3.2.1 货件服务 主要功能 ： 货件数据的增删改查 货件状态的管理和更新 货件与物流系统的交互 3.2.2 物流服务 主要功能 ： 与外部物流系统的API交互 物流信息的获取和解析 物流轨迹的处理和存储 3.3 后端 API 接口 3.3.1 货件列表接口 路径 ： /api/erp/ship/shipmenthandling/getshipList 方法 ：GET 参数 ：筛选条件，包括店铺、国家、仓库、日期、状态等 返回值 ：货件列表数据，包括货件编码、状态、物流信息等 3.3.2 物流详细信息接口 路径 ： /api/erp/ship/transportation/shipTransDetial 方法 ：GET 参数 ：公司ID、货件ID、订单号 返回值 ：物流详细信息，包括服务类型、运费、轨迹等 3.3.3 货件状态同步接口 路径 ： /api/erp/ship/shipment/refreshShipmentRec 方法 ：GET 参数 ：货件ID 返回值 ：同步结果 4. 物流系统集成 4.1 支持的物流系统 ZH物流系统 ： 提供详细的物流信息，包括服务类型、运费、状态等 支持货箱详情的查看 以时间线形式展示完整的物流轨迹 ZM物流系统 ： 提供运单号码和物流轨迹 以时间线形式展示物流状态变更 4.2 物流系统 API 集成 4.2.1 API 调用流程 前端调用后端物流信息接口 后端根据物流系统类型调用相应的外部 API 外部物流系统返回物流信息 后端解析和处理物流信息 后端返回处理后的物流信息给前端 前端以统一的格式展示物流信息 4.2.2 数据格式处理 ZH物流系统数据格式 ： { "service_name": "快递服务", "shipment_id": "123456", "client_reference": "REF789", "charge_amount": "100.00", "status": "运输中", "parcel_count": "2", "sumqty": "10", "sumprice": "500.00", "to_address": { "name": "收件人", "address_1": "地址1", "city_1": "城市", "postcode": "100000", "country": "CN" }, "from_address": { "name": "发件人", "address_1": "地址1", "city_1": "城市", "postcode": "200000", "country": "CN" }, "traces": [ { "time": 1674567890, "info": "货件已发出" }, { "time": 1674567900, "info": "货件在运输中" } ], "parcels": [ { "number": "P123", "ext_number": "EP123", "client_weight": "5.0", "client_length": "30", "client_width": "20", "client_height": "10", "carrier_code": "SF", "tracking_number": "SF1234567890", "chargeable_weight": "5.0", "actual_weight": "4.8", "chargeable_length": "30", "chargeable_width": "20", "chargeable_height": "10", "picking_time": 1674567890, "declarations": [ { "sku": "SKU123", "name_zh": "商品名称", "name_en": "Product Name", "unit_value": "50.00", "qty": "2", "material": "材质", "usage": "用途", "brand": "品牌", "size": "型号", "sale_url": "https://example.com", "weight": "1.0", "hscode": "12345678" } ] } ] } ZM物流系统数据格式 ： { "jobno": "ZM1234567890", "podInfoDTOList": [ { "scanTime": "2026-01-23 10:00:00", "remark": "货件已发出" }, { "scanTime": "2026-01-23 14:00:00", "remark": "货件在运输中" } ] } 5. 业务流程分析 5.1 货件状态管理流程 flowchart TD A[用户选择状态标签] --> B[更新筛选条件] B --> C[调用货件列表API] C --> D[后端处理请求] D --> E[查询数据库] E --> F[返回货件列表数据] F --> G[前端渲染表格] 5.2 物流信息查看流程 flowchart TD A[用户点击查看物流按钮] --> B[获取货件信息] B --> C[调用物流详情API] C --> D[后端处理请求] D --> E[调用物流系统API] E --> F[获取物流信息] F --> G[解析物流信息] G --> H[返回处理后的物流信息] H --> I[前端渲染物流信息弹窗] 5.3 异常货件处理流程 flowchart TD A[用户点击异常状态图标] --> B[打开异常处理对话框] B --> C{用户选择处理方式} C -->|忽略异常| D[调用忽略异常API] C -->|重新同步| E[调用重新同步API] D --> F[后端处理请求] E --> F F --> G[更新货件状态] G --> H[返回处理结果] H --> I[前端更新页面] 6. 技术实现亮点 6.1 前端技术亮点 Vue 3 Composition API ：使用 Vue 3 的 Composition API 进行状态管理和逻辑组织，代码结构清晰 Element Plus ：使用 Element Plus 组件库构建界面，样式统一美观 响应式设计 ：页面布局响应式，适配不同屏幕尺寸 组件化开发 ：将页面拆分为多个组件，提高代码复用性和可维护性 时间线展示 ：使用 Element Plus 的时间线组件展示物流轨迹，清晰直观 表格功能 ：使用自定义表格组件，支持排序、筛选、分页等功能 6.2 后端技术亮点 Spring Boot ：使用 Spring Boot 框架，简化后端开发 MyBatis Plus ：使用 MyBatis Plus 进行数据库操作，提高开发效率 RESTful API ：设计 RESTful API 接口，规范后端接口设计 多物流系统集成 ：支持多种物流系统的 API 集成，统一数据格式 数据缓存 ：使用缓存技术提高系统响应速度 异常处理 ：完善的异常处理机制，提高系统稳定性 6.3 系统集成亮点 多物流系统支持 ：集成了 ZH 和 ZM 等多种物流系统，统一展示物流信息 无缝切换 ：在不同物流系统间无缝切换查看物流信息 适配不同 API ：自动适配不同物流系统的 API 格式和数据结构 实时数据 ：实时获取和展示物流信息，确保数据准确性 统一界面 ：不同物流系统的信息以统一的界面展示，提高用户体验 7. 代码优化建议 7.1 前端优化建议 性能优化 ： 使用虚拟滚动技术处理大量货件数据，提高页面加载和滚动性能 实现数据缓存，减少重复 API 调用 优化组件渲染，避免不必要的重渲染 代码组织 ： 将复杂的业务逻辑拆分为更小的函数，提高代码可读性 使用 Pinia 或 Vuex 进行状态管理，简化组件间数据传递 提取重复的代码为公共函数或组件 用户体验 ： 添加更多的加载状态和操作反馈，提升用户体验 实现物流状态变更的实时通知 优化表单验证和错误提示 7.2 后端优化建议 性能优化 ： 使用缓存机制缓存频繁查询的物流信息，提高系统响应速度 优化数据库查询，使用索引提高查询效率 实现异步处理，提高系统并发能力 代码组织 ： 优化代码结构，提高代码可读性和可维护性 使用设计模式，如策略模式处理不同物流系统的 API 调用 提取重复的代码为公共服务或工具类 系统稳定性 ： 增强错误处理，提供更详细的错误信息 实现熔断机制，避免物流系统 API 故障影响整个系统 添加日志记录，便于问题排查 7.3 架构优化建议 微服务架构 ： 考虑将物流服务拆分为独立的微服务，提高系统的可扩展性和可维护性 使用服务发现和负载均衡，提高系统的可靠性 API 网关 ： 引入 API 网关，统一管理和保护后端 API 实现请求限流和熔断，提高系统的稳定性 数据存储 ： 考虑使用 NoSQL 数据库存储物流轨迹等半结构化数据 实现数据分片，提高数据库的处理能力 8. 功能扩展建议 8.1 功能扩展 移动端支持 ： 开发移动端应用或响应式网页，支持在手机上查看物流信息 实现物流状态变更的推送通知 更多物流系统集成 ： 集成更多的物流系统，如 FedEx、UPS、DHL 等 提供物流系统 API 配置的可视化界面 数据分析功能 ： 实现物流数据的统计和分析，如运输时间、异常率等 提供数据可视化图表，帮助用户分析物流性能 智能预警 ： 基于历史数据和规则，实现物流异常的智能预警 提供预警通知和处理建议 多语言支持 ： 实现多语言界面，支持国际化业务需求 支持不同国家和地区的物流规则和格式 8.2 技术扩展 使用 WebSocket ： 实现实时物流状态更新，无需手动刷新页面 提供更及时的物流轨迹变更通知 使用 AI 技术 ： 利用 AI 技术分析物流数据，预测可能的延误和异常 提供智能的物流路径优化建议 区块链技术 ： 考虑使用区块链技术存储物流信息，提高数据的安全性和可追溯性 实现物流过程的透明化和不可篡改 9. 总结 货件跟踪模块是 Wimoor 系统中一个功能完善、技术先进的模块，通过前后端的紧密配合，为用户提供了全面、实时的货件跟踪服务。该模块具有以下特点： 功能全面 ：支持货件状态管理、物流信息查看、物流轨迹跟踪、多物流系统集成等功能 技术先进 ：采用 Vue 3 + Element Plus 前端技术和 Java + Spring Boot 后端技术 用户友好 ：界面设计简洁直观，操作流程优化，物流信息展示清晰 系统稳定 ：完善的错误处理和异常管理机制，确保系统稳定运行 扩展性强 ：模块化设计，易于功能扩展和技术升级 通过不断优化和升级，货件跟踪模块将为用户提供更优质的 FBA 货件管理体验，帮助用户更高效地管理和跟踪货件的整个生命周期。