KnowSphere 主题集成指南

场景一：文章与集合付费墙

原生文章页输出 post.content.content，让后端决定完整内容或试看。分类、标签等集合页由插件注入的路由付费墙处理；主题如果使用特殊列表容器，应在插件付费墙设置里配置正确的内容选择器。

保持文章/分类 metadata.name 与 slug 区分。访问检查可能返回集合购买目标 purchaseTargetType、purchaseTargetName；按这些字段建单，而不是总用当前文章 ID。下单、金额、优惠和权益计算只认服务端结果。

手动创建付费墙时，新版参数使用 unlock-methods JSON，旧的 type、price、level 不是等价输入。通常应保留插件生成的组件而非自行重复挂载。

场景二：会员与订单

会员列表是 Flux，订单是分页 Mono：

<div th:with="plans=${knowSphereFinder.listMembershipPlans().collectList().block()}">
  <article th:each="plan : ${plans}">
    <h2 th:text="${plan.title}"></h2>
  </article>
</div>
<div th:with="result=${knowSphereFinder.listMyOrders(1, 10).block()}">
  <p th:if="${result == null or #lists.isEmpty(result.items)}">暂无订单</p>
  <article th:if="${result != null}" th:each="order : ${result.items}">
    <span th:text="${order.orderNo}"></span>
  </article>
</div>

付款弹窗里的 amount 是显示数据，不能用于决定服务端扣款。关闭弹框要停止轮询；支付失败、处理中、取消和退款分别展示，不将一个成功事件当作权益发放依据。

场景三：评论与评论解锁

<ks-comment-widget group="content.halo.run" kind="Post" version="v1alpha1"
  th:attr="name=${post.metadata.name}"></ks-comment-widget>

name 使用当前资源 metadata.name。不要同时挂载多个评论系统的提交区。评论是否允许匿名、是否先审核和验证码由站点设置决定。解锁凭证只发给实际提交评论的浏览器，凭证是 HttpOnly Cookie；主题不得在 localStorage 保存或模拟它。

场景四：暗色模式和样式

:root {
  --ks-border-radius-lg: 16px;
  --ks-paywall-article-radius: 16px;
}
html.dark, html[data-theme="dark"] {
  --ks-paywall-article-radius: 16px;
}

CSS 自定义属性可以穿透 Shadow DOM。外部选择器不能直接修改组件内部节点，不依赖未经公开的内部 class。完整变量见组件参考。

场景五：可选集成与缓存

插件不存在时保留普通主题内容；插件存在且拒绝访问时显示服务端提供的试看。不能把“没有插件”和“用户无权”合并为直接显示原文。

不要将带用户权益的 HTML 或 /uc.api... 响应作为公共 CDN 缓存。更换账号、退出登录、退款后再次读取权益。站点域名、HTTPS、代理转发头和支付回调应一起验收。

阅读支付部署、API 权限与 FAQ。