簡介這是一套基于PHP開發(fā)的代理分銷型商城系統(tǒng)面向中小型電商企業(yè)、創(chuàng)業(yè)團(tuán)隊(duì)及PHP學(xué)習(xí)者解決多級代理管理、傭金自動結(jié)算與分銷渠道拓展等核心運(yùn)營需求。系統(tǒng)采用MVC架構(gòu)前后端功能完備前端支持用戶注冊登錄、商品展示、購物車與訂單全流程后端涵蓋商品管理、代理審核與等級設(shè)定、訂單履約、數(shù)據(jù)統(tǒng)計(jì)及第三方支付支付寶/微信與物流接口集成。資源包為11.5MB的RAR壓縮文件含完整可運(yùn)行代碼主要包含PHP業(yè)務(wù)邏輯文件、MySQL數(shù)據(jù)庫腳本、HTML/CSS/JS前端頁面及配置文檔結(jié)構(gòu)清晰便于二次開發(fā)與功能定制。目前已有1349人學(xué)習(xí)下載讀者可直接部署調(diào)試深入理解電商分銷模型實(shí)現(xiàn)、PHP安全防護(hù)防SQL注入/XSS、傭金計(jì)算邏輯及高復(fù)用模塊設(shè)計(jì)思路。1. 這不是個(gè)“代理后臺”而是一套能跑通三級分潤、自動結(jié)算、實(shí)時(shí)查傭的 PHP 商城分銷閉環(huán)系統(tǒng)你手上有款自營商品想讓朋友幫你賣但又怕對賬扯皮、傭金算錯(cuò)、下級代理拉人沒動力——別急著寫 Excel 表格或手動打款。這個(gè) PHP 代理分銷系統(tǒng)從注冊即生成專屬推廣鏈接、下單自動綁定上級、訂單完成觸發(fā)多級分潤計(jì)算支持一級、二級、三級到后臺實(shí)時(shí)查看各級代理的團(tuán)隊(duì)規(guī)模、成交額、待結(jié)傭金、已提現(xiàn)記錄全部走完完整業(yè)務(wù)流。它不依賴 SaaS 平臺代碼全開源數(shù)據(jù)庫結(jié)構(gòu)清晰核心邏輯集中在app/Logic/Commission.php和app/Model/Agent.php里沒有黑匣子調(diào)用也沒有隱藏的第三方服務(wù)鉤子。適合中小團(tuán)隊(duì)快速部署一個(gè)可控、可審計(jì)、能二次開發(fā)的分銷底座尤其適合已有 PHP 技術(shù)棧、想把分銷模塊嵌入現(xiàn)有商城的開發(fā)者。如果你正卡在“怎么讓代理關(guān)系鏈自動建?！薄霸趺幢苊庵貜?fù)結(jié)算”“怎么讓下級代理看到自己能賺多少”這三個(gè)問題上這個(gè)項(xiàng)目就是為解這三道題寫的。2. 環(huán)境準(zhǔn)備與一鍵部署從 Nginx PHP 7.4 到后臺可登錄的完整路徑2.1 基礎(chǔ)運(yùn)行環(huán)境PHP 版本、擴(kuò)展與目錄權(quán)限硬性要求該項(xiàng)目基于 Laravel 8.x 框架封裝非原生 PHP 寫就因此必須滿足 Laravel 的底層約束。常見翻車點(diǎn)在于 PHP 版本和擴(kuò)展缺失——它不兼容 PHP 8.0實(shí)測 PHP 7.4.33 是最穩(wěn)版本PHP 擴(kuò)展中mbstring、openssl、pdo_mysql、tokenizer、xml、ctype、json必須啟用缺一不可。特別注意bcmath擴(kuò)展分潤計(jì)算中所有金額運(yùn)算如 0.01 × 0.15都強(qiáng)制使用bcadd()/bcmul()若未開啟會導(dǎo)致傭金歸零。Nginx 配置需啟用try_files $uri $uri/ /index.php?$query_string;不能簡單用 Apache 的.htaccess替代。部署時(shí) Web 根目錄必須指向public/而非項(xiàng)目根目錄否則路由全部 404。# 檢查 PHP 環(huán)境是否達(dá)標(biāo)執(zhí)行后應(yīng)無報(bào)錯(cuò)且返回版本號 php -v php -m | grep -E (mbstring|openssl|pdo_mysql|tokenizer|xml|ctype|json|bcmath)提示若用寶塔面板PHP 設(shè)置頁中「禁用函數(shù)」列表里務(wù)必刪掉putenv和pcntl_exec——Laravel 的 Artisan 命令行工具依賴它們否則php artisan migrate會靜默失敗。2.2 數(shù)據(jù)庫初始化表結(jié)構(gòu)設(shè)計(jì)意圖與關(guān)鍵字段說明項(xiàng)目使用 MySQL 5.7共 12 張核心表其中agents代理主表、agent_relations上下級關(guān)系表、orders訂單主表、commission_logs分潤流水表四張是業(yè)務(wù)心臟。agent_relations表采用「單向父子」設(shè)計(jì)每條記錄存parent_id和child_id并帶level字段值為 1/2/3不冗余存儲整條關(guān)系鏈靠遞歸查詢構(gòu)建團(tuán)隊(duì)樹。commission_logs表中type字段區(qū)分order_settle訂單結(jié)算、withdraw_apply提現(xiàn)申請、withdraw_success提現(xiàn)成功三類動作status字段控制狀態(tài)機(jī)流轉(zhuǎn)0待處理1已完成2已駁回這是后續(xù)做財(cái)務(wù)對賬的唯一可信源。-- 創(chuàng)建代理關(guān)系表關(guān)鍵聯(lián)合索引加速上級查下級、下級查上級雙向查詢 CREATE TABLE agent_relations ( id bigint unsigned NOT NULL AUTO_INCREMENT, parent_id bigint unsigned NOT NULL COMMENT 上級代理ID, child_id bigint unsigned NOT NULL COMMENT 下級代理ID, level tinyint unsigned NOT NULL DEFAULT 1 COMMENT 層級1直推2間推3再間推, created_at timestamp NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_parent_child (parent_id,child_id), KEY idx_child (child_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci;2.3 安裝流程五步走完從解壓到登錄后臺上傳并解壓將源碼包上傳至服務(wù)器/var/www/distribution/確保storage/和bootstrap/cache/目錄可寫chmod -R 775 storage bootstrap/cache配置.env復(fù)制.env.example為.env修改DB_DATABASE、DB_USERNAME、DB_PASSWORD關(guān)鍵一步設(shè)置APP_URLhttp://your-domain.com必須帶協(xié)議和域名不能是 localhost否則推廣鏈接生成異常安裝依賴在項(xiàng)目根目錄執(zhí)行composer install --no-dev --optimize-autoloader跳過 dev 包減少體積執(zhí)行遷移php artisan migrate --force--force是必須參數(shù)生產(chǎn)環(huán)境默認(rèn)禁止生成密鑰 清緩存php artisan key:generate php artisan config:clear php artisan cache:clear完成后訪問http://your-domain.com/admin/login初始賬號密碼均為admin / admin123首次登錄后強(qiáng)制修改。3. 核心模塊拆解分潤引擎、代理關(guān)系鏈、推廣鏈接生成三大主干邏輯3.1 分潤引擎Commission::calculateForOrder()如何保證金額不溢出、不漏算分潤不是簡單乘法而是帶規(guī)則的條件計(jì)算。核心方法位于app/Logic/Commission.php入口是calculateForOrder(Order $order)。它接收一個(gè)訂單對象返回一個(gè)Collection每項(xiàng)含agent_id、amount、level、rule_key。關(guān)鍵設(shè)計(jì)有三點(diǎn)精度控制所有金額以「分」為單位存入數(shù)據(jù)庫orders.total_amount是整數(shù)計(jì)算時(shí)先轉(zhuǎn)元再乘比例最后round(bcmul($base, $rate, 2), 0)回到分避免浮點(diǎn)誤差累積層級穿透按agent_relations表反查該訂單買家的全部上級但只取 level ≤ 3 的記錄并去重防止 A→B→C→D 中 C 同時(shí)是 A 的二級和 B 的一級被重復(fù)計(jì)規(guī)則隔離不同商品類目可配置不同分潤率$order-product-category-commission_rate優(yōu)先于全局默認(rèn)率且支持「滿 1000 元額外加 1%」這類階梯規(guī)則由CommissionRuleManager類動態(tài)加載。// app/Logic/Commission.php 節(jié)選核心計(jì)算片段 public function calculateForOrder(Order $order): Collection { $buyerId $order-user_id; // 1. 反查 buyer 的所有上級代理含層級 $uplines DB::table(agent_relations) -where(child_id, $buyerId) -where(level, , 3) -get([parent_id, level]); return $uplines-map(function ($upline) use ($order) { $rate $this-getEffectiveRate($order, $upline-level); $baseAmount bcmul((string)$order-total_amount, 0.01, 2); // 轉(zhuǎn)元 $amountInCents round(bcmul($baseAmount, $rate, 2), 0) * 100; // 轉(zhuǎn)回分 return (object)[ agent_id $upline-parent_id, amount (int)$amountInCents, level $upline-level, rule_key $this-currentRuleKey ]; }); }注意$amountInCents必須是整數(shù)類型因?yàn)閿?shù)據(jù)庫字段是BIGINT若傳 float 會觸發(fā) MySQL 截?cái)鄬?dǎo)致分潤變 0。3.2 代理關(guān)系鏈Agent::buildTeamTree()怎么高效查出三級團(tuán)隊(duì)結(jié)構(gòu)前端「我的團(tuán)隊(duì)」頁面要展示我A→ 直推 5 人 → 每人再推若干 → 最多展開到三級。如果每次請求都遞歸查 3 層MySQL 會瞬間變慢。本項(xiàng)目采用「預(yù)生成 緩存」策略當(dāng)新代理注冊并綁定上級時(shí)觸發(fā)Agent::syncTeamAncestors()將該代理的所有祖先最多 3 級寫入agent_ancestors表結(jié)構(gòu)agent_id,ancestor_id,distance。查團(tuán)隊(duì)時(shí)只需一條 JOINSELECT u.*, a.distance FROM users u JOIN agent_ancestors a ON u.id a.agent_id WHERE a.ancestor_id ? AND a.distance 3 ORDER BY a.distance, u.created_at;agent_ancestors表在代理注冊、上級變更、關(guān)系刪除時(shí)由 Observer 自動維護(hù)避免運(yùn)行時(shí)計(jì)算開銷。這也是為什么項(xiàng)目要求 MySQL 5.7——需要窗口函數(shù)支持ROW_NUMBER()做距離去重。3.3 推廣鏈接生成ShareLinkGenerator::make()如何防刷、防篡改、帶來源追蹤每個(gè)代理的推廣鏈接形如https://yoursite.com/register?refabc123其中ref參數(shù)不是代理 ID而是加密字符串。生成邏輯在app/Services/ShareLinkGenerator.php使用hash_hmac(sha256, $agentId . $timestamp, config(app.key))生成簽名將$agentId、$timestamp、$signature三者拼接后 base64url 編碼非標(biāo)準(zhǔn) base64/替換為-_鏈接過期時(shí)間設(shè)為 7 天解碼后校驗(yàn) timestamp 是否超時(shí)、signature 是否匹配任一失敗則拒絕注冊。這樣設(shè)計(jì)杜絕了「手動改 ref 參數(shù)綁定任意上級」的漏洞也避免了代理 ID 泄露帶來的信息風(fēng)險(xiǎn)。4. 避坑指南上線前必須驗(yàn)證的 4 個(gè)致命細(xì)節(jié)4.1 現(xiàn)象后臺顯示「今日新增代理 0」但實(shí)際有用戶通過推廣鏈接注冊原因.env中APP_URL未配置為真實(shí)域名或 Nginx 未透傳X-Forwarded-Proto頭導(dǎo)致URL::full()生成的注冊鏈接是http://localhost/register?refxxx用戶點(diǎn)擊后跳轉(zhuǎn)失敗前端 JS 捕獲不到 ref 參數(shù)。解決確認(rèn)APP_URL為https://your-domain.com并在 Nginx 配置中加入proxy_set_header X-Forwarded-Proto $scheme;。4.2 現(xiàn)象訂單完成但commission_logs表無記錄代理后臺「待結(jié)算傭金」始終為 0原因訂單狀態(tài)變更事件未正確觸發(fā)。項(xiàng)目監(jiān)聽OrderStatusUpdated事件但默認(rèn)隊(duì)列驅(qū)動為sync同步執(zhí)行若APP_DEBUGfalse且日志級別設(shè)為error事件內(nèi)異常會被靜默吞掉。解決臨時(shí)切到database隊(duì)列.env中設(shè)QUEUE_CONNECTIONdatabase運(yùn)行php artisan queue:work --once觀察failed_jobs表是否有報(bào)錯(cuò)或打開APP_DEBUGtrue查看具體異常。4.3 現(xiàn)象代理 A 推薦 BB 又推薦 C但 C 下單后A 的二級分潤未到賬原因agent_relations表中缺少 A→C 的 level2 記錄。系統(tǒng)只在 B 注冊時(shí)自動生成 A→Blevel1但不會自動補(bǔ)全 A→Clevel2需靠Agent::syncTeamAncestors()在 C 注冊時(shí)補(bǔ)全。若該方法未被調(diào)用如注冊流程繞過AgentRegisterService關(guān)系鏈就斷了。解決檢查注冊控制器是否調(diào)用AgentRegisterService::handle($request)或手動執(zhí)行php artisan agent:sync-ancestors補(bǔ)全歷史數(shù)據(jù)。4.4 現(xiàn)象提現(xiàn)申請?zhí)峤缓鬆顟B(tài)卡在「審核中」財(cái)務(wù)后臺無通知原因提現(xiàn)審核依賴App\Observers\WithdrawalObserver但該 Observer 未在AppServiceProvider::boot()中注冊或withdrawals表的status字段默認(rèn)值為pending但 Observer 的updating方法只監(jiān)聽status從pending變更為approved/rejected若數(shù)據(jù)庫默認(rèn)值寫錯(cuò)如寫成processing事件不觸發(fā)。解決確認(rèn)withdrawals.status默認(rèn)值為pending并在AppServiceProvider中添加Withdrawal::observe(WithdrawalObserver::class);。5. 二次開發(fā)實(shí)戰(zhàn)如何接入微信支付回調(diào)、增加邀請返現(xiàn)、導(dǎo)出代理業(yè)績 Excel5.1 接入微信支付回調(diào)復(fù)用現(xiàn)有訂單模型只改三處微信支付成功后會 POST 通知到你的notify_url。本項(xiàng)目已預(yù)留/api/payment/wechat/notify路由但控制器空實(shí)現(xiàn)。你需要在app/Http/Controllers/Api/Payment/WechatNotifyController.php中解析微信 XML 回調(diào)校驗(yàn)簽名根據(jù)out_trade_no查orders表確認(rèn)訂單存在且status unpaid調(diào)用OrderService::markAsPaid($order, wechat)—— 此方法內(nèi)部會觸發(fā)OrderStatusUpdated事件自動完成分潤結(jié)算。// app/Services/OrderService.php 中補(bǔ)充 public function markAsPaid(Order $order, string $channel): void { DB::transaction(function () use ($order, $channel) { $order-update([ status paid, paid_at now(), payment_channel $channel ]); // 關(guān)鍵觸發(fā)事件讓 Commission 邏輯自動跑 event(new OrderStatusUpdated($order, unpaid, paid)); }); }提示微信回調(diào)地址必須在微信商戶平臺配置為https://your-domain.com/api/payment/wechat/notify且域名需備案。測試時(shí)用「微信支付沙箱環(huán)境」避免真金白銀扣款。5.2 增加邀請返現(xiàn)在注冊流程中插入現(xiàn)金獎勵邏輯需求新用戶通過代理鏈接注冊除建立代理關(guān)系外再給邀請人上級發(fā) 5 元現(xiàn)金紅包。不走分潤池單獨(dú)記賬。新增表invitation_bonusesid,inviter_id,invitee_id,amount_cents,status,created_at在AgentRegisterService::handle()的末尾添加if ($referrerId) { DB::table(invitation_bonuses)-insert([ inviter_id $referrerId, invitee_id $user-id, amount_cents 500, // 5元500分 status pending, created_at now() ]); // 同時(shí)更新 inviter 的 wallet_balance 字段需提前在 users 表加此字段 DB::table(users)-where(id, $referrerId)-increment(wallet_balance, 500); }5.3 導(dǎo)出代理業(yè)績 Excel用 PhpSpreadsheet 替換原生 CSV原項(xiàng)目導(dǎo)出用fputcsv格式簡陋。升級為 Excel 需composer require phpoffice/phpspreadsheet新建app/Exports/AgentPerformanceExport.php繼承Maatwebsite\Excel\Concerns\FromCollection在導(dǎo)出控制器中調(diào)用Excel::download(new AgentPerformanceExport($agentId), agent-performance.xlsx)。關(guān)鍵點(diǎn)AgentPerformanceExport的collection()方法應(yīng)返回一個(gè)包含name,team_size,total_orders,total_commission的集合數(shù)據(jù)來自聯(lián)表查詢而非多次 DB 請求。// app/Exports/AgentPerformanceExport.php public function collection() { return DB::table(agents) -select( users.name, DB::raw(COUNT(DISTINCT ar2.child_id) as team_size), DB::raw(COUNT(DISTINCT o.id) as total_orders), DB::raw(SUM(cl.amount) as total_commission) ) -join(users, agents.user_id, , users.id) -leftJoin(agent_relations as ar1, agents.user_id, , ar1.parent_id) -leftJoin(agent_relations as ar2, ar1.child_id, , ar2.parent_id) -leftJoin(orders as o, ar2.child_id, , o.user_id) -leftJoin(commission_logs as cl, ar2.child_id, , cl.agent_id) -where(agents.user_id, $this-agentId) -groupBy(users.name) -get(); }從那以后我每次接手分銷類項(xiàng)目都會先翻app/Logic/Commission.php和database/migrations/*commission*遷移文件確認(rèn)分潤精度處理、關(guān)系鏈存儲方式、事件觸發(fā)時(shí)機(jī)這三點(diǎn)是否對齊業(yè)務(wù)需求。哪怕只是加個(gè)「滿 1000 返 50」的活動我也強(qiáng)制走一遍php artisan tinker手動調(diào)用Commission::calculateForOrder()打印出每級金額盯著小數(shù)點(diǎn)后兩位——這比寫十遍單元測試更能暴露浮點(diǎn)陷阱。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取