企业官网建设流程全解析

FastAdmin Shopro 这套组合在二开圈子里的地位不用多说了，一个是 PHP 后台快速开发框架，一个是基于 uni-app 的跨端商城解决方案。两者搭起来，小程序、H5、App 都能跑，后台用 FastAdmin 那一套成熟的管理体系撑着，确实能省掉不少从零造轮子的时间。

但这套组合有个很有意思的现象：官方 Demo 跑起来很顺，分销功能也像模像样，可真到了客户面前，需求一细化，问题就全冒出来了。我记得很清楚，有个做社区团购的客户，上来就问我三个问题：我的分销员要分区域管理，佣金能不能按小区算？A 推了 B，B 又推了 C，C 成交之后佣金到账到底要卡几天？客户退款了佣金怎么往回扣？这三个问题，官方默认的分销逻辑一个都答不全。

所以这篇就专门聊聊 Shopro 分销这块的深度定制实践，不是照着文档念，是把我在实际项目中改过的关系绑定、佣金结算、前端分销中心这些核心链路拆开讲清楚，顺便把踩过的坑也一并说了。

1. 先弄明白：Shopro 自带的分销逻辑到底能做到什么程度

很多朋友拿到 Shopro 第一件事就是去后台开启分销，看到分销等级、佣金比例、提现设置这些选项卡就觉得功能挺全。确实，FastAdmin 后台集成的分销设置界面该有的字段都有，但你要真把它当一个完整的社交电商分销系统来用，差距还是不小。

1.1 看默认的三层分销与佣金计算模型

Shopro 默认的分销模型是经典的三级分销，也就是分销员 A 推荐 B，B 推荐 C，C 产生消费后，A、B 都能获得佣金，层级最多到三级。后台可以分别设置一级、二级、三级佣金比例，比例是按订单商品的实际支付金额来计算的，默认不包含运费。

这个模型的优点是清晰，数据表结构也简单，shopro_user表里加个parent_id字段就能把关系链串起来。实际跑起来你会发现，它的佣金计算是走回调的：订单支付成功触发一次计算，确认收货又触发一次，每次都会去查关系链上一路往上的分销员。

但这里有个天然的限制——它只认"下单用户"这个节点往上追，追到的每个层级按商品设置或者默认比例算佣金。如果你需要按不同商品分类设置不同比例，或者某些商品不分佣、某些商品双倍返佣，默认逻辑是做不到的，得自己在商品表或者结算逻辑上动手脚。

1.2 分销关系绑定的三个关键时刻

除了佣金计算，更多人忽略的是绑定关系本身的触发时机。Shopro 默认的分销关系绑定发生在用户进入小程序或 H5时，只要 URL 或小程序码带了分销员推广标识，系统就尝试建立上下级关系。

这个机制存在几个现实问题：

• 如果用户只是随便点开看看，并没有注册，那么关系在注册时建立，还是进入时建立？Shopro 的处理是进入时建立临时关系，注册后再正式落地。
• 用户 A 先通过普通链接进入，后又通过分销员 B 的链接进入，关系被谁覆盖？
• 用户本身就是分销员，自己扫自己的推广码，系统会不会允许这种自推自买？

这些场景官方没有完整覆盖，实际运营中又一定会遇到。所以深度定制第一刀，多半要先砍在关系绑定上。

2. 第一刀：分销关系绑定链路的定制改造

关系绑定是所有分销业务的地基，地基要是歪了，后面佣金算得再准也没用。我改造 Shopro 分销时，通常第一步就是把绑定逻辑从"被动依赖回调"改成"可控的主动落位"。

2.1 关系绑定时机怎么选

在做定制前，要先明确业务想要什么样的绑定节奏。业界大致有三种方案：

实际操作中我推荐注册后绑定为主，配合"首次进入记录推广来源"做兜底。也就是说用户带着推广码进入时先把推广人记到临时字段或缓存里，等注册成功后再真正写入parent_id。这样既不会丢关系，也不会搞出大量垃圾绑定数据。

2.2 改造推广码解析与带参进入逻辑

Shopro 前端是 uni-app，小程序端通过scene参数带推广人 ID，H5 端通过 URL 参数带。默认代码里这块是写死的，定制的时候我一般会单独抽一个share-helper.js，统一处理不同端的推广参数解析。

// uni-app 端统一处理推广参数 export function getPromoterFromShare() { // #ifdef MP-WEIXIN const scene = decodeURIComponent(options.scene || '') const promoterId = parseSceneToPromoter(scene) // #endif // #ifdef H5 const query = getCurrentPages()[0].options || {} const promoterId = query.pid || query.promoter || '' // #endif return promoterId }

核心思路是把"从哪来"这个信息标准化成一个promoter_id，然后交给后端接口统一处理。这里特别要注意，解析参数时一定要做防注入处理，不能直接拿参数拼 SQL 或者直接写关联关系。我在项目里见过有人直接把pid参数塞进接口就建立关系，结果被人刷了一堆假上级，惨烈。

处理逻辑上建议写成独立的接口，例如user/share/bind，内部完成这些动作：

1. 校验推广人ID是否真实存在且是分销员身份
2. 检查当前用户是否已绑定关系，已绑定则返回当前关系，不覆盖
3. 检查是否自推（推广人ID等于当前用户ID），自推则忽略
4. 写入关系前用事务锁防止并发覆盖
5. 写完后给推广人推送一条绑定成功通知

2.3 防自推、防覆盖、防并发三个坑

这三个坑是实际运营中最容易炸的。

防自推：很多人觉得自推不可能，但实际操作中用户自己点自己分享出来的链接太常见了。如果不拦截，用户就能自己当自己的上级，佣金逻辑直接乱套。判断时机要放在接口层，不要放在前端。

防覆盖：默认逻辑下，用户先通过 A 的链接进来，后又点了 B 的链接，理论上关系可能被 B 覆盖，造成 A 的推广流失。我一般写成"首次绑定永久生效"，除非主动解绑，否则后续任何带参进入都不再覆盖关系。

防并发：用户首次注册那一刻系统可能同时接到来自不同渠道的调用，如果不同步处理，会产生两条绑定记录。解决办法是用parent_id作为唯一索引，或者在写入前用数据库行锁锁定用户记录。FastAdmin 这边我用的是 ThinkPHP 的lock方法配合事务。

3. 第二刀：佣金结算逻辑的深度改造

关系链理顺之后，重头戏就在佣金结算。默认的佣金计算是"订单金额 x 比例"，听着简单，放到多商品、多分类、多等级的场景下就完全不够用了。

3.1 按分类与商品双重维度配置佣金

真实商城一定会有"有些商品利润高可以多分佣，有些单品本身就不赚钱不能分佣"的需求。默认功能只能全局设置比例，所以我改造的思路是在商品表加两个字段：is_commission（是否参与分佣）和commission_ratio（自定义比例，为空则走全局或分类设置）。

同时在商品分类表上加commission_ratio字段，做成三级兜底逻辑：

商品自定义比例 > 商品分类比例 > 平台全局比例

结算的时候先取商品自己的设置，没有就往上找分类，分类也没有再落回全局默认。这个逻辑要在后台的结算服务里统一封装，不能在多个地方各写一套判断，不然后面维护起来想哭。

3.2 佣金计算与冻结期、退款回滚的联动

Shopro 默认佣金在订单支付成功时计算，确认收货后到账可提现。真实业务里还会有冻结期的需求，比如晒单返佣、7天无理由退货期过了才释放。这里就要把佣金状态做成多阶段：

待结算（已计算未确认收货） → 冻结中（已确认收货，未过冻结期） → 可提现（冻结期结束真正可用） → 已失效（订单全额退款或风控判定刷单）

状态迁移的核心触发点有两个：一是确认收货事件，二是冻结期到期事件。冻结期可以用定时任务扫表实现，FastAdmin 后台有现成的定时任务插件，跑一个每分钟执行的小脚本就行。

退款场景是另一个大坑。订单部分退款要不要扣佣金？扣多少？默认逻辑是"全额退款退全额佣金"，但实际经常遇到用户买三件退一件的情况。我改造时会在退款单里记录退款的商品明细，按比例回算涉及的佣金行，然后扣回对应部分的佣金。这里必须注意：佣金扣回时不能直接删记录，而是要新增一条负数调整记录，保留完整的佣金流水，方便财务对账，也让分销员看到明细时心服口服。

3.3 团队绩效佣金要不要做

很多分销需求会提到"团队业绩"，比如一级分销员拿直推佣金，还能拿整个下级团队的销售额提成。这块默认功能是完全没有的。

我的建议是，如果需求只是"团队总销售额展示"，那就不要动佣金表，只看关联订单做统计查询即可。如果真的要按团队业绩结算佣金，那要单独建一张agent_team_commission表，按周期（月/周）跑批汇总，计算规则要尽量避免实时算——实时算团队级佣金在订单量上来后性能会很差。

我做过的项目里，团队佣金都是在每日凌晨的批处理脚本里统一计算，计算完生成待确认记录，后台人工审核后再入账。这样做既保证了扩展性，也避免实时计算带来的性能抖动。

4. 第三刀：uni-app 前端分销模块的定制

后端逻辑改了，前端分销中心也得跟着动。Shopro 的 uni-app 端默认自带分销中心页面，有累计佣金、可提现佣金、提现记录、推广海报这些模块，但默认界面和交互一般很难直接满足运营需求，尤其是海报生成和分享回流这两块，值得花心思重写。

4.1 分销中心数据聚合接口定制

分销中心页面通常要展示这些数据：累计收益、本月收益、可提现余额、团队人数、团队业绩、订单数。如果前端直接查多张表，网络请求会很碎。

我习惯把数据聚合放到后端做一个agent/center接口，一次性返回分销中心所有需要的统计字段。用 FastAdmin 的话就是在控制器里组装数据，注意统计查询要加 Redis 缓存，比如累计收益这类变化不频繁的数据可以缓存 60 秒，省得每次进入页面都跑全表聚合。

另外要注意金额字段的精度处理。PHP 端浮点数运算容易丢精度，金额一律转成分（int）来加减乘除，响应给前端时再转回元保留两位小数。我在项目里专门写了一个MoneyService，统一封装金额转换，禁止在业务代码里直接round或者floatval。

4.2 海报生成：canvas 绘制与推广码定位

分销海报是分销员拉新最核心的素材。Shopro 默认有海报功能，但样式固定，很多定制需求要改背景图、改推广文案、改二维码位置。

uni-app 端实现海报生成有两种主流方案：

• 方案一：前端 canvas 绘制，将商品图 + 背景图 + 文案 + 小程序码画成一张图，再保存到相册。
• 方案二：后端生成海报图片，前端只拉取图片链接渲染。

前端 canvas 的坑在于不同端 API 不统一——小程序用uni.createCanvasContext，App 端可能用plus原生能力，H5 端又不一样。为了兼容，我通常只做微信小程序端的 canvas 海报，H5 端直接用后端生成图替代。

用户授权保存图片到相册时，记得处理多次拒绝授权的情况，否则体验很差。我的做法是第一次拒绝后弹窗说明去设置页开启，不反复调用原生授权。

4.3 分享回流与参数传递的闭环

前端分享动作有三类：小程序转发给好友、生成海报扫码进入、H5 链接分享到朋友圈或群聊。每种入口都要能正确带上推广参数。

小程序转发实现时，onShareAppMessage里把path参数拼上推广人 ID 即可，注意拼在scene里而不是直接?pid=，因为微信小程序扫码进入时通常只能获取到scene字段。

onShareAppMessage(res) { return { title: '邀请你一起买好物', path: `/pages/index/index?scene=${encodeURIComponent('pid=' + this.promoterId)}`, imageUrl: shareImage } }

H5 端就简单些，分享链接拼上?pid=xxx，落地页读取后调后端绑定接口。

这里最容易被忽略的是分享链路埋点。我之前做过一个项目，分销推广上线两周后运营完全不知道哪条渠道带来了多少用户、转化率多少，就是因为前端分享只传了pid没传渠道来源。后来我加了个source字段（枚举值：wechat_friend、wechat_timeline、poster_scan、h5_share），在绑定关系时一并保存，后台报表才真正有了分析价值。

5. 二次开发避坑实录：这些细节能救你一命

最后聊聊实战中踩过的那些坑。有些问题排查起来非常隐蔽，网上资料又少，这里集中把典型问题列出来。

5.1 佣金计算精度与浮点数问题

PHP 的float类型在算钱上就是灾难。比如0.1 + 0.2在浮点数运算里并不等于0.3，商城订单金额一旦涉及多商品、多折扣、多级比例，浮点数累加出来的误差会在对账时暴露。

我的强制方案是整个项目禁止用浮点数直接做金额运算，所有金额字段以"分"为单位存整数。如果第三方支付返回的是元，就统一bcmul($amount, 100, 0)转分，算完再转回元。这一点务必写进项目规范里，不然换个人接手随手一改就是事故。

5.2 定时任务与队列消费的配置

Shopro 里像佣金到期解冻、订单超时关闭这类逻辑依赖定时任务。FastAdmin 后台自带定时任务管理，但很多人配完发现不生效，主要原因是任务脚本的crontab配置或调用路径不对。

我自己常用的方法是：写一个统一的 CLI 脚本入口，所有定时能力都挂在php think cron下面，然后在服务器 crontab 里每分钟执行一次。脚本内部再判断当前秒数是否匹配业务需要的执行窗口。这样不依赖 FastAdmin 后台那个任务调度界面，部署到哪台服务器都好排查。

5.3 高并发下分销关系绑定串数据

前面提到的并发绑定问题，我再具体展开一下。分销业务做活动时，某分销员的小程序码被大量新用户同时扫码，此时新用户注册完成的一瞬间会有多个并发请求同时尝试写入parent_id。如果数据库事务隔离级别没设置好，可能出现上级 ID 被后写数据覆盖，甚至出现主键冲突报错。

我有一次线上活动就出现过这个问题，排查了半天，最后发现用户在注册环节发起了两次绑定请求，一个走的旧逻辑，一个走的新逻辑。解决办法有三步：

1. 绑定接口做幂等，同一用户重复请求直接返回当前关系；
2. 写入前用SELECT ... FOR UPDATE锁定用户行；
3. parent_id加唯一索引，从数据库层面兜底防重。

5.4 uni-app 多端差异化处理

uni-app 宣传一套代码多端运行，但分销模块涉及分享、海报、支付这些强端能力，差异还是很明显。比如生成分享海报时，微信小程序和 App 的 canvas API 不同，H5 端还存在跨域图片绘制被污染的问题。

我的习惯做法是做一个distribute-platform.js适配层，把所有端差异封装在统一方法里，业务页面只调用方法不看端类型。这样开发时心智负担小，后续某个端出问题也只要修适配层。有条件的话，分销海报功能可以优先做后端生成方案，一次生成到处可用，避免前端三端各自调试的苦海。

5.5 后台配置项记得做权限细分

二开到后面，运营后台的分销设置常常涉及敏感金额配置。如果账号权限管理不细，一个普通客服就能修改佣金比例，后果不堪设想。

FastAdmin 的权限管理是基于规则树做的，我建议把分销相关菜单拆成"分销设置"和"佣金明细""提现审核"三个独立权限节点，分别分配给运营和财务角色。另外修改佣金比例的操作要加操作日志，FastAdmin 自带日志功能，但要在控制器里手动写上log调用，别指望系统自动全记。

6. 最后的一些实在话

做分销商城二开，技术本身并不复杂，复杂的是逻辑边界和业务场景的覆盖。每一次定制，本质上都是把线下分销的利益分配规则翻译成代码，规则越清晰，代码就越简单。怕就怕需求文档里写着"大概这样就行"，上线后运营天天找你对账。

我自己做完这套改造后最大的体会是：分销系统二开的第一优先级永远是关系链数据的准确性和佣金流水的可追溯性。前端页面再炫都不如一条清晰可查的佣金流水来得重要。所以花时间在设计好佣金状态机、流水表和关系绑定时机上，比花时间调海报样式有意义得多。

如果你正准备对 Shopro 的分销功能下手，建议从绑定链路开始梳理，然后是佣金状态流，最后才是页面UI。这个顺序走下来，你会发现后面每一步都有据可依，而不是哪里坏了补哪里。