Shipping Restriction Pro 使用说明文档

一、插件简介

Fluence Shipping Restriction Pro 是一款基于 WooCommerce 的运费/购买限制插件。
它可以根据 产品、分类 和 国家/地区 设置配送限制规则，在结账时：

• 阻止结账（显示错误并禁止下单）
• 隐藏下单按钮（用户无法提交订单）
• 自定义提示消息（支持动态变量如产品名称、国家）

同时提供规则命中统计图表，方便分析哪些限制最频繁触发。

---

二、环境要求

• WordPress 5.6 或更高版本
• WooCommerce 6.0 或更高版本
• PHP 7.4 或更高版本（推荐 PHP 8.0+）

⚠️ 插件完全依赖 WooCommerce，请确保 WooCommerce 已激活，否则后台会显示错误提示且功能不可用。

---

三、安装与激活

1. 将插件文件夹 fluence-shipping-restriction-pro 上传至 /wp-content/plugins/ 目录。
2. 在 WordPress 后台「插件」页面找到 Fluence Shipping Restriction Pro，点击「激活」。
3. 激活后，左侧菜单栏会出现 Shipping Restriction 图标（一个盾牌），点击进入插件主界面。

💡 如果菜单没有出现，请检查 WooCommerce 是否已激活，并刷新后台页面。

---

四、核心功能与操作指南

4.1 创建一条限制规则

在插件主界面，找到 「Create Rule」（创建规则）卡片，按以下步骤填写：

字段	说明	示例
Rule Name	规则的名称，用于后台识别和统计	“美国 - 高端产品禁运”
Products	选择要限制的具体商品（可多选，支持 Ajax 搜索）	搜索 MacBook Pro 并选中
Categories	选择要限制的商品分类（可多选）	“电子产品”、“保健品”
Countries	选择哪些国家/地区适用此规则（可多选）	US、CA
Mode	限制模式： • Block Checkout：阻止结账（显示错误并阻止下单） • Hide Order Button：隐藏「Place order」按钮	Block Checkout
Message	自定义提示消息，支持变量： {{product_name}} – 触发规则的商品名 {{country}} – 用户的国家/地区代码	“{{product_name}} 不可配送至 {{country}}，请移除。”

填写完成后，点击 Save Rule 按钮。保存成功后页面会自动刷新，新规则将出现在下方的 Existing Rules 列表中。

📌 注意：一条规则可以同时包含产品和分类（取并集）。即：购物车中只要包含任一指定产品或任一指定分类的商品，就会触发该规则。

4.2 管理已有规则

• 查看规则列表：在「Existing Rules」表格中，可以看到每条规则的名称、限制的国家（超出3个会折叠显示）、命中次数（Hits）。
• 命中次数统计：每当用户在前台触发了该规则（被阻止或按钮被隐藏），Hits 会自动加1，用于分析高频限制规则。
• 删除/编辑：当前版本未提供可视化的删除/编辑按钮，如需修改或删除，可通过 WordPress 的「设置」→「所有设置」页面找到选项名 fsrp_rules_v2，编辑其值（高级用户），或重新安装插件清空数据。

4.3 统计图表

在页面顶部 Statistics 区域，会以柱状图展示每条规则的命中次数（Hits）。
如果没有数据，图表区会显示一段提示文字。

---

五、前台效果说明

5.1 阻止结账模式（Mode = Block Checkout）

• 当用户购物车中包含违规商品，且其配送/账单国家属于限制国家时：
  • 在结账页面顶部（或购物车页面）会显示红色的错误消息，内容为你设置的自定义消息。
  • 用户无法提交订单（结账流程被中断）。
• 示例消息：
  "This product is not available for delivery to US: MacBook Pro"

5.2 隐藏下单按钮模式（Mode = Hide Order Button）

• 当触发规则时，结账页面的 「Place order」 按钮会被 CSS 隐藏（用户不可见）。
• 你可以通过自定义消息告知用户原因（虽然按钮隐藏，但消息仍会显示）。
• 该模式常用于“仅展示但不允许下单”的场景，例如库存不足或地区限制提示。

注意：两种模式下，命中规则都会增加该规则的 Hits 计数。

---

六、高级说明与常见问题

6.1 规则匹配逻辑

• 插件会遍历购物车中所有商品，对于每个商品：
  • 获取商品 ID（如果是变体商品则取父级 ID）
  • 获取商品所属的所有分类 ID
• 然后遍历所有规则，检查：
  • 用户的国家是否在规则的 Countries 列表中
  • 商品的 ID 是否在规则的 Products 列表中 或 商品的分类 ID 与规则的 Categories 有交集
• 一旦匹配命中，立即停止检测并触发限制。

6.2 国家检测顺序

插件按以下优先级获取用户的国家：

1. 收货国家（shipping country）
2. 账单国家（billing country）
3. WooCommerce 默认商店国家（base country）

6.3 消息变量支持

在自定义消息中，可以使用：

• {{product_name}}：触发规则的商品名称（如果购物车多个商品命中，只会显示第一个命中的商品名）
• {{country}}：用户的国家代码（如 US、GB）

6.4 保存规则后没有立即生效？

• 规则保存后会实时生效，无需额外操作。如果发现未生效，请检查：
  • 购物车中确实包含指定产品或分类。
  • 用户的国家/地区与规则中设置的国家匹配（注意大小写，国家代码为 ISO 3166-1 alpha-2，如 US）。
  • 清空浏览器缓存或 WooCommerce 会话（可尝试注销后重新登录）。

6.5 如何删除所有规则？

删除选项 fsrp_rules_v2：

• 进入 WordPress 后台 → 「设置」→ 「所有设置」（如果看不到，安装插件 “Custom Settings” 或直接访问 /wp-admin/options.php）
• 找到 fsrp_rules_v2，将其值改为空数组：[]
• 或使用 WP CLI：wp option update fsrp_rules_v2 '[]' --format=json

警告：直接操作 options.php 需谨慎，避免误删其他配置。

6.6 兼容性说明

• 插件不会修改运费计算方法，仅拦截下单流程或隐藏按钮。
• 与大多数缓存插件（如 WP Rocket、LiteSpeed Cache）兼容，但建议在排除规则页面时不要对结账页面进行强缓存。
• 支持多语言（可通过 .pot 文件翻译，但当前版本仅提供英文界面）。

---

七、技术支持与反馈

• 如果你遇到任何问题（如后台不显示、PHP 错误、规则不生效），请先启用 WordPress 调试模式（WP_DEBUG）查看具体报错。
• 确保 WooCommerce 已更新到最新稳定版。
• 你可以通过插件作者邮箱（插件头部 Author 字段）获取支持。