主题组件、接口与权限

适用版本：会员插件 1.5.0 · 核对日期：2026-10-22

用途

让主题在文章页展示读者活动，在分享链接中展示公开护照，并为可信集成提供读者俱乐部接口与权限边界说明。

前置条件

主题正常输出 Halo 模板页脚；会员插件已启用且产品授权有效。调用用户中心接口需要登录态，公开护照接口允许匿名只读。自定义角色需要获得对应的非资源 URL 授权。

操作入口

插件自动注入 member-club-widget.js；主题可提供显式挂载点；接口前缀为 /apis/{uc|console|public}.member.muyin.site/v1alpha1/club/；OpenAPI 契约位于 api-docs/openapi/v3_0/readerClub.json。

操作步骤

无需手动引入脚本：页脚会加载 member-club-widget.js?version=<插件版本>，并调用 window.memberClub.init({postName, ucUrl})。
文章页会自动追加活动宿主。存在显式 [data-member-club-post] 宿主时不再自动追加；找不到 article 或 main 容器时使用右下浮动卡片。
需要固定位置时在主题模板中加入：

<div data-member-club-post="文章资源名"></div>
<div data-member-club-passport="公开护照标识"></div>

追加 data-member-club-floating 可改为浮动卡片。

分享链接 /?member-passport=<公开护照标识> 会自动创建浮动护照卡片；护照未公开或标识无效时显示不可查看提示。
自定义交互可调用 init(config)、getPassport(publicId)、getActivities()、activityAction({activityId, action, stepId?, answer?})；主题动态渲染页面后重新调用 init({postName, ucUrl})。
服务端集成按接口分组调用：用户中心 10 个操作（me、profile、claim、care、memories、activities、activity-action、wishes、wish、vote），控制台 8 个操作（items、item、grant、activities、activity、attendance、wishes、moderate-wish），公开 1 个操作（passport）。TypeScript 客户端由契约生成在 ui/src/api/generated-club。

交互示例

const views = await window.memberClub.getActivities();
const target = views.find((view) => view.activity.type !== "MILESTONE");
if (target) {
  await window.memberClub.activityAction({
    activityId: target.activity.id,
    action: "JOIN",
  });
}

预期结果与核对

文章页出现「这篇文章的小旅程」卡片，只列出绑定当前文章的步骤；已完成的步骤显示完成标记且不再提供输入。公开护照卡片显示昵称、简介、佩戴物和花园成长，不显示积分、订单与活动历史。

限制与注意事项

组件内容渲染在 Shadow DOM 中，主题样式不会穿透，探测内容需读取宿主元素的 shadowRoot。所有俱乐部响应带 no-store，公开护照未公开时返回不存在，不缓存。答案与内部密钥不出现在任何响应中。链接只接受站内路径或 HTTPS。插件不向读者授予原始扩展资源权限：用户中心接口从登录态确定身份，控制台接口沿用会员控制台权限，公开护照仅提供匿名只读。当前会员 MCP 工具不包含读者俱乐部操作。

常见问题

主题看不到卡片？ 检查页脚是否输出、活动是否已发布且在时间范围内、步骤是否填写了当前文章资源名。
匿名打开分享链接提示无法查看？ 读者未开启公开护照，或站点匿名角色未正确聚合公开护照接口。
出现两个活动卡片？ 请检查主题是否重复添加了宿主元素，或页面重复加载了组件脚本。
自定义角色调用接口 403？ 为该角色补充对应的俱乐部非资源 URL 授权。