PluginProduct 功能介绍与操作教程

适用项目：PluginProduct 产品管理插件
文档口径基于当前仓库代码与文档分析：CONTEXT.md、docs/intro-*.md、docs/usage-guide.md、docs/theme-adaptation-guide.md、Scheme、Endpoint、Console/UC 页面与 settings.yaml。
一句话讲明白：这不是“产品表单插件”，而是把 Halo 站点改造成产品销售、订单支付、自动履约和权益管理平台的商业化插件。

功能体验

功能地图

当前插件围绕 产品、订单、授权、商城履约、卡密、营销、外部对接、主题展示 做了一套完整闭环。

控制台入口在 /console/product，当前代码中包含 12 个标签：

用户中心入口在 /uc/product，当前代码中包含 6 个标签：

快速上手

1. 安装并启用 PluginProduct。

2. 如需真实支付，在插件设置的 支付设置 中开启支付，并配置 PluginPayment 的支付宝或微信支付渠道。

3. 如需余额、积分、推荐码、会员折扣，安装并配置 PluginMember。

4. 进入 /console/product 的 分类数据 创建分类。

5. 进入 产品管理 创建产品，选择 LICENSE、PHYSICAL 或 CARD_KEY。

6. 如果是授权产品，进入 版本数据 发布版本；如果是卡密商品，进入 卡密库 导入卡密。

7. 发布产品后，用户可在 /uc/product 的 商城数据 购买，主题侧也可通过 /product 展示。

8. 支付成功后，系统根据产品类型自动进入授权生成、实物待发货或卡密发放流程。

1. 产品池、分类与版本

功能介绍

插件的核心入口是 产品。当前产品类型有三种：

配套模块：

• 分类数据：给产品做业务分组，支持启用/禁用和排序。

• 版本数据：面向授权产品，管理版本号、兼容范围、发布说明、文档链接、下载链接。

• 产品块：编辑器中可插入产品信息块，在文章或页面里展示产品。

• 主题商城：/product 和 /product/{key} 提供前台商城列表和详情页。

操作教程

1. 进入 /console/product。

2. 打开 分类数据，创建分类，建议先建“插件”“主题”“服务”“卡密”等业务分类。

3. 打开 产品管理，点击创建产品。

4. 填写产品标识、名称、Logo、描述、作者、分类、排序和发布状态。

5. 选择产品类型：

   • 授权产品：配置日付、周付、月付、季付、年付、永久等价格策略。

   • 实物商品：配置永久价格、库存和库存预警。

   • 卡密商品：配置永久价格、库存预警和是否自动发放。

6. 保存并发布。

7. 如果是授权产品，进入 版本数据 创建版本并上线。

8. 到用户中心 商城数据 或主题侧 /product 验证展示。

注意事项

• productKey 是核心业务键，后续订单、授权、优惠、版本和对接规则都会引用它，别随手改。

• 实物商品和卡密商品当前按商城语义处理，价格策略一般使用永久价格。

• 主题侧不要直接扒 CRD 字段，优先使用主题展示接口或 themeProductFinder。

2. 授权管理与授权校验

功能介绍

授权产品支付成功后，会形成用户可使用的 授权。授权可绑定：

• 产品标识

• 授权域名

• 授权用户

• 授权证书

• 授权时间和过期时间

• 授权状态：UNAUTHORIZED、AUTHORIZED、EXPIRED

校验方式有两类：

操作教程

1. 管理员先创建并发布授权产品。

2. 用户在 商城数据 中购买授权产品。

3. 支付成功后，系统创建授权相关订单和权益。

4. 用户进入 授权数据，按产品创建或查看授权。

5. 填写授权域名、授权用户等信息。

6. 需要离线校验时，点击生成授权证书。

7. 外部系统调用在线校验接口或使用证书做离线校验。

管理员处理

• 在控制台 授权数据 可查看全部授权。

• 可手动创建、更新或删除授权。

• 可开启定时清理过期授权。

• 授权过期通知模板为 product-auth-expired-notification。

3. 订单中心与支付

功能介绍

插件把管理入口做了统一，但底层模型不乱合并，这点很关键，不然订单迟早搅成一锅酸菜汤。

支持的支付能力：

操作教程：配置支付

1. 进入插件设置的 支付设置。

2. 开启支付功能。

3. 选择支付宝、微信、余额或积分支付渠道。

4. 如果启用积分支付，配置会员积分内部调用令牌和积分换算比例。

5. 设置订单状态同步 Cron。

6. 保存配置。

操作教程：用户下单

1. 用户进入 /uc/product 的 商城数据。

2. 选择产品和价格策略。

3. 实物商品需要填写收货信息。

4. 可输入优惠券或推荐码。

5. 选择支付方式。

6. 支付完成后，系统同步订单状态。

7. 根据产品类型进入授权、发货或卡密交付流程。

订单状态

授权产品订单状态：

商城订单状态：

4. 商城履约：实物商品与卡密商品

功能介绍

商城模块面向实物商品和卡密商品。

实物商品流程：

1. 用户浏览商品。

2. 填写收货信息。

3. 创建商城订单和订单项。

4. 支付成功后进入待发货。

5. 管理员填写快递公司和运单号。

6. 订单进入已履约。

卡密商品流程：

1. 用户浏览卡密商品。

2. 创建商城订单。

3. 支付成功后自动从卡密库存中分配可发放卡密。

4. 用户在 我的卡密 查看。

5. 如果库存不足或发放失败，管理员可补货后重试。

操作教程：后台补录商城订单

1. 进入控制台 订单中心。

2. 切换到实物商品订单或卡密商品订单。

3. 创建完整商城订单，选择商品、数量、用户和支付状态。

4. 待支付订单可编辑商品和数量。

5. 支付后的订单不能再随意改商品和数量，别硬拧，硬拧就容易账物不一致。

操作教程：实物发货

1. 进入 订单中心 的实物商品订单视图。

2. 找到待发货订单。

3. 打开发货操作。

4. 填写快递公司和运单号。

5. 保存后用户可在我的订单中查看物流信息。

操作教程：卡密重试

1. 先进入 卡密库 补充该商品可发放库存。

2. 回到 订单中心 的卡密商品订单视图。

3. 找到失败订单项。

4. 点击重新发放卡密。

5. 到 我的卡密 或订单详情中确认交付结果。

5. 卡密库

功能介绍

卡密库由两个资源配合：

当前卡密状态：

操作教程：导入卡密

1. 创建并发布卡密商品。

2. 进入控制台 卡密库。

3. 点击导入卡密。

4. 选择卡密商品。

5. 输入批次名称。

6. 粘贴卡密数据，支持类似：

CODE-001,SECRET-001
CODE-002----SECRET-002

7. 查看导入预览。

8. 确认导入。

9. 到卡密列表确认状态为可发放。

交付规则

• 卡密商品开启自动发放后，支付成功会自动扣减可发放库存。

• 已发放卡密会记录订单 ID、订单项 ID、用户 ID 和发放时间。

• 库存不足时订单会进入失败语义，需要补货后重试。

6. 优惠营销

功能介绍

营销体系包含四类能力：

优惠券类型：

操作教程：创建优惠券

1. 进入控制台 优惠数据。

2. 点击创建优惠券。

3. 填写优惠券名称、类型、优惠力度和有效期。

4. 选择适用产品和价格策略，不限制则留空。

5. 配置总使用次数和是否允许自助领取。

6. 保存。

7. 用户进入 UC 的 优惠数据 领取或查看优惠券。

操作教程：启用推荐码和会员折扣

1. 安装并启用 PluginMember。

2. 在插件设置 优惠设置 中开启推荐码优惠或会员折扣。

3. 在具体产品中确认推荐码、会员折扣开关没有被关闭。

4. 用户购买时输入推荐码，系统会校验不能使用自己的推荐码。

5. 如果会员折扣开启，系统按配置进行会员价或组合优惠计算。

附赠策略怎么配

旧设置页仍保留 附赠策略 repeater，用于兼容旧入口。当前更推荐：

1. 进入 授权产品订单动作规则。

2. 创建规则。

3. 动作类型选择 BONUS_ORDER。

4. 选择主产品、附赠产品和附赠时长策略。

5. 保存启用。

6. 主订单支付成功后，系统自动创建 0 元附赠产品订单。

7. 支付动作自动化

功能介绍

授权产品订单动作规则 在授权产品订单支付成功后触发。当前动作类型：

规则可按以下条件过滤：

• 产品 Key

• 价格策略

• 是否仅真实支付订单

• 排序

• 最大重试次数

• 重试间隔

执行结果会写入 授权产品订单动作记录，状态包括：

操作教程：创建通知规则

1. 进入 授权产品订单动作规则。

2. 点击新增。

3. 填写规则名称，启用规则。

4. 选择产品和价格策略，留空表示更宽泛匹配。

5. 动作类型选择 NOTIFICATION。

6. 配置是否通知下单用户、指定用户、标题模板和正文模板。

7. 保存。

操作教程：创建 Webhook 规则

1. 新增规则。

2. 动作类型选择 WEBHOOK。

3. 填写 URL、HTTP 方法、请求头、密钥和超时时间。

4. 使用变量模板组织请求体。

5. 先点预览，确认请求体。

6. 再点测试，确认外部系统能收到。

7. 保存启用。

操作教程：创建附赠订单规则

1. 新增规则。

2. 动作类型选择 BONUS_ORDER。

3. 选择附赠产品列表。

4. 选择附赠时长策略：日、周、月、季、年、永久或跟随主产品。

5. 保存启用。

排障

• 创建规则时 actionType 是必填字段，接口报 Field 'actionType' is required 时，先检查前端表单是否真的提交了 actionType，别只看界面像选了。

• Webhook 失败先看动作记录里的请求快照、响应码和错误信息。

• 开启支付动作失败重试 Cron 后，失败记录会按规则重试。

8. 外部商城对接与权益认领

功能介绍

外部商城对接用来把外部商品购买结果转成本站权益。核心资源：

履约动作：

认领类型：

操作教程：配置商城对接规则

1. 进入 Halo商城对接规则。

2. 点击创建规则。

3. 填写外部商品 ID 和外部规格 ID。

4. 选择内部产品 Key 和价格策略。

5. 选择履约动作。

6. 如果创建优惠券，补充优惠券模板。

7. 选择响应来源。

8. 保存启用。

操作教程：用户认领权益

1. 外部商城支付完成后调用插件公开发放接口。

2. 插件生成发放记录。

3. 用户进入 UC 的 商城认领。

4. 输入外部订单信息。

5. 系统解析可认领权益。

6. 用户点击认领。

7. 权益进入我的订单、授权数据或优惠数据。

排障

• 发放失败先看 Halo商城发放记录。

• 检查外部商品 ID 和规格 ID 是否与规则完全匹配。

• 检查履约动作是否需要额外模板，比如创建优惠券时需要优惠券模板。

9. 主题展示、公开接口与系统配置

主题展示能力

插件提供四种主题侧展示方式：

操作教程：使用内置商城页

1. 确认产品已发布。

2. 在主题导航中添加 /product。

3. 打开 /product 检查产品列表、分类筛选、类型筛选和搜索。

4. 打开 /product/{key} 检查详情页、价格、库存、版本和购买入口。

操作教程：使用 Finder

适合服务端渲染：

<section th:with="products=${themeProductFinder.list('mall', 'PHYSICAL', '', '', 1, 12)}">
  <article th:each="product : ${products.items}">
    <a th:href="https://auth.muyin.site/@{${product.detailUrl}}" th:text="${product.name}">商品名称</a>
    <strong th:text="${product.displayPrice}">¥0.00</strong>
  </article>
</section>

操作教程：使用公开接口

常用接口：

GET /apis/public.product.muyin.site/v1alpha1/theme-products/list
GET /apis/public.product.muyin.site/v1alpha1/theme-products/{key}
GET /apis/public.product.muyin.site/v1alpha1/product-category/list
GET /apis/public.product.muyin.site/v1alpha1/product-version-info-page/list

类型筛选：

如果配置了公开 API Token，请求需要带：

X-Api-Token: your-token

系统配置

设置页分为四组：

定时任务：

通知模板：

权限边界：

数据模型总览

当前插件定义了 17 个主要 GVK 模型：

建议配置顺序

新站点建议按这个顺序来，别一上来先配 Webhook，主产品都没有你回调个啥，回调空气吗。

1. 配置通用设置和支付设置。

2. 配置服务条款、购买须知和客服信息。

3. 创建产品分类。

4. 创建授权产品、实物商品或卡密商品。

5. 授权产品发布版本。

6. 卡密商品导入卡密库存。

7. 创建优惠券或开启推荐码/会员折扣。

8. 配置订单动作规则：通知、Webhook、附赠订单。

9. 如有外部商城，再配置商城对接规则。

10. 最后接入主题商城或产品块展示。