@wildbuck/core-usage-event-frontend

Buck 产品使用事件采集 helper。默认关闭，业务应用需要产品使用分析时由后端配置和 client-meta 统一驱动前端 bootstrap。

import {
  bootstrapUsageEventsFromClientMeta,
  createModuleUsageTracker,
} from '@wildbuck/core-usage-event-frontend';

await bootstrapUsageEventsFromClientMeta();

const tracker = createModuleUsageTracker('security-setting', {
  pages: {
    passwordPolicy: {
      featureCode: 'password-policy',
      pageCode: 'password-policy-page',
      routeName: 'security-setting.password-policy',
    },
  },
  features: {
    passwordPolicyConfig: {
      featureCode: 'password-policy-config',
      pageCode: 'password-policy-page',
      routeName: 'security-setting.password-policy',
      viewActionCode: 'open-config',
    },
  },
});

await tracker.trackPage('passwordPolicy');
await tracker.trackOpen('passwordPolicyConfig');
await tracker.trackAction('passwordPolicyConfig', 'save', () => savePasswordPolicy());
await tracker.trackActionResult('passwordPolicyConfig', 'cancel', 'CANCELLED');

configureUsageEvents(...) 仍保留用于测试、迁移或特殊部署覆盖。业务常规接入不要重复声明 enabled/appCode/endpoint，避免和后端 brick.usage-event.* 配置形成两个事实来源。

模块页面优先使用 createModuleUsageTracker(moduleCode, matrix)。模块只维护稳定事件矩阵和模块级 tracker，页面进入使用 trackPage(pageKey)，抽屉或详情进入使用 trackOpen(featureKey, actionCode?, result?)。保存、轮转、授权等 async 动作用 trackAction(featureKey, actionCode, asyncFn) 包裹，由 helper 自动按执行结果记录 SUCCESS 或 FAILURE；已由业务流程算出结果的动作统一使用 trackActionResult(featureKey, actionCode, result)，不要再创建模块本地 success/failure wrapper。

只允许提交 Buck usage event 白名单字段。moduleCode、featureCode、pageCode、actionCode 使用小写 kebab-case；routeName 使用小写点号或短横线形态；subjectHash 只允许不可逆摘要，例如 sha256:<hex>；roleCodes 最多 32 项并会按顺序去重。

姓名、手机号、身份证号、token、密码、密钥、请求体、表单内容、附件内容和业务对象明文不应进入使用事件。校验失败和发送失败都不会阻断业务页面主流程。

collect endpoint 默认复用宿主认证、鉴权、网关和传输安全链路，不是匿名日志入口。400、401、403、413 或网络失败会按 fail-open 处理，可通过 onError 诊断。