企业官网建设流程全解析

电商小程序做到订单履约这一步，很多团队才发现最麻烦的不是支付，不是商品展示，而是"怎么把货发出去还不发错"。用户下单后，商家得搞清楚哪个订单该发什么、分几个包裹、用哪家快递、单号是多少。这些信息如果还要靠人肉复制粘贴，效率低不说，错发漏发的问题一定会找上门。微信小程序发货信息录入这个功能，解决的就是这件"小事"：让仓库人员拿着手机，扫一下面单，选一下物流公司，录入就算完成，订单状态自动流转，买家端也能第一时间看到物流单号。

这篇内容我不会只贴一段示例代码，而是把实际开发这个功能时踩过的坑、想清楚的逻辑完整梳理一遍：字段怎么设计、拆单合并怎么处理、前端怎么扫码、后端 Java 接口怎么保证不重复发货，以及真机调试时遇到的基础库版本、顶部导航栏高度、附件保存路径、抓包验证这些问题。适合正在做电商类小程序、需要实现商家或仓库端发货功能的开发者，也适合刚入小程序开发、想看看一个完整业务功能是怎么从页面到接口串起来的新手。

1. 发货信息录入的业务本质：先理清"承上启下"再动手

1.1 发货环节的真实痛点

发货信息录入这个功能听起来很简单——不就是填个快递单号吗？但放到真实业务里就完全不是这么回事。我接手过好几个电商类项目，最典型的问题有三个。

第一个是录入分散。订单在商城小程序里，发货单在快递系统里，操作记录在 Excel 里，信息不在一个地方，仓库和客服对账全靠吼。第二个是拆单状态混乱。一个订单买了两件商品，分两个仓库发；或者三件商品合成一个包裹发，订单状态到底是"已发货"还是"部分发货"，很多团队根本没想清楚。第三个是错发漏发追责难。发错了，不知道是哪个环节的问题；漏发了，也不知道是谁漏的。

做一个发货信息录入功能，如果能顺手把这三个问题都解决掉，这个功能的价值就不只是"录单"了，它其实是订单履约流程里最关键的"确认动作"：系统通过一次录入，把"订单待发货"变成"订单已发货并附上物流信息"，同时把操作人、发货时间、包裹明细都记录下来。这个语义很重要，后面设计的很多接口和状态流转，都是围绕它展开的。

1.2 功能边界与角色划分

在做需求分析时，我习惯先画一条边界：发货信息录入功能，只管"从订单产生到包裹交付给物流公司"这一段，再往后的物流轨迹查询、买家通知、售后拦截，都属于其他模块。功能边界清楚了，接口设计才不会什么都往这个模块里塞，不然一个简单的录入功能会被各种奇怪的业务需求拖垮。

角色上，至少要考虑三种：

• 商家或店主：能看全部订单，能录入，也能改。
• 仓库操作员：能录发货信息，但不能改商品价格、不能退款。
• 管理员：能查看操作日志，能处理异常发货。

权限设计不当，后面上线了才发现仓库人员能把订单改成已退款，那就麻烦了。小程序端的身份识别走wx.login拿 code，再到后端换 token，这一步很基础但很重要。code 是一次性的，后端拿到后调用微信接口换取 openid 和 session_key，再自己签发业务 token，后续请求都带这个 token 做鉴权。很多新手直接把 openid 放在请求参数里来回传，这个习惯不好，等于把用户身份证号贴脑门上走路。

数据流是这样的：小程序录入页发起请求，后端校验参数和权限，在一个事务里写入发货单、更新订单状态，然后返回结果；小程序刷新订单列表，买家端立刻能看到物流单号。这个链路里，发货单是承上启下的核心表，接下来就细说这张表怎么设计。

2. 字段与页面设计：拆单、合并、多包裹时怎么录

2.1 数据模型：发货单和订单是"多对一"还是"一对多"

我建议用两张表：shipment（发货单主表）和 shipment_item（发货明细表），不要试图把所有东西塞进一张大表。

主表的字段设计，我根据自己的踩坑经验整理如下：

• shipment_no：发货单号，业务编号，仓库那边习惯用这个对账。
• order_id / order_no：关联的原订单。
• express_company：物流公司编码。这里注意存编码不存中文名，比如存 ZTO，不存"中通快递"。否则哪天物流公司改个名，或者你想接入新的快递渠道，就要改一堆历史数据。
• express_no：物流单号。
• package_count：包裹数量。
• receiver_name / receiver_phone / receiver_address：冗余的收货人信息。订单收货地址可能会变，但发货这一刻的信息需要快照下来，后面打单、对账、客服排查都用得到。
• status：发货单状态（1-已创建、2-已发货、3-已签收）。
• operator_id / operator_name：操作人。
• remark：备注。
• shipped_at：发货时间。

明细表字段相对简单：shipment_id、order_item_id、sku_id、product_name、quantity。这里的设计细节是：明细表里存的是商品快照，而不是直接实时去查订单明细。为什么要快照？因为订单可能改价、可能部分退款，发货单作为履约凭证，必须保留发货那一刻的商品信息。这个道理就像财务为什么要留底单一样，不是随便拍拍脑袋定的。

2.2 拆单、合并发货的交互设计

拆单，就是一个订单拆成多个 shipment，比如一个订单买了五件衣服，分两个仓库发货。合并发货，就是多个订单合成一个 shipment，比如同一个买家连续拍了两单，仓库打包成一个包裹发走。页面交互上，我建议这样设计：

订单列表页展示待发货订单，卡片上显示订单号、商品缩略图列表、数量和收货人。点击"去发货"进入录入页。录入页顶部是待发货商品明细，支持勾选和取消勾选。勾选商品后，点击"添加到当前包裹"，一个包裹就对应一个 shipment。继续勾选剩余商品，点击"新建包裹"，这样就形成了拆单效果。包裹列表下方是物流信息填写区：物流公司加物流单号，可扫码可手动。

合并发货更简单，在订单列表页勾选多个订单，统一录入同一个物流公司加单号，后端按订单逐个生成 shipment 记录。这个方案在真实场景里验证过，仓库操作员不需要培训太久，看一遍界面就能上手。

2.3 录入效率优化：不是每个字段都需要手填

移动端录入的体验至关重要。仓库人员一天要录几十上百单，每次都要手输物流公司再输入一长串单号，这个体验会让他们直接放弃小程序，回到 Excel 老路上去。我做了三个优化，实测下来效率提升非常明显。

第一个是记住上次选择。把最近一次使用的物流公司存在本地 storage 里，下次进入页面默认选中。这个功能很简单，但能省掉百分之八十的点选操作。第二个是扫码直接带出快递公司。快递面单上的条码内容虽然各家不完全一样，但很多包含物流公司编码信息，扫完可以自动帮你选好公司，只需要确认。第三个是批量粘贴。支持一次粘贴多行"物流公司 空格 单号"的文本，自动拆分成多个包裹，专门给手里已经有一张表格要批量录入的场景用。

这些优化单独看都是小功能，但组合起来，仓库操作员的操作时间能从一分钟一单降到十几秒一单。千万别小看这几十秒，录单员一天几百单下来，省下的时间是实打实的人力成本。

3. 前端核心实现：扫码、物流公司选择与单号校验

3.1 用 wx.scanCode 把面单条码扫进去

小程序端最重要的交互就是扫描快递面单。wx.scanCode这个接口用起来很简单，但有两个细节要注意：一是扫出来的内容不一定是纯单号，可能是网址或者混合编码，需要二次解析；二是扫码前要申请相机权限，用户拒绝后要有引导，不能让用户卡在那里不知道怎么办。

下面是我在发货录入页里的扫码实现，加了字段清洗和权限处理的逻辑：

wx.scanCode({ scanType: ['barCode', 'qrCode'], success: (res) => { const result = res.result || ''; // 部分面单条码是纯数字，部分带字母前缀，这里做一次清洗 const expressNo = result.replace(/[^0-9A-Za-z]/g, '').slice(-20); this.setData({ 'form.expressNo': expressNo }); this.autoDetectCompany(expressNo); }, fail: (err) => { if (err.errMsg && err.errMsg.indexOf('auth deny') > -1) { wx.showModal({ title: '提示', content: '需要相机权限才能扫描快递单号，请在设置中开启', confirmText: '去设置', success: (r) => { if (r.confirm) { wx.openSetting(); } } }); } } });

这里有个经验：不要拿到扫码结果就直接填进表单。面单上的内容常常混了其他信息，我会先做一次清洗，去掉杂字符，再截取最后一段纯数字和字母组合。如果还要更稳，可以加一个"智能识别"逻辑，根据单号前缀自动匹配物流公司，这样用户连下拉框都不用点了。

3.2 物流公司选择器：picker 还是 radio

物流公司数量通常有几十家，全放 radio 单选框会很难看，滚动列表也长。我的建议是默认用 picker 组件，展示常用几家，点击后弹出完整列表。如果你只有三四家固定物流，比如一个校园跑腿平台只和两家快递合作，那用 radio 确实更直观，点一下就切换，不用多一次弹窗确认。热搜词里有人在问"微信小程序单选框"，其实就是这个选择问题。超过五家物流，直接上 picker，别犹豫。

实现逻辑上，核心是公司编码和显示名的映射，以及按单号前缀自动推断公司：

// 物流公司数据源，建议放后端接口下发，前端只保留一份缓存 const companyList = [ { code: 'SF', name: '顺丰速运' }, { code: 'ZTO', name: '中通快递' }, { code: 'YTO', name: '圆通速递' }, { code: 'YUNDA', name: '韵达快递' }, { code: 'JD', name: '京东物流' } ]; // 根据单号前缀推断物流公司 function autoDetectCompany(expressNo) { const prefixRules = [ { code: 'SF', test: /^SF/i }, { code: 'JD', test: /^JD/i }, { code: 'ZTO', test: /^7[0-9]{10,}$/ } ]; const matched = prefixRules.find(r => r.test.test(expressNo)); if (matched) { this.setData({ 'form.expressCompany': matched.code }); } }

优先用编码存储，前端再映射成展示名，这是防止后端数据被 UI 绑架的基本原则。后端接口收的是 ZTO，而不是"中通快递"，这样即使前端把"中通"改成"中通快运"，后端代码也不用动。

3.3 单号校验规则：不同快递公司不一样

单号校验不能一刀切。顺丰常见 15 位数字，中通、圆通多为 12 位或 13 位，京东的单号带 JD 前缀。前端可以做一个快速提示，但真正的校验必须放在后端，因为绕过前端直接调接口太容易了。

不同快递公司的常见单号格式参考：

前端校验函数示例：

function validateExpressNo(companyCode, expressNo) { const rules = { SF: /^\d{15}$/, ZTO: /^\d{12}$|^\d{13}$/, YTO: /^\d{12}$|^\d{13}$/, JD: /^JD\d{15,20}$/i, YUNDA: /^\d{13}$/ }; const rule = rules[companyCode]; if (!rule) return true; // 未知公司不强制拦截 return rule.test(expressNo.trim()); }

实际项目里这些规则会随着快递公司调整而变，所以我把规则表放到了后端配置里，前端通过接口拉取，这样改规则不用发版。这个思路在发货信息录入这种低频但准确性要求高的功能上很实用。

3.4 发货凭证图片：chooseMedia 与本地暂存

有些业务要求上传发货凭证，比如打包照片、面单照片。微信小程序里用wx.chooseMedia选图片，这个接口会返回临时文件路径，注意真机上要处理好临时文件路径和持久化存储路径的差异。这里有一个很经典的坑：用wx.env.USER_DATA_PATH做本地存储目录时，开发工具和真机的文件系统路径完全不一样，千万不要在代码里硬编码绝对路径。

下面是用 USER_DATA_PATH 暂存附件的写法：

const filePath = `${wx.env.USER_DATA_PATH}/shipment_${Date.now()}.jpg`; wx.getFileSystemManager().copyFile({ srcPath: tempFilePath, destPath: filePath, success: () => console.log('附件已存到本地目录', filePath), fail: (err) => console.error('附件保存失败', err) });

这里要重点提醒一点：临时文件在退出小程序后可能被清理，如果凭证需要留存，最稳妥的上传时机是用户点"提交发货"那一刻，直接把图片上传到云存储或后端对象存储，服务端只存 URL。本地路径只是暂存，不是存档。热搜词里有人问保存附件相关的用法，大概率就是在这个边界上踩了坑。

3.5 提交状态与防重复提交

录入页面点"提交"后，一定要加 loading 状态，按钮置灰，防止用户连续点两下造成重复发货。前端只能防手滑，真正的幂等保障在后端，这个放到后面详细说。但前端的 loading 和禁用按钮也绝不能省，它是用户体验的第一道防线，也是后端幂等设计兜底前的最后一道友好提示。

提交成功后的页面反馈也要设计好。发货成功后，建议直接清空当前页面表单，并显示"发货成功"的 Toast，然后延迟回到订单列表页并刷新。不要让用户手动返回再手动下拉刷新，多一步操作就多一分"这个系统好不好用"的差评。

4. 后端接口与状态流转：Java 侧怎么承接发货提交

4.1 接口设计

后端我用 Spring Boot 实现，平时直接在 IDEA 里启动服务，小程序端用微信开发者工具打开，两边同步调试，效率很高。核心接口就一个：POST /api/shipment。

请求体设计如下：

{ "orderNo": "SO202501010001", "packages": [ { "expressCompany": "ZTO", "expressNo": "773012345678901", "itemIds": [1001, 1002], "remark": "易碎品请轻放" } ], "operatorId": "u_10086" }

响应体：

{ "code": 0, "message": "success", "data": { "shipmentNo": "SH202501010003", "status": "SHIPPED" } }

为什么请求体里带的是 packages 数组而不是单个 expressNo？因为要支持拆单场景，一次提交就能处理多个包裹，减少网络请求次数，也能在同一个事务里同时完成，避免"第一个包裹提交成功、第二个失败"的数据不一致。这个设计是从真实业务教训里得来的，最开始版本只支持单个包裹，上线没两周就被仓库反馈拆单场景用不了，加班改了一版才稳定下来。

4.2 参数校验与幂等处理

参数校验用@Valid加自定义注解，不能只靠前端。特别是 expressNo 校验规则，后端必须有同样一份，否则用户绕过小程序直接调接口，脏数据就进库了。

一个简化版的参数模型：

@Data public class PackageRequest { @NotBlank(message = "物流公司不能为空") private String expressCompany; @NotBlank(message = "物流单号不能为空") @Pattern(regexp = "^[A-Za-z0-9]{10,32}$", message = "物流单号格式不正确") private String expressNo; @NotEmpty(message = "商品明细不能为空") private List<Long> itemIds; private String remark; }

幂等处理是发货功能最容易出问题的地方，这里必须展开讲。我遇到过一次真实事故：仓库网络卡顿，操作员点了三次提交，结果生成了三张发货单，库存和订单状态全乱了，客服花了一下午才把多发的货追回来。从那以后我定下两条硬规矩：

1. 业务幂等键。前端进入录入页时向后端申请一个 shipmentRequestId（UUID），提交时带上。后端在 shipment 表上给(order_no, shipment_request_id)建唯一索引，重复插入直接报错被拦下。
2. 订单状态前置校验。事务内先SELECT ... FOR UPDATE把订单行锁住，判断当前状态必须是"待发货"，否则抛异常回滚。

核心代码逻辑：

@Transactional public Shipment createShipment(ShipmentCreateRequest req) { // 幂等检查 if (shipmentMapper.existsByRequestId(req.getOrderNo(), req.getShipmentRequestId())) { throw new BusinessException("重复的提交请求"); } // 锁订单行，防止并发发货 Order order = orderMapper.selectByNoForUpdate(req.getOrderNo()); if (order == null || order.getStatus() != OrderStatus.UNSHIPPED) { throw new BusinessException("订单不存在或当前状态不可发货"); } // 插入发货单与明细 Shipment shipment = buildShipment(req, order); shipmentMapper.insert(shipment); // 更新订单状态 orderMapper.updateStatus(order.getId(), OrderStatus.SHIPPED); // 记录操作日志 operationLogMapper.insert(buildLog(req, shipment)); return shipment; }

事务边界很重要：插入发货单、更新订单状态、记录操作日志，必须放在同一个事务里，任何一个失败都要回滚，否则就会出现"发货单有了但订单还在待发货"的状态错乱。这种错乱是最难排查的，因为它不报错，只是数据对不上，往往要等买家投诉没有收到发货通知才会被发现。

4.3 状态机与异常处理：发货不是终态

订单状态机建议明确四个状态：待发货、已发货、已签收、已取消。发货接口只允许"待发货到已发货"这一条路径，其他路径全部拒绝。状态控制的权限说明可以用一个表来表达：

有些系统在发货后允许"改物流单号"，比如仓管手误把单号输错了，这个操作属于特殊权限，不要放在普通发货接口里，单独出一个修改接口，并且必须记录修改人。字段 audit 日志不能省，等真正出问题的时候，能靠这个日志定位到人。

这里再说一个很多人忽略的点：发货不是结束，而是物流的开始。如果系统接入了物流查询服务，发货成功后应该触发一个异步事件，去物流平台订阅轨迹更新，再通过模板消息或订阅消息通知买家。这个事件如果和发货事务放在一起同步执行，可能会拖慢发货接口的响应，所以我用消息队列解耦。前端用户感知不到这个异步过程，但查询物流轨迹的体验会差很多，属于典型的基础体验优化。

5. 真机调试与上线前必须处理的坑

功能开发完，在开发者工具里看没问题，一上真机就翻车，这是小程序开发的常态。这一章我把发货信息录入功能最容易在真机上翻车的几个点集中列出来。

5.1 顶部导航栏高度：自定义导航的适配

如果你觉得默认导航栏太丑，想做一个自定义顶部导航，麻烦就来了。微信小程序的导航栏高度不是固定的，带刘海的 iPhone 和安卓机完全不同，右上角胶囊按钮的位置也不同。很多人在热搜词里搜"微信小程序顶部导航栏高度"，其实就是被这个适配问题卡住了。

正确的做法是用wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的定位，再反推状态栏高度和导航栏高度：

const systemInfo = wx.getWindowInfo(); const menuButton = wx.getMenuButtonBoundingClientRect(); // 胶囊按钮顶部到屏幕顶部的距离 const statusBarHeight = systemInfo.statusBarHeight; const navBarHeight = (menuButton.top - statusBarHeight) * 2 + menuButton.height;

这个值在页面初始化时算一次，存到全局变量或 storage 里，后面所有自定义导航页面复用。如果录入页顶部要放标题、返回按钮、提交按钮，自定义导航栏总高度就是statusBarHeight + navBarHeight，内容区域要往下避开这个高度。不同机型的差异测试覆盖是必须做的，至少安卓和 iOS 各测一台。

5.2 基础库版本设置：很多人找错地方

关于"微信小程序基础库版本从哪设置"这个问题，我看到过不少新手找错地方。开发者工具的右上角"详情-本地设置"里可以切换调试基础库版本，这是开发调试用的。但小程序真正允许用户运行的最低基础库版本，是在微信公众平台管理后台配置的，路径是"设置-服务内容声明-基础库版本"。

代码层面，更重要的不是设置版本，而是做兼容判断。比如wx.getWindowInfo()是较新的 API，基础库版本低的老手机会调用失败，要兼容就得用老的wx.getSystemInfoSync()，或者先通过wx.canIUse('getWindowInfo')判断。发货录入页如果用了新 API 又不做兼容，老手机上页面直接白屏或功能不可用，这是上线后最容易收到投诉的问题。

如果你是拿 uniapp 打包成微信小程序，基础库版本的设置逻辑稍有不同。uniapp 项目的 manifest.json 里有基础配置，编译生成的小程序项目会自动处理一部分兼容，但wx.getMenuButtonBoundingClientRect这类原生 API 的调用方式还是一样的，条件编译要做好。

5.3 附件保存路径：wx.env.USER_DATA_PATH 的玄机

我在前面已经提到了wx.env.USER_DATA_PATH，这里再展开讲一下。开发工具里打印这个变量，会得到一个本机绝对路径，看起来很正常。到了真机上，这个路径是沙盒目录，你在电脑上根本找不到这个目录，想验证文件是否保存成功，必须通过wx.getFileSystemManager().readdir()去读取。

而且注意，小程序的本地文件存储是有上限的，如果发货凭证照片很多，保存到本地肯定不够用，最终还是得传给后端。我的习惯是本地只做缓存，云端才是持久化。录入页把图片先放本地临时目录，点提交时再上传到对象存储，成功后把 URL 放进接口请求体。这样既保证用户下次打开还能看到待提交的凭证，又不会让本地存储吃紧。

5.4 抓包验证发货请求

发货这个动作涉及资金和订单，上线前必须抓包检查一遍，确认前端发出的字段名称、格式、签名都与后端一致。我一般用 Charles 做 HTTPS 抓包，需要在小程序真机上打开调试模式，并安装 Charles 的根证书。有几个坑很常见：手机代理设置不正确、手机和电脑不在同一个网段、小程序请求走了微信内部代理导致 Charles 抓不到包。

抓包重点看三样东西：

• 请求 URL 和 HTTP method 是否正确。
• 请求体里 orderNo 与 packages 是否完整、字段名有没有拼错、中文有没有乱码。
• 响应 code 是否为 0，以及重复提交同一份请求时，是否真的被幂等逻辑拦下。

一次完整的"提交发货"抓包，能帮你拦截掉至少百分之五十的联调问题。不要等到上线了才发现接口字段对不上，那时候再排查，影响的就是真实订单了。

5.5 开发工具里的 handshake failed 报错

很多人用开发者工具连接本地后端调试时，会看到一行报错：handshake failed due to invalid upgrade header: null。这个错误我遇到过好多次，原因通常是开发工具在发起 WebSocket 升级请求时，本地代理或服务端返回的头信息不规范，或者域名校验未通过。

解决思路按顺序排查：

• 如果用的本地 HTTP 服务，确认开发者工具"详情-本地设置"里勾选了"不校验合法域名…"。
• 如果项目里接入了 WebSocket 或实时推送，检查服务端的升级响应头是否为Connection: Upgrade和Upgrade: websocket。
• 这个错误大概率只在开发工具里出现，真机上反而不容易遇到，不用过度恐慌。但要确认线上请求用的都是 HTTPS 加已备案域名，开发工具和真机的差异在这个点上尤其明显。

5.6 一点性能优化：lazyCodeLoading

如果发货录入页面只在商家端使用，而且小程序分包后首包体积偏大，可以在 app.json 里开启"lazyCodeLoading": "requiredComponents"，让页面按需注入组件代码。这个配置对录入页这种打开频率不高的功能页效果明显，能减少商家端首页的加载时间。

不过开启时要回归一下其他页面有没有使用未注册的组件，避免上线后某个页面白屏。lazyCodeLoading 的坑在于它不是"开启就完事"，组件注册表必须准确，否则组件会在某个不起眼的交互中被用到时才报错，排查起来比较费劲。如果项目比较老，组件管理模式混乱，我建议先做一次全量组件引用检查再开这个配置。

真机调试这一圈走下来，发货录入页基本就稳了。实践经验告诉我，小程序功能开发最大的敌人不是逻辑复杂度，而是各种环境差异——开发工具和真机不同、安卓和 iOS 不同、老基础库和新基础库不同。这些差异如果不能在上线前充分覆盖，光靠测试用例是发现不全的，真机真跑一遍才是硬道理。