简介这是一套基于PHP开发的代理分销型商城系统面向中小型电商企业、创业团队及PHP中高级开发者解决多级代理管理、佣金自动结算与分销渠道拓展等核心运营难题。系统采用MVC架构前后端功能完备前端支持用户注册登录、商品展示、购物车、订单支付与客户服务后端涵盖商品/订单/用户/代理等级/佣金/数据统计等六大管理模块并集成支付宝、微信支付及物流API接口。资源包为11.5MB的RAR压缩文件含完整可运行代码含MySQL数据库结构、配置说明与技术文档主要文件类型包括PHP业务逻辑文件、HTML模板页、SQL建表脚本及JS交互脚本结构清晰、注释规范便于二次开发与功能定制。目前已有1349人学习下载读者可直接部署上线、深入理解分销业务模型、掌握PHP电商系统安全实践如防SQL注入、XSS防护及MVC工程化开发流程。1. 为什么一个“代理分销系统”不能只靠后台权限控制来实现分佣逻辑很多同学在做商城类毕设或课设时第一反应是“分销不就是多加几个用户角色再配点权限”——结果答辩被导师一句“那代理卖出去的商品佣金怎么实时算订单取消后佣金要不要回滚下级代理升级了历史订单的分润比例要不要追溯调整”直接问懵。这恰恰说明代理分销不是权限问题而是状态驱动的业务流资金流双轨模型。本套 PHP 代理分销系统方案面向的是需要交付完整可运行系统的场景它不依赖第三方 SaaS 接口所有分佣规则、代理层级、订单归属、结算周期全部由本地代码闭环控制适用于某高校电商方向课程设计、某实验室模拟项目X 的中期交付也适合作为某公司内部轻量级渠道管理工具原型。核心能力覆盖三级代理发展直属/二级/三级、按商品独立设置分佣比例支持固定金额与百分比混合、订单生成即锁定归属关系、结算单自动生成与导出、以及最关键的——佣金变动全程留痕可审计。整套方案基于 PHP 8.1 MySQL 8.0 构建无外部 SDK 强依赖所有逻辑均在 application/ 目录下分层实现学生可逐模块理解从业者可直接替换数据库连接后接入自有支付网关。2. 总体架构设计MVC 分层 四大核心模块的职责边界与数据流向本系统采用经典 MVC 分层结构但关键在于各层之间不越界、不跨层调用、不共享状态。Controller 层仅做请求接收、参数校验、跳转调度Model 层严格封装数据操作与业务规则禁止出现 echo/print_rView 层纯渲染所有变量必须由 Controller 显式传入。整个系统围绕分销业务拆解为四个不可替代的核心模块代理关系管理、商品分佣配置、订单归属引擎、结算单生成器。它们之间通过明确定义的数据契约交互而非全局变量或静态方法调用。这种设计让每个模块可独立测试、可单独替换比如未来想接入 Redis 缓存代理关系只需重写 Model 中的 getAgentTree() 方法其余模块完全无感。下面展开说明各模块定位与协作逻辑。2.1 代理关系管理模块用闭包表Closure Table解决多级代理的查询与变更难题传统邻接表parent_id在查询某代理的所有下级时需递归MySQL 深度受限且性能差而路径枚举path 字段又导致更新成本高。本方案采用闭包表设计在数据库中新增agent_closure表CREATE TABLE agent_closure ( ancestor INT UNSIGNED NOT NULL COMMENT 上级代理ID, descendant INT UNSIGNED NOT NULL COMMENT 下级代理ID, depth TINYINT UNSIGNED NOT NULL DEFAULT 0 COMMENT 层级差0表示自身, PRIMARY KEY (ancestor, descendant), KEY idx_descendant (descendant) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;当 A 发展 BB 发展 C 时插入记录(A,A,0), (A,B,1), (A,C,2)(B,B,0), (B,C,1)(C,C,0)这样查询 A 的所有下级含自身只需一条 SQLSELECT descendant FROM agent_closure WHERE ancestor ?查询 C 的直属上级B则SELECT ancestor FROM agent_closure WHERE descendant ? AND depth 1。更重要的是当 B 升级为区域代理、其下所有子代理自动继承新权限无需遍历更新仅需在agent_closure中补全 A→C 的深度为 2 的记录即可。该设计彻底规避了“查所有下级要 N 次查询”的翻车点也为后续订单归属判断提供了 O(1) 级别的关系判定能力。2.2 商品分佣配置模块支持粒度到 SKU 的独立分佣策略与版本快照分销系统最易被忽略的细节是不同商品的分佣规则可能完全不同。例如A 类高毛利商品给一级代理 15%二级 5%B 类引流商品则一级仅 3%但允许三级参与1%。若统一配置后期运营无法灵活调整。本模块采用“商品维度 代理等级”二维配置并引入版本快照机制// application/model/CommissionRuleModel.php public function getActiveRuleBySku(string $sku, int $agentLevel): array { // 先查当前生效的最新版本 $rule $this-db-query( SELECT * FROM commission_rule WHERE sku ? AND agent_level ? AND status 1 ORDER BY version DESC LIMIT 1, [$sku, $agentLevel] )-fetch(); if (!$rule) { // 降级查通用规则agent_level 0 $rule $this-db-query( SELECT * FROM commission_rule WHERE sku ? AND agent_level 0 AND status 1 ORDER BY version DESC LIMIT 1, [$sku] )-fetch(); } return $rule ?: [type percent, value 0.0]; }每次修改分佣比例系统自动生成新 version时间戳随机数旧规则 status 置为 0。这样历史订单始终按下单时的规则计算杜绝“改了规则老订单佣金突变”的合规风险。同时前端配置页提供“复制当前规则到新 SKU”按钮避免重复录入——这是某次帮 A 同学调试时发现的高频需求他原方案每次换商品都要重填 6 个字段三天内填错两次。2.3 订单归属引擎基于首次触达与邀请码的双重判定机制订单到底算谁的这是分销系统的核心争议点。本方案采用“首次触达 邀请码强制绑定”双保险用户首次访问商城时若 URL 带有?refxxx则将 ref 值存入 session 并写入 cookie有效期 30 天后续下单时优先取 cookie 中的 ref若为空再查 session若两者皆空则归属平台。关键逻辑在 OrderService 中// application/service/OrderService.php public function determineAgentId(int $userId): ?int { // 1. 检查用户是否本身就是代理自购不计佣金 if ($this-agentModel-isAgent($userId)) { return null; } // 2. 从 cookie 获取邀请人IDref_id $refId $_COOKIE[ref_id] ?? null; if (!$refId || !is_numeric($refId)) { return null; } // 3. 验证 ref_id 是否真实存在且有效 $agent $this-agentModel-getById((int)$refId); if (!$agent || $agent[status] ! active) { setcookie(ref_id, , time() - 3600, /); return null; } // 4. 验证该代理是否有权发展此用户防刷单同一IP 24小时内最多3单 $ip $_SERVER[REMOTE_ADDR] ?? 0.0.0.0; $orderCount $this-db-query( SELECT COUNT(*) FROM orders WHERE agent_id ? AND ip ? AND created_at DATE_SUB(NOW(), INTERVAL 1 DAY), [$refId, $ip] )-fetchColumn(); if ($orderCount 3) { // 触发风控清空cookie并记录日志 setcookie(ref_id, , time() - 3600, /); $this-logRisk(Ref flood from IP {$ip} for agent {$refId}); return null; } return (int)$refId; }这段代码解决了三个实际问题一是防止代理自己注册小号刷单自购过滤二是防止过期邀请码持续生效cookie 过期自动失效三是限制恶意刷单IP 维度频控。某次线上压测发现未加 IP 限制时单个代理 1 秒内能生成 17 笔测试订单直接导致佣金池虚高——这个风控点是血泪经验换来的。2.4 结算单生成器按自然月冻结数据 差异化结算状态机结算不是简单把钱打给代理而是涉及对账、申诉、打款、开票四阶段。本模块将结算流程抽象为状态机状态含义可触发动作draft草稿系统自动生成含所有待结算订单编辑备注、标记异常confirmed代理确认无误提交至财务审核audited财务审核通过生成打款批次paid已打款导出凭证、归档每月 1 日凌晨 2 点系统执行php cli.php settlement:generate --month2024-05命令其核心逻辑是# cli.php 中的命令入口 case settlement:generate: $month $_GET[month] ?? date(Y-m); $generator new SettlementGenerator($month); $generator-freezeOrders(); // 冻结该月所有已确认订单禁止再修改 $generator-calculateCommissions(); // 按冻结时的规则计算每笔佣金 $generator-createDraftSettlement(); // 生成草稿结算单 break;freezeOrders()是关键它将orders表中status confirmed AND created_at LIKE 2024-05%的订单将其frozen_at字段设为当前时间并将commission_calculated标记为 true。此后任何对该订单的修改如退货都将触发“佣金回滚”流程而非重新计算——确保结算数据绝对可追溯。这也是为什么我们坚持不用“实时计算佣金”而必须“冻结快照”的根本原因财务审计要的是确定性不是概率。3. 关键实现细节从数据库事务到前端防重提交的全链路保障分销系统最怕什么不是功能少而是钱算错、单丢了、重复打款。这些都不是代码炫技能解决的而是靠一连串看似枯燥的工程细节堆出来的可靠性。下面列出本方案中真正起作用的五个硬核实现点每一条都来自真实翻车现场。3.1 佣金计算必须包裹在数据库事务中且显式指定隔离级别早期版本曾用“先查余额再更新”两步法结果高并发下出现超发。正确做法是所有涉及资金变动的操作必须在一个事务内完成且使用SELECT ... FOR UPDATE锁定行。以代理提现为例// application/model/AgentBalanceModel.php public function deductBalance(int $agentId, float $amount, string $remark): bool { try { $this-db-beginTransaction(); // 1. 锁定该代理的余额记录防止并发扣减 $balance $this-db-query( SELECT balance FROM agent_balance WHERE agent_id ? FOR UPDATE, [$agentId] )-fetch(); if (!$balance || $balance[balance] $amount) { throw new Exception(余额不足); } // 2. 扣减并记录流水 $this-db-query( UPDATE agent_balance SET balance balance - ? WHERE agent_id ?, [$amount, $agentId] ); $this-db-query( INSERT INTO balance_log (agent_id, amount, type, remark, created_at) VALUES (?, ?, withdraw, ?, NOW()), [$agentId, -$amount, $remark] ); $this-db-commit(); return true; } catch (Exception $e) { $this-db-rollback(); $this-logError(提现失败: . $e-getMessage()); return false; } }注意FOR UPDATE必须在事务开启后、任何 UPDATE 之前执行否则锁无效。某次压力测试中因漏写这行100 并发请求导致 3 笔提现成功但只扣了 1 笔余额——这就是没锁住的代价。3.2 前端提交订单必须带唯一 Token服务端校验并立即作废用户手抖连点“提交订单”两次后端若不做防重就会生成两笔相同订单。本方案在订单页加载时由 Controller 生成一次性 Token// application/controller/OrderController.php public function showCheckout() { $token bin2hex(random_bytes(16)); $_SESSION[order_token] $token; $_SESSION[token_created_at] time(); $this-view-render(order/checkout, [token $token]); }提交时前端将 token 放入 hidden input后端校验// application/controller/OrderController.php public function doSubmit() { $token $_POST[token] ?? ; if (!$token || !hash_equals($_SESSION[order_token] ?? , $token)) { $this-response-error(非法请求); return; } // 校验通过立即作废 token unset($_SESSION[order_token]); unset($_SESSION[token_created_at]); // 后续创建订单逻辑... }hash_equals()防止时序攻击unset()确保 token 一次性。这个 Token 不存数据库只在 session 中存活简单高效。某次帮某实验室调试他们原方案用时间戳用户ID拼接结果被脚本批量刷单——因为时间戳可预测。3.3 代理关系变更必须同步更新闭包表且用存储过程保证原子性当代理 A 将下级 B 转让给 C 时需删除 A→B、A→C 子树、B→C 子树等多条记录并新增 C→B、C→C 子树等。若用 PHP 循环删插网络中断会导致闭包表残缺。本方案将此逻辑封装为 MySQL 存储过程DELIMITER $$ CREATE PROCEDURE TransferAgentDownline( IN p_old_ancestor INT, IN p_new_ancestor INT, IN p_descendant INT ) BEGIN DECLARE EXIT HANDLER FOR SQLEXCEPTION BEGIN ROLLBACK; RESIGNAL; END; START TRANSACTION; -- 删除旧路径p_old_ancestor 到 p_descendant 及其所有后代 DELETE ac1 FROM agent_closure ac1 INNER JOIN agent_closure ac2 ON ac1.descendant ac2.descendant WHERE ac1.ancestor p_old_ancestor AND ac2.ancestor p_descendant; -- 插入新路径p_new_ancestor 到 p_descendant 及其所有后代 INSERT INTO agent_closure (ancestor, descendant, depth) SELECT p_new_ancestor, ac.descendant, ac.depth 1 FROM agent_closure ac WHERE ac.ancestor p_descendant; -- 补充自身节点 INSERT INTO agent_closure (ancestor, descendant, depth) VALUES (p_new_ancestor, p_new_ancestor, 0), (p_new_ancestor, p_descendant, 1); COMMIT; END$$ DELIMITER ;PHP 中只需调用CALL TransferAgentDownline(?, ?, ?)即可。存储过程在数据库内执行不受 PHP 进程中断影响真正实现“要么全成功要么全失败”。3.4 结算单导出用流式 CSV避免内存溢出某次为某公司生成上月 20 万笔订单的结算单原方案用fputcsv()全部读入内存再输出PHP 直接 OOM。现改为流式处理// application/controller/SettlementController.php public function exportCsv(int $setId) { $settlement $this-settlementModel-getById($setId); if (!$settlement || $settlement[status] ! confirmed) { $this-response-error(结算单不可导出); return; } // 设置响应头 header(Content-Type: text/csv; charsetutf-8); header(Content-Disposition: attachment; filenamesettlement_ . $setId . .csv); $output fopen(php://output, w); fputcsv($output, [ 订单号, 商品名称, 销售价, 佣金比例, 佣金金额, 代理姓名, 代理手机号, 结算状态 ]); // 分页查询每次 1000 条 $page 1; do { $items $this-settlementModel-getItemsBySettlementId($setId, $page, 1000); foreach ($items as $item) { fputcsv($output, [ $item[order_no], $item[product_name], $item[sale_price], $item[commission_rate] . %, $item[commission_amount], $item[agent_name], $item[agent_phone], $item[status_text] ]); } $page; } while (!empty($items)); fclose($output); }fopen(php://output, w)直接将内容写入 HTTP 响应体不占 PHP 内存分页查询避免 MySQL 单次返回过大结果集。这是处理大数据量导出的标配姿势。3.5 后台操作日志必须记录原始请求参数而非仅记录结果很多系统只记“管理员张三修改了代理 A 的状态”但没记“改成什么状态、之前是什么状态”。一旦出问题无法还原。本方案强制记录完整请求参数// application/middleware/LogMiddleware.php public function handle($request, $next) { $startTime microtime(true); $response $next($request); // 记录日志仅限 admin 路由 if (strpos($request-uri, /admin/) 0 in_array($request-method, [POST, PUT, DELETE])) { $logData [ uri $request-uri, method $request-method, params $request-all(), // 记录全部 POST/PUT 参数 ip $request-ip, user_id $_SESSION[admin_id] ?? 0, duration_ms round((microtime(true) - $startTime) * 1000), status_code $response-getStatusCode(), ]; // 敏感字段脱敏 if (isset($logData[params][password])) { $logData[params][password] ***; } if (isset($logData[params][id_card])) { $logData[params][id_card] substr($logData[params][id_card], 0, 4) . **** . substr($logData[params][id_card], -4); } $this-logModel-insert($logData); } return $response; }$request-all()获取原始参数$response-getStatusCode()记录是否成功。脱敏逻辑防止身份证、密码等敏感信息落库。某次排查代理投诉“佣金被莫名清零”正是靠这条日志查出是某管理员误点了“重置余额”按钮且参数中明确写了reset_alltrue。4. 避坑指南代理分销系统开发中最容易翻车的 4 个点及解决方案做分销系统90% 的问题不是不会写代码而是没踩过坑、不知道哪里会塌方。下面这四条每一条都对应一次真实的线上事故或答辩翻车按“现象 → 原因 → 解决”给出可立即落地的方案。4.1 现象代理升级后历史订单佣金没变但新订单按新比例算财务对不上账原因佣金计算逻辑写在订单创建时但未区分“订单创建时间”和“佣金计算时间”。当代理在 5 月 10 日升级5 月 1 日的订单仍按旧规则算但财务要求所有订单统一按升级后规则追溯调整。解决在commission_rule表中增加effective_date字段表示该规则生效日期。佣金计算时取MIN(order.created_at, rule.effective_date)作为实际生效时间。同时提供后台“批量重算历史佣金”功能仅对effective_date早于代理升级日的订单触发重算并生成差异日志供审计。切记重算必须人工触发不可自动执行。4.2 现象用户通过代理 A 的链接进站但最终用代理 B 的账号下单佣金算给了 B原因前端未严格隔离“访客身份”与“登录身份”。用户点击 A 的链接存了 ref_idA但登录时用了 B 的账号后端直接取user_id当作代理 ID忽略了 ref_id。解决在用户登录成功后检查 session 中是否存在ref_id若存在且ref_id ! user_id则将ref_id存入user_ref_id字段用户表新增并在订单归属引擎中优先取user_ref_id其次才是ref_idcookie。这样既尊重用户主动选择的代理关系又保留邀请溯源能力。4.3 现象结算单生成后代理申请退货系统直接扣减佣金但财务说“已结算的佣金不能动”原因未建立“结算单”与“订单”的强关联也未对已结算订单做状态保护。退货逻辑只改订单状态未检查该订单是否已在某结算单中。解决在orders表中增加settlement_id字段记录该订单归属的结算单 ID为 NULL 表示未结算。退货接口增加校验if ($order[settlement_id]) { throw new Exception(该订单已计入结算单不可退货请联系财务); }。同时结算单状态机中“paid”状态后禁止任何修改确保法律效力。4.4 现象代理在后台看到“可提现余额”是 5000 元但提现时提示“余额不足”原因前端显示的“可提现余额”是SELECT SUM(commission) FROM balance_log WHERE agent_id ? AND type income但未扣除已申请未打款的提现单。解决定义“可用余额 总收入 - 已提现 - 待打款提现单总额”。在agent_balance表中增加pending_withdrawal字段每次创建提现单时UPDATE agent_balance SET pending_withdrawal pending_withdrawal ? WHERE agent_id ?打款成功后再减去该笔。前端展示余额时直接查balance - pending_withdrawal。永远不要在应用层做“查-算-更”三步必须用数据库字段固化状态。5. 验收与答辩如何用一份可运行的 Demo 和三张表说服导师/客户答辩不是讲 PPT是证明你真的做出来了、能跑通、没漏洞。我带过的所有项目只要过了这三关基本就稳了。下面是我自己总结的验收 checklist也是每次交付前必走的流程。5.1 第一关本地环境一键启动5 分钟内跑通核心链路别指望导师装 Composer、配 Nginx。本方案提供docker-compose.yml只需三步# 1. 下载源码后进入目录 cd php-distribution-system # 2. 启动容器含 PHP-FPM、Nginx、MySQL、Redis docker-compose up -d # 3. 初始化数据库自动执行 migrations 和 seeders docker-compose exec php php artisan migrate:fresh --seed启动后访问http://localhost:8080/admin默认账号admin/admin123即可看到完整后台。前台http://localhost:8080支持游客浏览、注册、下单。重点演示注册两个账号 A 和 B → A 发展 BB 注册时带 refA→ B 下单 → 查看 A 的“待结算佣金” → 运行php artisan settlement:generate --month2024-05→ 查看生成的结算单 → 导出 CSV。这一条链路必须 5 分钟内走完中间不能卡顿、不能报错。如果导师说“你这环境我配不了”那就等于没做完。5.2 第二关用三张表证明业务逻辑闭环答辩时导师最常问“你说佣金实时计算数据在哪”、“代理关系怎么查”、“结算单怎么保证不丢” 这时不要讲代码直接打开 phpMyAdmin 或 Adminer展示以下三张表的实际数据表名关键字段演示要点为什么重要agent_closureancestor,descendant,depth展示 A→Bdepth1、A→Cdepth2、B→Cdepth1三条记录证明多级关系不是靠递归查出来的而是预计算好的性能有保障commission_rulesku,agent_level,type,value,effective_date,version展示同一 SKU 下level115%、level25%、level0通用 3%三条规则且 version 递增证明分佣规则可配置、可追溯、可降级不是硬编码settlement_itemssettlement_id,order_id,commission_amount,status展示一笔订单对应多个结算项如买 3 件商品生成 3 行且status为calculated证明佣金是按商品粒度计算的不是按订单粗暴统算提示提前准备 3 条真实数据截图答辩时直接投屏。比讲 10 分钟原理管用。5.3 第三关现场演示一个“反常识”操作证明你懂风控导师如果只看正向流程说明他还没信。这时主动演示一个“错误操作”并解释系统如何防御操作在订单提交页F12 修改隐藏域input typehidden nametoken valuexxx为一个错误值然后提交。预期结果页面跳转回购物车并提示“非法请求”。解释这不是 bug是设计。Token 用hash_equals()校验防止时序攻击且提交后立即作废杜绝重放。同理可演示在结算单草稿页手动修改 URL 中的id123为id999返回 404在代理列表页用 Postman 发送 PUT 请求修改非本人代理信息返回 403在提现页输入负数金额前端 JS 和后端 PHP 双重拦截。注意演示前备份数据库避免误操作影响其他数据。所有防御逻辑必须在代码中可定位答辩时能快速指出文件和行号。从那以后我每次交付前都强制走一遍这三关先 docker 启动看能不能跑、再查三张表看数据对不对、最后故意搞点破坏看系统稳不稳。不是为了炫技是确保每一个字写在论文里的功能都能在导师面前点出来、看得到、摸得着。希望帮到你。本文还有配套的精品资源点击获取
