docs(analytics): add Chinese guide and split delivery scope

Refs #989

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
This commit is contained in:
千乘妍 (Xiaoyaner) 2026-10-28 23:22:19 +08:00
parent 238b784110
commit 688b7ce18e
6 changed files with 364 additions and 23 deletions

View file

@ -0,0 +1,197 @@
# 前端动作统计接入指南
## 1. 先了解边界
SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集、不加载统计 SDK、不发送事件。可选 helper 把允许的原生交互转换成 `{ id, event }`,再交给部署方选择的 adapter。点击下载只表示下载意图,不表示下载、安装成功;提交发布也不表示发布成功。部署方负责授权、隐私合规、保留期限和平台安全。
本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](../openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约](frontend-analytics.md)为准。
## 2. 选择接入路径
### 路径 A:复用已有统计平台
先确认平台接收地址、公开站点标识、授权策略和 CSP。不要把平台管理密钥放到浏览器。平台不受支持时,需要部署方编写自己的 adapter;当前版本不能只填平台名字就接入任意平台。
1. 复用 [helper](examples/analytics/observe/v1/skillhub-intents.mjs),不要修改业务页面或引入厂商 SDK。
2. 参照 [Umami adapter](examples/analytics/observe/v1/umami-adapter.mjs)实现 `send(intent) -> Promise<void>` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。
3. 由 adapter 验证平台参数、清洗最终发送字段、管理 SDK 加载和超时。不要只清洗 helper 回调后就信任 SDK 自动附加的 URL、标题或身份字段。
4. 在部署方入口中连接 helper 与 adapter,只有策略允许时才初始化:
```js
import { observeSkillhubIntents } from './skillhub-intents.mjs'
// adapter 由部署方创建;必须先确认当前授权。
const stopObserver = observeSkillhubIntents({
root: document,
onIntent: intent => adapter.send(intent),
})
function stop() { stopObserver(); adapter.stop() }
```
入口交付、同源代理、授权回调和 CSP 由部署方维护。下面的 edge 仅演示 Umami 两个端点;使用其他平台时,需要自行审核并替换 adapter 和代理端点。不要把平台管理界面代理到公开采集前缀。
### 路径 B:本地自托管 Umami 演示
前提:已有能正常使用的 SkillHub Web;已安装 Docker 和 Compose;能使用示例指定的 Umami 3.4.1、Postgres 16、Nginx 1.30.6 镜像;本机 8300 和 8081 端口空闲。所有 shell 命令从仓库根目录运行。示例会创建独立演示网络和临时数据库,不用于生产持久化。请在隔离环境运行。
先检查配置,再启动:
```sh
docker compose -f docs/examples/analytics/compose.yaml config
docker compose -f docs/examples/analytics/compose.yaml up -d
```
默认上游是 `host.docker.internal:80`,对应 release Compose 的 `WEB_PORT` 默认 80。这里是容器访问宿主机的 Web 入口,不是后端端口,也不是 edge 自己的 8081。若 Web 实际发布在 18080,使用:
```sh
SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 docker compose -f docs/examples/analytics/compose.yaml up -d
```
原生 Linux Docker 需要 `host.docker.internal` 映射,示例 edge 已包含 `extra_hosts: ["host.docker.internal:host-gateway"]`。Docker Desktop/OrbStack 已提供这个名字。宿主机 Web 必须监听容器可达的地址;如果防火墙或仅回环监听阻止访问,先调整可达性,或填写容器可以访问的其他 `host:port`。不要填写 `http://` 或 URL 路径。
打开 `http://localhost:8300`。首次演示登录是 `admin` / `umami`,立即改密码。示例公开的数据库口令和 APP_SECRET 也只能用于演示;生产需要独立密钥、持久化、备份和访问控制。
在 Umami 创建一个演示网站,记录网站 UUID。打开 `docs/examples/analytics/observe/v1/observer.mjs`:
1. 将全零 `website` 改为刚创建的网站 UUID。
2. 将 `enabled: false` 改为 `enabled: true`。
3. 将 `hasConsent()` 接入自己的当前授权判断。仅在隔离演示、明确允许采集时可暂改为返回 true;正式接入不能把它当作用户同意。
4. 按下一节配置 rules。示例额外的 `skill.example.open` 没有对应产品元素,不会凭空产生事件。
然后重建 edge,使单文件挂载更新可靠生效:
```sh
docker compose -f docs/examples/analytics/compose.yaml up -d --force-recreate edge
docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -t
docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -T
```
打开 `http://localhost:8081`,不要从原 Web 入口验收注入。本地演示可以修改 v1 文件;正式交付中同一路径的模块是 immutable 缓存,修改内容必须发布到新的版本目录并同步注入路径,不能覆盖旧版本字节。
## 3. 配置规则和增加动作
省略 `rules` 使用冻结的 `DEFAULT_RULES`,共 12 条:
| ID | 规则 |
| --- | --- |
| search.query.submit | submit |
| skill.card.open | card |
| suite.card.open | card |
| skill.download.request | click |
| skill.file.download | click |
| skill.command.copy | click |
| skill.prompt.copy | click |
| skill.publish.request | click |
| skill.publish.confirm | click |
| skill.publish.cancel | click |
| skill.delete.confirm | click |
| skill.delete.cancel | click |
显式传入 rules 会替换默认值,空对象表示没有动作。要保留默认值再增加已存在的动作,先合并:
```js
import { DEFAULT_RULES, resolveRules } from './skillhub-intents.mjs'
const rules = { ...DEFAULT_RULES, 'navigation.home.open': 'click' }
const { active, skipped } = resolveRules(rules)
console.table(skipped) // 只在本地检查,不发送这些诊断。
```
把 `active` 传给 helper 的 `rules`。也可在浏览器开发者工具 Console 中直接执行以下代码,无需编辑源码,就能查看无效项:
```js
const { resolveRules } = await import('/_skillhub-observe/v1/skillhub-intents.mjs')
console.table(resolveRules({ 'skill.example.open': 'drop' }).skipped)
```
应看到 `id: skill.example.open`、`reason: unknown rule type`。非法 ID、非字符串规则也会跳过;非法容器返回 `id: null` 的诊断和空 active。该检查只验证配置,不能证明 DOM 元素支持某类事件。
仅支持三种规则:
- `click`:普通按钮、链接;忽略 FORM、SELECT、TEXTAREA、非按钮 INPUT(包括文件选择器)。
- `submit`:只用于 FORM。点击提交和按 Enter 都归一到原生 submit;原生校验失败可能没有事件。
- `card`:已有 Enter/Space 处理的 DIV role=link,观察 click 和对应 keydown。helper 不会替应用增加键盘行为。
不支持的选择器、拖放、文件和裁剪行为不要硬填 click。未配置的动作不采集。`skill.detail.render` 是结构标签,不是自动页面访问量。
新增产品动作时,开发者在正确的现有元素上增加静态字面量 ID,再从仓库根目录运行:
```sh
node web/scripts/analytics-manifest.mjs --write
node web/scripts/analytics-manifest.mjs
```
审核生成的 [manifest](frontend-analytics-manifest.json) 差异和原生交互测试。部署方再加一条规则即可。ID 必须匹配 `^[a-z]+(?:\.[a-z]+){2,}$`:至少三段小写字母,不含数字、下划线或资源信息。已有 ID 含义冻结,不能把用户、技能名、版本、路径拼进去。manifest 是版本清单,不是运行时封闭枚举。
## 4. 部署、子路径和 CSP
edge 仅在 UI HTML 注入一个延迟执行的 module,不改变 API、登录、下载、静态资源或 runtime-config。server 级 `client_max_body_size 100M` 保留标准 Web 的 100 MiB 请求体上限;实际业务校验仍可能拒绝上传。不要在应用代理 location 覆盖成更小值。
正式启用前检查 Nginx 含 http_sub_module、`nginx -t` 成功,并审核 `nginx -T`。HTML 输入不能仍被上游 gzip/Brotli 压缩。示例禁用 HTML 缓存和旧校验器;启用或回退都应清理 CDN/浏览器旧 HTML。不要修改 API 或 immutable 资源的缓存规则。
根路径演示的 CSP 需要允许同源外部 module 和同源连接。保留原有 CSP;nonce-only 或 strict-dynamic 策略不能只靠同源满足。需要部署方协调每响应 nonce 或已批准的 hash/SRI;做不到就不要启用。不要加 unsafe-inline、unsafe-eval 或通配符。还要保留原安全头,注意 Nginx add_header 的 location 继承规则。
`/skillhub/` 等子路径不是只改一个 URL。先按正常部署方式配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/` 和匹配的同源 API base,再同时调整 UI location、无尾斜线重定向、旁路正则、模块目录/注入 src、两个 Umami 精确端点和 adapter prefix。edge 到 Web 的 proxy_pass 不带尾斜线,保留原 URI,不能再次重写。逐项配置见[英文契约的子路径映射](frontend-analytics.md#supported-sub-path-mapping)。OAuth、公网 HTTPS 和资源地址仍遵守原部署要求。
## 5. 验收:照这个顺序检查
下面命令假定根路径和默认 edge 端口。子路径时为所有采集 URL 加相同前缀;自定义端口时统一替换地址。
1. 检查模块确实由 edge 提供,不是 SPA 返回的 HTML:
```sh
curl -i http://localhost:8081/_skillhub-observe/v1/skillhub-intents.mjs
curl -i http://localhost:8081/_skillhub-observe/v1/missing.mjs
curl -I http://localhost:8081/skills
```
第一个应为 200、JavaScript MIME、nosniff 和 immutable。第二个应为非 HTML 的 404。第三个应为 200、Cache-Control: no-store,并保留原 CSP(若原部署配置了 CSP)。
2. 打开 edge 的 SkillHub 页面,在开发者工具 Network 勾选保留日志,筛选 `/_skillhub-umami/`。刷新后应加载 script.js,但没有自动 pageview 或 send。
3. 搜索框输入任意本地测试文字,点击搜索。应恰好有一条 `/_skillhub-umami/api/send` POST,响应 200。再按 Enter 搜索一次,应新增一条,不是两条。切换 Network 的 Payload 查看真正出站 JSON,不要只看回调。
4. JSON 只能包含 `{ type: 'event', payload: { website, name, data: { event } } }`。website 是配置的 UUID;搜索 name 为 search.query.submit,event 为 submit。不得出现搜索词、完整 URL、标题、referrer、身份或额外 data 字段。
5. 打开 Umami 网站事件页,选择当前时间范围,应看到 search.query.submit 和对应数量。平台处理可能稍有延迟;不能把 HTTP 200 单独当作入库证明。
6. 执行下面的 Console 命令后再搜索,页面仍能使用,但 Network 不得新增 send:
```js
window.skillhubAnalytics.stop()
```
stop 不能撤回已开始的 fetch。重新获准后才可调用 start();同一个 root 重复初始化保留第一次规则和回调,修改规则需要先 stop 再初始化。
7. 将入口恢复 `enabled: false`,重新创建 edge 并刷新新页面,再搜索:不得加载 script.js、产生采集回调或 send。完全不注入时也应零采集。最后在隔离演示中停止 Umami,再打开新页面搜索和打开技能卡片,应仍正常,无统计依赖导致的页面错误:
```sh
docker compose -f docs/examples/analytics/compose.yaml stop umami
```
验收后如需继续演示,使用上面的 up 命令恢复。不要为了测试停止共享平台或生产服务。
## 6. 故障排查
| 现象 | 常见原因 | 处理 |
| --- | --- | --- |
| module 404 | 未挂载模块,版本目录或子路径不一致 | 对照 nginx -T、挂载路径、注入 src 和相对 import,三份 mjs 都要可访问;不要回退到 index.html |
| MIME 报错或返回 HTML | 模块误入 SPA fallback,缺少 mjs MIME | 使用示例独立前缀、try_files 404 和 JavaScript MIME,保留 nosniff |
| CSP 拦截 | script-src/connect-src 不允许,或 nonce-only 策略 | 按原 CSP 的授权机制交付;不要删除 CSP 或放宽为通配符 |
| 上传 413 | 外层代理仍默认 1 MiB,或请求超过 100 MiB | 用 nginx -T 检查整条代理链;应用代理继承 100M,超过标准上限仍应拒绝 |
| 没有事件 | 走了原 Web 而非 edge,enabled/授权未开,UUID 错,规则未配置或宿主不支持 | 按第 5 节从模块、skipped、Network 到平台事件页逐步确认;检查时间范围;不要把结构标签当 pageview |
| edge 502 | Web 上游地址/端口错误,宿主不可达 | 核对 WEB_PORT、host-gateway、防火墙和监听地址;不要把后端或 edge 端口填成 Web 上游 |
| Umami 不可用 | SDK 404、超时、平台停止或网络故障 | 页面应继续正常;检查平台和代理日志,恢复后重新打开页面;没有重试补发保证 |
## 7. 升级、关闭和已知限制
升级时先比较新旧 manifest。已有 ID 语义不变;含义变化需要新 ID,重命名/删除必须有发布说明。消失的 ID 不再触发,新 ID 默认不自动加入规则。模块/SDK 升级要重新验证真实出站字段、stop 派发边界、并发发送、根/子路径和业务行为,不能只看构建成功。
临时关闭当前页用 stop();持久关闭把入口改回 enabled:false,并按版本发布规则更新、清理 HTML 缓存和刷新。彻底关闭则撤掉注入/edge,让访问回到正常 Web 入口,确认新 HTML 不引用模块、Network 无采集。关闭平台网站或封锁采集路由是额外控制,不能代替授权撤回。
结束本地演示(会删除演示数据库,先确认无需要保留的数据):
```sh
docker compose -f docs/examples/analytics/compose.yaml down -v
```
限制必须一起评估:
- 尽力发送,无重试、无持久队列,可能少计。SDK 加载期最多在内存暂存 20 条,默认最多等三秒;超额、失败、超时或 stop 都丢弃。已就绪发送彼此独立,不因一个请求挂起而阻塞后续动作。
- 示例固定 Umami 3.4.1。stop 的派发保护依赖此版本在 fetch 前同步序列化的顺序,升级必须重跑适配器测试和真实浏览器验收;不要同时加载第二个 Umami tracker。
- JSON 字段少不等于匿名传输。IP、User-Agent、Origin 仍到平台;SDK 还带网站、实际 hostname 和后续会话 cache 头。edge 去掉采集代理的 Cookie、Authorization、Referer,并使用 no-referrer。Umami 仍可能据传输元数据推导浏览器、系统、设备、地域和会话。
- SDK 在清洗前仍会在页面内读取标题、URL、referrer 和自身 localStorage 开关;通用 helper 不读取这些内容。平台日志、数据保留和权限需另审计,详见[隐私契约](frontend-analytics.md#privacy-and-integration-modes)。

View file

@ -1,8 +1,13 @@
# Passive frontend analytics attributes
For step-by-step setup, see the [Chinese integration guide](frontend-analytics-integration.md).
This document is the English contract reference. Configuration-only deployment is
planned in [PR-2](../openspec/changes/add-configurable-frontend-analytics/proposal.md);
the current examples remain deployment-owned and opt-in.
SkillHub exposes semantic HTML attributes for separately maintained, optional
collectors. It does not collect or send analytics by default. There is no SDK,
DataFinder dependency, vendor token, network reporter, app script loader or
vendor dependency, vendor token, network reporter, app script loader or
telemetry configuration switch. The application entrypoint and production Nginx
configuration are unchanged. Deployment owners control consent, script delivery,
retention, transport and compliance; this is not an official vendor integration
@ -221,9 +226,17 @@ From the repository root:
```sh
docker compose -f docs/examples/analytics/compose.yaml config
SKILLHUB_WEB_UPSTREAM=host.docker.internal:8080 docker compose -f docs/examples/analytics/compose.yaml up -d
docker compose -f docs/examples/analytics/compose.yaml up -d
```
The default Web upstream is `host.docker.internal:80`, matching the release
Compose `WEB_PORT` default of 80. Override `SKILLHUB_WEB_UPSTREAM` with the actual
reachable host:port if different. The edge's `extra_hosts` maps this hostname to
`host-gateway` on native Linux; Docker Desktop/OrbStack already provide it. The
host Web listener must be reachable from containers. The edge inherits the standard
server-level `client_max_body_size 100M` for application proxying (100 MiB); it does
not reduce uploads to Nginx's default 1 MiB.
This creates a demo network and ephemeral database, not production storage. Use
an isolated local Docker environment with available network pools. Open
`http://localhost:8300` for local setup only. Umami's default `admin` / `umami`

View file

@ -2,6 +2,29 @@
本变更在 PR #1010 上保留原贡献历史并合入最新 main,保留 footer 翻译及 Trans 登录协议。使用已有运行时配置比 Nginx HTML 注入更易自动交付;完整标签管理平台增加额外服务与权限体系,本期不采用。
## 分阶段交付与接口对齐
PR-1(#1010)仅完成被动标签、厂商中立 helper 与示例 adapter、edge 示例问题修正和中文接入指南。它不修改产品入口或部署开关,手工接入方式继续明确标为可选示例。PR-2 独立交付配置化加载、产品模块、runtime-config、同源代理和 Compose/Helm。两者可分别合并,Issue #989 仅在 PR-2 完成并验证后关闭。
PR-2 必须采用 PR-1 实际交付的接口,不能另起一套不兼容协议:
| PR-1 接口 | PR-2 采用方式 |
| --- | --- |
| `data-analytics-id` 匹配 `^[a-z]+(?:\.[a-z]+){2,}$`,由 manifest 索引 | 保持已发布 ID 含义冻结;manifest 不是运行时封闭枚举,不插值资源/身份信息 |
| `observeSkillhubIntents({ root, rules, onIntent }) -> stop` | controller 按授权安装委托观察;不改变页面原生事件和业务处理 |
| 冻结的 `DEFAULT_RULES`(12 条) | rules 省略用默认值,显式提供为替换,空对象不采集;增加默认规则需显式合并 |
| `resolveRules(rules) -> { active, skipped: [{ id, reason }] }` | 使用相同纯校验;非法容器的 id 为 null;诊断只留本地,不发送原配置 |
| 有限类型 `click`/`submit`/`card` | 保持宿主限制和原生事件边界;未知类型/ID 格式/不支持宿主跳过,不猜测选择、文件、拖放或裁剪事件 |
| intent 仅 `{ id, event }` | event 为原生 click/submit/keydown,不表示业务成功;同版本只允许增加可选的静态白名单字段,消费者忽略未知字段;破坏性变更另版本 |
| adapter `send(intent) -> Promise<void>`、`stop()` | send 消化异常、永不 reject;平台参数只归 adapter;停止后不得派发新请求,已开始 fetch 不可撤回 |
| 同 root 重复初始化保留第一次 config/callback 并返回相同 stop | 改配置先 stop 再初始化;旧 stop 不得撤掉新安装,stop 可重复调用;嵌套观察共享事件去重 |
配置映射:enabled=false 不安装观察、不加载 SDK;consent=denied 同样禁止初始化。enabled 与 consent 的联合判断由通用 controller 管理,不放进业务组件。rules 原样通过 resolveRules,保留 active/skipped 语义。adapter 仅选择静态注册 factory;adapterConfig 只交给所选适配层校验,不把 websiteId 等厂商字段提升到通用配置。PR-1 示例的 website/prefix 对应 PR-2 Umami 的 adapterConfig.websiteId/部署生成的同源前缀;PR-1 的 hasConsent hook 对应 PR-2 consent 和动态 start/stop。PR-2 新增默认关闭的模块加载边界,不能声称 PR-1 示例已具备产品配置化加载。
PR-2 将 helper 迁入 `web/src/features/analytics` 的单一产品源码,迁移而非复制,保留 PR-1 测试的全部断言,包括 grammar、有限规则、生命周期、隐私和 dispatch 边界。示例 adapter 仍不是任意远程 JS 插件机制。
## PR-2 产品设计(下列能力尚未在 PR-1 实现)
### 1. Stable configuration contract
- `SKILLHUB_WEB_ANALYTICS_CONFIG`:可选 JSON 对象,空值等同关闭。字段为 enabled(boolean,默认 false)、adapter(注册适配器名)、consent(`denied`/`granted`,默认 denied)、rules(可选动作→有限规则对象,省略沿用默认规则,显式空对象不采集)、adapterConfig(平台自有公开参数对象)。

View file

@ -2,8 +2,16 @@
Issue #989 / PR #1010 已提供被动动作标签、通用 helper 和独立平台适配示例,但部署方仍需修改 JS、提供文件和手工接入 Nginx。维护者确认新的交付目标:部署只填配置、尽量一次启动、文档可独立复现,同时控制对原业务的影响。此目标是原评审之后新增的正式产品能力,不将其描述为原贡献者返修遗漏。
## 分两次交付
- PR-1(#1010):完成被动标签、厂商中立 helper、示例 adapter、edge 上传上限与默认 Web 上游修正,以及可独立照做的中文接入指南。示例仍由部署方手工接入,不增加产品运行时开关。
- PR-2(后续 PR):交付下述配置化产品能力,包括 `web/src/features/analytics` 单一产品源码、runtime-config 可选加载、同源代理路由及 Docker/Compose/Helm 配置。Umami 是首个注册 adapter,通用配置和加载入口不绑定平台。
- 两个 PR 分别合并。Issue #989 保留到 PR-2 完成并验证后才关闭;PR-1 不自动关闭该 Issue。
## What Changes
以下产品加载和部署变更由 PR-2 交付;PR-1 的稳定接口与验收边界见 design 和 specs。
- 保留原作者的被动标签及协议,增加默认关闭的通用可选加载入口。
- 复用现有 runtime-config;采集参数通过部署 JSON 配置提供,平台参数放在 adapterConfig,不编辑源码。
- 模块随 Web 发布,平台适配器按需加载;第一版以 Umami 作为一个注册实现,不把厂商 SDK 或字段耦合进业务页面。
@ -23,6 +31,6 @@ Issue #989 / PR #1010 已提供被动动作标签、通用 helper 和独立平
## Impact
影响 Web 可选模块、运行时配置、容器启动、Compose/Helm、部署测试和文档。新增小型 jq 镜像依赖用于标准 JSON 校验与安全转义,避免用 envsubst 拼接任意配置。默认部署不启动统计服务、不加载采集模块、不外发事件。
影响按阶段区分:PR-1 仅涉及被动标签契约、示例、测试和接入文档;以下产品部署影响属于 PR-2。影响 Web 可选模块、运行时配置、容器启动、Compose/Helm、部署测试和文档。新增小型 jq 镜像依赖用于标准 JSON 校验与安全转义,避免用 envsubst 拼接任意配置。默认部署不启动统计服务、不加载采集模块、不外发事件。
范围外:后台采集配置页、SkillHub 分析数据库、通用远程代码插件平台、用户级同意弹窗、可靠消息/重试队列、服务端业务成功事件、生产环境部署和自动合并。统计平台自己的数据库属于可选外部服务,不修改 SkillHub schema。

View file

@ -1,62 +1,152 @@
## ADDED Requirements
### Requirement: Preserve passive business semantics
Delivered by: PR-1 (passive markers and examples); PR-2 (product integration regression).
The system SHALL preserve existing static action categories and business interactions without introducing analytics dependencies into business components.
#### Scenario: Existing business operation
Delivered by: PR-1 (marker/helper assertions); PR-2 (full business regression).
- **WHEN** a user logs in, publishes, uploads, downloads or navigates with analytics disabled or unavailable
- **THEN** existing permissions, requests, keyboard behavior and business outcomes remain unchanged
### Requirement: Deploy using configuration only
Delivered by: PR-2.
The system SHALL deliver optional analytics modules with the Web artifact and accept deployment configuration without source edits or hand-written Nginx rules.
#### Scenario: Connect an existing supported platform
Delivered by: PR-2.
- **WHEN** the operator supplies valid analytics JSON, a supported adapter configuration and internal upstream origin
- **THEN** the Web startup generates safe runtime configuration and the required isolated proxy routes without an additional Nginx service
### Requirement: Default closed and fail isolated
Delivered by: PR-2 (product loader); PR-1 examples SHALL remain opt-in and inert by default.
The system SHALL default to analytics disabled and consent denied, and SHALL isolate invalid configuration and runtime analytics failures from Web and business availability.
#### Scenario: Disabled or denied collection
Delivered by: PR-2.
- **WHEN** configuration is omitted, enabled is false, or consent is denied
- **THEN** the browser does not load analytics modules or SDKs and does not send analytics requests
#### Scenario: Disabled example
Delivered by: PR-1.
- **WHEN** the deployment-owned entry remains enabled:false or consent is not approved, or no entry is injected
- **THEN** no observer is installed, no tracker is loaded and no intent is sent; importing the helper alone has no collection side effects
#### Scenario: Invalid configuration
Delivered by: PR-2.
- **WHEN** analytics JSON, adapter or upstream is invalid
- **THEN** only analytics is disabled with a diagnostic that does not echo raw values, while existing Web configuration remains usable
#### Scenario: Statistics service unavailable
Delivered by: PR-2 (including request-time DNS); PR-1 covers an unavailable example tracker without making a product DNS-startup guarantee.
- **WHEN** the upstream is unreachable or its hostname cannot resolve
- **THEN** the Web still starts and business remains usable without waiting for the statistics service
### Requirement: Vendor-neutral module contract
The system SHALL separate generic configuration, rules and lifecycle from adapter-specific parameters and SDK calls.
Delivered by: PR-1 (helper and example adapter); PR-2 (registered product factories and configuration).
The system SHALL separate generic configuration, rules and lifecycle from adapter-specific parameters and SDK calls. PR-2 SHALL migrate the helper to one product source under web/src/features/analytics and retain every PR-1 test assertion rather than maintaining duplicate implementations.
#### Scenario: Registered adapter
Delivered by: PR-2.
- **WHEN** a supported adapter is selected
- **THEN** its factory validates its own adapterConfig and exposes send and stop while generic code does not depend on vendor fields
#### Scenario: Stable helper and adapter boundary
Delivered by: PR-1; adopted unchanged by PR-2.
- **WHEN** a deployment connects a collector to passive markers
- **THEN** IDs follow `^[a-z]+(?:\.[a-z]+){2,}$` and the manifest lifecycle; observeSkillhubIntents({ root, rules, onIntent }) returns stop; frozen DEFAULT_RULES contains the original 12 rules; resolveRules(rules) returns active and skipped entries with id and reason
- **AND** only click, submit and card rule types are supported with their documented host restrictions; invalid or unknown entries are skipped without affecting the page
- **AND** the intent is { id, event }, describes native intent rather than business success, and evolves additive-only within its version
- **AND** adapter send(intent) returns Promise<void> and never rejects, stop prevents new dispatch, and vendor parameters belong only to the adapter
#### Scenario: Configuration maps to the existing contract
Delivered by: PR-2.
- **WHEN** enabled, adapter, consent, rules and adapterConfig are supplied
- **THEN** enabled and consent gate optional loading and observation, adapter selects a static registered factory, rules use the existing resolver (omitted means defaults, explicit object replaces them), and adapterConfig is validated only by the selected adapter
### Requirement: Safe event lifecycle
Delivered by: PR-1 (example lifecycle); PR-2 (product controller and asynchronous module loading).
The system SHALL preserve finite configured rules, field allowlists, duplicate prevention, bounded loading waits and failure isolation.
#### Scenario: Stop races with asynchronous initialization
Delivered by: PR-1 (SDK wait/dispatch); PR-2 (module/controller races as well).
- **WHEN** collection is stopped while a module or SDK is loading
- **THEN** late initialization does not restart collection and no new request dispatches after stop returns, excluding requests already started
#### Scenario: Repeated initialization and rule changes
Delivered by: PR-1; preserved by PR-2.
- **WHEN** the same root is initialized repeatedly before stop
- **THEN** it returns the same stop and retains the first configuration and callback without duplicate events
- **AND** stop is idempotent, configuration changes require stop then reinitialization, and an old stop does not remove a new installation
### Requirement: Compatible deployment paths
Delivered by: PR-2 (normal deployment); PR-1 (opt-in edge example and mapping guide).
The system SHALL support root and supported sub-path deployments while preserving existing API, auth, upload, cache and security behavior.
#### Scenario: Large valid upload through normal Web
Delivered by: PR-2.
- **WHEN** a user uploads a business-valid package larger than 1 MiB through the standard Web entry with analytics enabled
- **THEN** optional analytics routes do not reduce the existing upload limit or alter the upload request
#### Scenario: Example edge preserves upload boundaries
Delivered by: PR-1.
- **WHEN** an operator uses the opt-in edge in front of the Web
- **THEN** client_max_body_size 100M applies at server level and is not lowered on application proxy locations; a 5 MiB API/upload probe reaches the upstream rather than returning edge 413, while a body larger than 100 MiB is rejected with 413
- **AND** any tighter collector-only limit does not change application uploads
#### Scenario: Example defaults match release Web
Delivered by: PR-1.
- **WHEN** SKILLHUB_WEB_UPSTREAM is omitted from the example Compose configuration
- **THEN** the edge targets host.docker.internal:80, matching the release WEB_PORT default of 80, and its extra_hosts provides host.docker.internal:host-gateway on native Linux
- **AND** the guide explains overrides and container-to-host reachability, while Docker Desktop/OrbStack already provide the hostname
#### Scenario: Optional endpoint boundary
Delivered by: PR-1 (example routes); PR-2 (generated product routes).
- **WHEN** a browser requests an unregistered analytics route
- **THEN** the route is rejected and does not expose the statistics platform administration or arbitrary upstream paths
### Requirement: Reproducible deployment documentation
Delivered by: PR-1 (manual example guide); PR-2 (configuration-only production guide).
The system SHALL document configuration fields, existing-platform and optional self-hosted deployment, required initialization, verification, troubleshooting, upgrade, disable and rollback.
#### Scenario: Operator follows the guide
Delivered by: PR-2.
- **WHEN** an operator deploys the supported integration using the published guide
- **THEN** no JS or Nginx source file edits are required, all manual platform prerequisites are explicit, and enabled, disabled and failure behavior can be independently verified
#### Scenario: Operator follows the PR-1 Chinese example guide
Delivered by: PR-1.
- **WHEN** an operator follows the Chinese integration guide without reading implementation source
- **THEN** the guide explicitly identifies the required entry configuration edits and platform initialization, explains both a custom send/stop adapter and self-hosted Umami, and provides copyable deployment and acceptance commands
- **AND** it explains the 12 defaults, finite rules and skipped diagnostics, upstream/host-gateway, supported sub-path mapping, CSP, actual Network payload and platform event checks, zero collection when disabled, troubleshooting, manifest/ID upgrades and shutdown
- **AND** best-effort/no retry, the 20-intent loading cap, pinned Umami version and remaining transport metadata are disclosed, with configuration-only deployment clearly deferred to PR-2
#### Scenario: Separate merges keep the issue open
Delivered by: PR-1 (scope declaration); PR-2 (completion gate).
- **WHEN** PR-1 merges independently
- **THEN** Issue #989 remains open until PR-2 configuration-only deployment is complete and verified

View file

@ -1,26 +1,36 @@
## 1. Scope and integration
- [x] 1.1 Confirm maintainer authorization, preserve contributor history and resolve latest-main translation conflicts.
- [x] 1.2 Define runtime configuration, adapter boundary, failure behavior and production deployment scope.
- [ ] 1.3 Validate this OpenSpec change and bind the existing PR/task.
## 2. Optional frontend capability
- [ ] 2.1 Move helper/adapter to a single product source and preserve existing tests.
- [ ] 2.2 Add default-closed runtime loader and vendor-neutral controller/registry.
- [ ] 2.3 Cover consent, validation, duplicate init, async stop races and adapter failures.
## 2. PR-1 (#1010)
- [x] 2.1 Verify passive markers, frozen published IDs and manifest drift against the current base.
- [x] 2.2 Verify the vendor-neutral helper, frozen defaults, finite rules, skipped diagnostics, repeat-init/stop and example adapter assertions.
- [x] 2.3 Fix and regression-test the example edge's server-level 100M application upload limit, release Web upstream default and native Linux host-gateway mapping.
- [x] 2.4 Provide an independently followable Chinese guide for existing-platform adapters and the local Umami demo, including configuration, deployment, acceptance, troubleshooting, upgrade and shutdown; link the English contract.
- [x] 2.5 Align the two-PR interfaces and manually check OpenSpec structure against add-skill-suites (CLI unavailable; not CLI validation).
- [x] 2.6 Run focused/full tests, typecheck, lint, build, manifest, Compose rendering and diff checks; repeat built-frontend/real-collector browser acceptance and the guide walkthrough, including upload boundaries.
- [ ] 2.7 Independent parent review and publication; keep Issue #989 open.
## 3. Deployment
- [ ] 3.1 Safely serialize and validate configuration without breaking existing runtime config.
- [ ] 3.2 Add isolated proxy snippets with request-time DNS, certificate validation and exact endpoints.
- [ ] 3.3 Wire Compose/Helm defaults and reserved sub-path validation.
- [ ] 3.4 Provide optional persistent self-hosted Compose combination without another Nginx.
## 3. PR-2 (follow-up): optional frontend capability
- [ ] 3.1 Move helper/adapter to a single product source under web/src/features/analytics and preserve all PR-1 assertions.
- [ ] 3.2 Add default-closed runtime loader and vendor-neutral controller/registry; register Umami as the first adapter.
- [ ] 3.3 Cover consent, validation, duplicate init, async stop races and adapter failures.
- [ ] 3.4 Validate this OpenSpec change with the CLI when available and bind the follow-up PR/task.
## 4. Documentation
- [ ] 4.1 Replace source-editing quickstart with configuration-only production paths.
- [ ] 4.2 Document fields, platform prerequisites, initialization, verification, upgrade and shutdown.
- [ ] 4.3 Link deployment entry points and document adapter extension and actual privacy boundaries.
## 4. PR-2 (follow-up): deployment
- [ ] 4.1 Safely serialize and validate configuration without breaking existing runtime config.
- [ ] 4.2 Add isolated proxy snippets with request-time DNS, certificate validation and exact endpoints.
- [ ] 4.3 Wire Docker/Compose/Helm defaults and reserved sub-path validation.
- [ ] 4.4 Provide optional persistent self-hosted Compose combination without another Nginx.
## 5. Quality gates
- [ ] 5.1 Consolidated independent implementation review, fixes and final base checkpoint.
- [ ] 5.2 Reviewed requirement/scenario/test matrix and targeted source/deployment checks.
- [ ] 5.3 Exact-SHA release Compose S3/auth smoke and Chromium normal/changed/failure scenarios.
- [ ] 5.4 CI/privacy/readiness, one validation report and retained preview for human acceptance.
## 5. PR-2 (follow-up): documentation
- [ ] 5.1 Replace source-editing quickstart with configuration-only production paths for supported platforms; distinguish custom adapter development.
- [ ] 5.2 Document fields, platform prerequisites, initialization, verification, troubleshooting, upgrade and shutdown.
- [ ] 5.3 Link deployment entry points and document adapter extension and actual privacy boundaries.
## 6. PR-2 (follow-up): quality gates
- [ ] 6.1 Consolidated independent implementation review, fixes and final base checkpoint.
- [ ] 6.2 Reviewed requirement/scenario/test matrix and targeted source/deployment checks.
- [ ] 6.3 Exact-SHA release Compose S3/auth smoke and Chromium normal/changed/failure scenarios, including default zero module/SDK/request and root/sub-path upload/login/download/CSP/cache compatibility.
- [ ] 6.4 CI/privacy/readiness, one validation report and retained preview for human acceptance.
- [ ] 6.5 Close Issue #989 only after configuration-only deployment is complete and verified, not when PR-1 merges.