主题商城：内置页面、Finder 与公开接口

适用版本：产品管理插件 3.1.0；内容依据当前源码核对，更新日期：2026-10-10。

方案选择

主题负责展示和购买跳转。订单创建、支付和权益交付继续由产品插件与用户中心处理。

使用内置页面

确认产品已发布，在主题导航添加 /product，检查列表、类型、分类、搜索、分页和详情。主题可提供 product.html、product-detail.html 同名模板覆写结构；保留路由及所需注入。品牌信息使用当前站点名称。

使用 Finder

<section th:with="products=${themeProductFinder.list('mall', 'PHYSICAL', '', '', 1, 12)}">
  <article th:each="product : ${products.items}">
    <a th:href="@{${product.detailUrl}}" th:text="${product.name}">商品名称</a>
    <strong th:text="${product.displayPrice}">价格</strong>
    <a th:if="${product.purchasable}" th:href="@{${product.purchaseUrl}}">购买</a>
  </article>
</section>

Finder 还提供 list(page,size)、按 scope 查询、getByKey(key) 等方法，返回主题展示模型。少量推荐位可用 listAll；动态分页场景使用接口。

使用公开接口

GET /apis/public.product.muyin.site/v1alpha1/theme-products/list?scope=mall&productType=PHYSICAL&page=1&size=12
GET /apis/public.product.muyin.site/v1alpha1/theme-products/{key}

全部产品使用 scope=all，授权产品使用 scope=license，卡密商品使用 scope=mall&productType=CARD_KEY。设置了公开 API Token 时，受保护的展示接口需带 X-Api-Token。该 Token 用于公开展示访问，不能代替写入凭据。

验收与限制

使用返回的 detailUrl 与 purchaseUrl，保留推荐码透传。未发布产品不正常展示，公开分类需启用；详情不存在时检查 Key 与发布状态。模板使用展示字段，避免依赖后台原始资源。Finder 不需要浏览器 Token 请求头；自建浏览器接口页则需处理 Token 和跨域条件。

相关文档

• 编辑器产品块与展示模板
• 浏览、购买产品与查看我的订单