一、开发背景与定位
龙霄加盟推广插件（LongXiao Affiliate）是由萨龙网络出品的一款深度 WordPress 电商加盟推广管理插件，100% 为龙霄主题（LongXiao Theme）量身定制。传统 WordPress 生态中的加盟推广插件——如 AffiliateWP、WooCommerce Affiliate 等——虽然功能强大，但它们面向通用场景设计，与龙霄主题高度解耦的前后端架构（WordPress 后端 + Vue.js/Nuxt.js 前端）、WPGraphQL 数据层、多语言多币种体系、余额系统等特色功能无法原生适配。龙霄加盟推广插件正是为解决这一断层而生。
插件采用纯自定义数据表架构，不依赖任何 WordPress 自定义文章类型（CPT），所有加盟商信息、推广记录、访问日志、创意素材和链接数据均存储在独立的数据表中，性能优异且与主题的前端 GraphQL 查询层无缝对接。插件后台预设了完整的「加盟推广」主菜单及八大子菜单，覆盖从加盟商管理、佣金结算到数据报表的全链路运营需求。无论你是运营垂直电商平台、内容变现社区，还是跨境多语言店铺，这套插件都能提供精准、高效、可定制的加盟推广管理体验。
二、核心菜单功能详解
2.1 概述（Overview）—— 数据驾驶舱
概述页面是插件的仪表盘，以十个核心统计卡片快速呈现全局运营状态：加盟用户数（含总计与活跃数）、总素材数、总链接数、总推广数、总访问量、总转化数、转化率、累计佣金、累计已付佣金、累计未付佣金。十大数据让管理者一屏掌握平台推广业务的整体健康度。
统计卡片下方是四组数据表格构成的运营看板，呈 2×2 布局：
- 最优推广用户排行：按收益和推广次数排序，识别高价值加盟商。
- 近期注册用户：展示新加盟用户的审核状态，支持快速跟进。
- 最近访问记录：展示推广链接的来源渠道和 URL 参数，帮助分析引流效果。
- 最新推广动态：展示最新的订单转化记录，含状态标签（已支付/未支付/已拒绝/已退款）。
这套看板的设计初衷是让管理者无需跳转多个子页面即可完成日常巡检，快速发现异常（如被拒加盟申请激增、访问量突降等）。
2.2 加盟管理（Affiliates）—— 加盟商全生命周期管理
加盟管理页面是插件的核心运营阵地，采用 WordPress 标准列表表格（WP_List_Table）呈现所有加盟商记录。每一行展示加盟商 ID、用户 ID、状态、佣金比例、累积收益、未支付收益、推广次数、访问次数、注册时间和审核时间。
表格支持按用户 ID 搜索和批量删除操作。插件预设了四种加盟商状态：
- 待审核（pending）：新提交申请，需运营人员人工审核，操作栏提供绿色的「通过」和红色的「拒绝」按钮。
- 已通过（active）：正常推广中的加盟商，可执行停用、编辑、删除操作。
- 已停用（inactive）：被暂时冻结的加盟商，支持一键恢复为活跃状态。
- 已拒绝（rejected）：未通过审核的申请，支持重新激活（被拒绝的加盟商可自行在前端重新提交申请，状态重置为待审核并触发新通知）。
编辑页面支持修改状态（下拉选择）、佣金比例（百分比或固定金额）、佣金类型、网站网址、申请原因、累积收益、未支付收益、推广次数、访问次数和注册时间等信息。所有状态变更均会自动触发龙霄主题的通知系统（系统内支持站内通知、邮件通知、微信通知三种渠道独立开关），确保加盟商在个人中心实时收到审核结果通知。
表格上方新增了统计汇总栏，分「当前页」和「总计」展示当前筛选条件下的关键数据，包括访问量、推广数、转化数，以及按语言区域拆分的累计收益和未付收益（多币种场景下分别以对应货币符号显示），帮助管理者快速了解数据分布而不需要逐行加总。
2.3 推广记录（Referrals）—— 订单级佣金明细
推广记录页面管理所有通过加盟链接产生的订单转化数据。表格列包含：ID、加盟商、客户、订单 ID、金额、状态、描述、时间和语言区域（多语言场景下显示）。
页面顶部提供筛选器，支持按订单 ID、加盟商 ID、客户 ID 和状态（全部/未支付/已支付/已拒绝/已退款）快速定位记录。内置批量操作（接受、拒绝、删除）大幅提升审核效率。访问日志、创意素材和链接管理页面同样支持批量删除操作；所有列表表格均支持通过界面选项自定义每页显示条数（默认 20 条）。
表格上方增设统计汇总栏，分「当前页」和「总计」展示已付佣金和未付佣金的金额汇总，多语言环境下按语言区域分别显示对应币种的合计值，方便管理者即时掌握推广成本的全貌。
新增和编辑推广记录的表单包含完整字段：加盟商用户 ID（必填）、客户 ID、订单 ID（必填）、金额（必填）、语言区域（多语言场景）、访问 ID、状态、参考信息、上下文和描述。插件内置并发锁机制（基于 WordPress Transient API），防止同笔订单重复创建佣金记录。当状态变更为「已支付」时，插件自动调用龙霄主题的余额系统，将佣金打入加盟商账户余额并发送站内通知和站外邮件（含微信）通知；当订单发生退款时，系统自动从余额扣除对应金额并从积分中扣除相应推广积分，实现全自动的佣金账务闭环。
2.4 访问日志（Visits）—— 全链路引流溯源
访问日志页面记录了每一次通过加盟链接访问网站的完整数据。表格包含：ID、加盟商、访客、访问 URL、来源（Referrer）、Campaign、设备类型（桌面/手机/平板）、浏览器、操作系统、是否已转化、时间和 IP 地址。
数据颗粒度极细，支持按 URL 或来源搜索，以及批量删除和单条删除。每条记录都精准记录了设备指纹信息，这在反刷单场景中至关重要——结合插件后台的防刷设置，管理者可以轻松识别来自同一设备或 IP 的高频异常访问。
更重要的是，「已转化」标记将访问记录与推广记录打通，管理者可以追溯每一笔佣金是从哪个渠道、哪个 Campaign、哪个创意素材引流而来，实现推广 ROI 的精细化归因分析。插件内置系统日志（salong_affiliate_logs），自动记录佣金跳过、发放失败等异常事件，为排查问题提供完整审计链路。
2.5 创意素材（Creatives）—— 标准化推广物料库
创意素材页面用于管理提供给加盟商的推广物料。支持三种素材类型：图片、二维码、链接。表格展示：ID、类型（带图片缩略图）、名称、Campaign、URL、状态（已上线/已下线）、创建时间和更新时间。
插件内置二维码生成功能（对接 api.qrserver.com 外部 API），输入的 URL 和名称可以一键生成二维码图片并自动上传到 WordPress 媒体库。三种素材类型在编辑表单中通过 JavaScript 动态切换字段显示，交互体验流畅。
每个素材支持上下线切换（上线/下线），管理者可以配合营销活动节奏灵活控制物料的可使用状态。在龙霄主题前端，加盟商在「创意素材」页面中只能看到状态为「已上线」的物料，确保推广物料的可控性和时效性。
2.6 链接管理（URLs）—— 加盟商推广链接看板
链接管理页面展示系统中所有加盟推广链接记录，包含 ID、用户 ID、URL、Campaign、访问次数、转化次数、创建时间和更新时间。此页面与龙霄主题前端加盟商自行创建的链接形成对应关系——运营人员可以在此处集中管理所有手动创建的推广链接并查看每条链接的实时访问和转化数据。
其中「访问次数」和「转化次数」是直接从访问日志表中实时查询的统计结果，管理者能够直观判断哪些链接的引流效果最好，为后续的 Campaign 投放决策提供一手数据支撑。
2.7 数据报表（Reports）—— 多维度经营分析
数据报表是插件中最具深度的功能模块。采用标签页导航 + 日期范围筛选的交互模式，支持按加盟商 ID、Campaign 和语言区域进一步下钻分析。四大标签页各具侧重：
加盟报表（Affiliates Tab）：展示历史全部加盟总数、周期内新增加盟数、最佳转化率加盟商及其转化率。趋势图以日为单位展示加盟商注册曲线，Top 10 转换率排行榜让管理者快速识别高绩效群体。
推广报表（Referrals Tab）：按币种（多语言多币种场景）展示历史已支付总额、历史未支付总额、周期内已支付/未支付金额及均值。每日趋势图可视化佣金支出曲线，多语言区域的透视矩阵和 Top 10 排行榜帮助分析不同语言市场的佣金分布。
访问报表（Visits Tab）：展示历史总访问量、周期内访问量、周期内转化量、历史转化率、最佳来源渠道。每日趋势图结合来源排名表格，为流量渠道优化提供量化依据。
活动报表（Campaigns Tab）：展示历史 Campaign 总数、最佳转化 Campaign、周期内最活跃 Campaign、周期内最佳推广 Campaign。每日趋势图和 Top 10 排行榜提供 Campaign 粒度的效果对比。
所有报表图表均基于 Chart.js v4.5.1 渲染，搭配插件自研的数据缓存版本控制机制，在大量数据场景下依然保持流畅加载。
2.8 加盟设置（Settings）—— 灵活可配的业务规则
加盟设置页面由 Codestar Framework 驱动，分为四大配置区块：
常规设置：开放/关闭自主注册开关、允许/禁止自推广、是否启用人工审核、选择加盟协议页面、设置推广链接参数（默认 ref）、配置申请原因长度（默认 6-50 字符）及敏感词过滤。
佣金设置：支持百分比佣金或固定金额两种计费模式，每个加盟商可单独设置佣金比例覆盖全局默认值（新加盟商自动继承全局配置）。可配置佣金比例、固定金额和 Cookie 有效天数（默认 30 天）。注意：纯积分支付的订单不计推广转化。
排除规则：未付款订单不计佣金、免费/零元订单不计佣金、最后推荐计佣金、优惠券订单不计佣金、运费不计佣金、排除指定商品、积分支付订单不计佣金——七项规则为精细化佣金策略提供全面保障。
防刷设置：全局防刷机制开关、设备指纹检测、设备频率限制、IP 频率限制、时间窗口配置。四维防护体系有效遏制恶意刷单行为，保护平台佣金支出的安全性。
三、与龙霄主题的协同适配优势
龙霄加盟推广插件与龙霄主题的协同绝非简单的「兼容」，而是深度、双向的原生融合：
- GraphQL 数据层完全打通：插件注册了完整的 WPGraphQL 查询和变更（Mutation）类型，龙霄主题前端通过
salongGetAuthorContent一个 GraphQL 查询即可获取所有加盟页面数据，无需额外 REST API 开发。 - 余额系统集成：佣金发放不需要单独开发提现模块，数据自动汇入龙霄主题的余额系统，与平台会员余额一体化管理。
- 通知与动态系统融合：加盟申请审核、佣金入账、订单退款等事件自动触发龙霄主题的站内通知、邮件通知（两种渠道可独立开关）和动态日志，加盟商在个人中心的「通知」和「动态」频道即可接收所有推广相关消息。
- 多语言多币种原生支持：通过龙霄主题的 Polylang 集成层，每笔推广记录、每个创意素材、每条链接均可关联语言区域，数据报表支持按币种拆分统计，满足跨境多语言电商的复杂需求。
- 积分系统联动：推广转化成功后，主题的积分系统可自动奖励推广积分（默认 100 分，可在主题积分设置中自定义）；退款时系统同步扣除相应积分，形成「佣金 + 积分」的双重激励机制。
- 前端路由无缝嵌入：插件不需要创建任何前端模板，龙霄主题的
/user/{id}/affiliate/*路由体系原生解析插件数据，加盟商在个人中心即可完成申请、查看数据、管理链接和素材等全部操作。
四、实操价值与用户收益
从运营视角来看，插件解决了电商加盟推广中最核心的三个问题：
效率提升：从加盟申请审核到佣金结算，所有操作无需离开 WordPress 后台。列表表格的批量操作、搜索筛选和快速状态切换，将日常运营效率提升数倍。
数据驱动：八大菜单覆盖了「拉新→追踪→转化→结算→分析」的全链路数据，管理者不是在「凭感觉运营」，每一笔佣金支出都有完整的访问→转化→结算链路可追溯。
风险控制：防刷设置、排除规则和访问日志的设备指纹信息，从规则层面和技术层面双重保障平台利益，有效降低恶意刷单带来的经济损失。
五、适用人群
龙霄加盟推广插件最适合以下场景：正在使用龙霄主题搭建多语言电商平台（如跨境独立站、垂直品类电商、数字商品平台）的站点管理者，尤其是那些希望建立自有加盟推广体系、降低营销获客成本、精细化追踪推广效果的运营团队。插件同时也适用于需要为内容创作者、KOL 和社群团长提供标准化推广工具和佣金结算机制的平台型站点。
