应用安装与活跃统计

apps 扩展补齐了市场转化漏斗：浏览与下载此前已公开，但在上报安装与启动之前，无从得知某个已上架应用是否真的被采用、是否仍在运行、版本是否在漂移。这些遥测数据完全归扩展私有（ext_apps_install_event），不进入 APay 核心 Schema。

它记录四类信号：

层级事件来源
漏斗顶端download安装包分发接口在交付已校验安装包时由服务端自动记录
采用install安装端/客户端在首次安装成功时按设备上报一次
活跃launch已安装客户端每次启动时上报
生命周期update、uninstall安装端/客户端上报

公开上报接口（POST /api/public/plugins/apps/telemetry）

供 Shopark 安装器与已安装客户端 fire-and-forget 调用。接口刻意宽松：限流与校验失败都以 JSON body 返回，绝不抛 5xx，因此遥测异常永远不会阻塞客户端启动或安装。

请求体：

字段类型必填说明
eventstring是install、launch、update、uninstall 之一
uniqueNamestring是目录条目的 unique_name（小写 kebab-case）
installIdstring是8–128 位的 URL 安全字符（A-Za-z0-9_-）；每次安装生成新 id，故重装单独计数
versionstring否已安装版本，最多 64 字符
osstring否最多 32 字符
archstring否最多 32 字符
curl -X POST https://yourdomain.com/api/public/plugins/apps/telemetry \
  -H 'content-type: application/json' \
  -d '{"event":"install","uniqueName":"stripe","installId":"device-2f9a1c04","version":"1.2.0","os":"macos","arch":"arm64"}'

{ "code": 0, "msg": "ok", "data": { "recorded": true } }

接口只接受存在于目录中的 uniqueName（匹配 unique_name 或 slug），未知应用返回 code: 404。

服务端下载计数

POST /api/public/plugins/apps/package 在某个条目解析为已登记且未撤回的版本、即将返回签名镜像之前，记录一条 download 事件。写入为尽力而为：失败仅记录日志，绝不改变下载响应。

后台聚合接口（GET /api/admin/plugins/apps/catalog/telemetry）

与「应用管理」页共用 catalog 能力。查询参数 days（1–365，默认 30）设定统计窗口。

{
  "windowDays": 30,
  "generatedAt": "2026-01-20T12:00:00.000Z",
  "totals": { "installsAllTime": 1840, "installs": 212, "uninstalls": 9, "downloads": 640, "active7d": 1180, "active30d": 1602 },
  "apps": [{ "uniqueName": "stripe", "name": "Stripe Connector", "version": "1.3.0", "installs": 210, "active": 1590, "downloads": 620, "uninstalls": 9 }],
  "daily": [{ "date": "2026-01-20", "installs": 8, "active": 1150, "downloads": 27 }],
  "versions": [{ "uniqueName": "stripe", "version": "1.3.0", "installs": 196 }]
}

计数按 installId 去重：installs 统计窗口内安装过的去重设备数，active 统计所选 days 窗口内触发过 launch/update 的去重设备数，daily 按站点配置时区（settings.timezone，支持 SQLite/PostgreSQL/MySQL 三方言）按日聚合，versions 按每台设备的最新生命周期事件（install/update 迁移至最新版本，若最新事件为 uninstall 则剔除）统计当前已安装版本分布，且服务端会自动关联 ext_apps_catalog 补齐每个应用的 name 与当前 version。

去重与保留策略

  • install 在 (uniqueName, installId) 上终身只记一次；重装会生成新 installId 并重新计数。
  • 重复的 launch/update/uninstall 在一小时窗口内折叠为单行，卡死的客户端无法刷表。
  • download 事件从不去重。
  • 原始事件在 180 天后向前单向清理；守卫运行 node scripts/check-app-install-telemetry.mjs。