inkwatch

0 Fork 0

Files

T

jkooe f4e24c2c95 feat(events): 最小埋点 5 事件的闭环 —— 白名单、有界、写失败不阻断（M5）

## 三处前置此前**全部不存在**（我实测，不是文档说）

```
shared/events.js                     → 不存在
deploy/migrate.sql  CREATE TABLE events → 0 命中
server/ 下 "api/events"               → 0 命中
```

所以在这之前任何"事件名单差集为空"的断言都是**恒绿的空断言**：文件不存在 → 读到空
集合 → 差集为空，而"文件不存在"与"文件里没有多余事件"在输出上是同一个东西：空。

## 服务端

- `shared/events.js`：5 个名字的**唯一机器副本**（权威在 SPEC §6.1.1）。净化做的是
  **形状白名单**而不是字段名白名单 —— SPEC 只锁了事件名、没定义逐事件 props，此时
  在这里发明一套字段名等于实现方单方面定契约，然后让客户端照着写。形状约束
  （键名 `^[a-z][a-z0-9_]{0,31}$` / 值只接受标量 / ≤12 键 / ≤2KB / 敏感键名直接丢）
  能挡住"埋点变成第二张用户表"这条路上最现实的风险，且不假装知道产品要什么。
- `POST /api/events`：未知名与非法条目**丢弃并计 dropped**（AC-20，不是 400）、
  超 20 条只受理前 20（AC-21）、**写库失败仍 202**（AC-22）。认证可选但
  **带废令牌一律 401**（降级成匿名等于"发个废令牌就关认证"）；
  `body.account_id` 自报**被忽略** —— 否则谁都能往别人账号的漏斗里灌数，而漏斗是
  拿来算率的，被灌了就没有意义。
- 管理端 `/api/admin/events/summary`：只出按事件名的计数与首末时间。它的判据不在
  "能查出来"，而在**查不出来** —— 这个端点没有任何办法取回某一条事件的内容。

## 客户端：必须有真实产生方，否则这张表永远是空的

这是本轮最容易"看起来交付了"的地方：端点全绿、表建好了，而**没有任何上报** →
表恒空、漏斗没有分子分母，而所有测试照样通过。**"以空为通过"的形态里这一种最难发现，
因为每一层单独看都对。**

`client/lib/host/event_reporter.dart` + `main.dart` 两个真实触发点（`app_open` 在配置
就绪、首帧将出时；`first_frame_shown` 用 `addPostFrameCallback`）。三条纪律：
不阻断业务（失败吞掉）、不重试（补报时序已经错了）、有界（丢最旧的）。

`app_open` **不能**放在 `main()` 最前面 —— 那时还不知道业务地址（`businessUrl` 来自
用户配置）。所以它落在"配置已就绪、首帧将出"这一刻；语义仍是"打开了应用"，且这一批
能真的发出去。

## 建表只有一个落点

`events` 只写进 `deploy/migrate.sql`，`init.sql` 用 `\i /migrate.sql` 引用它 ——
这是本仓库既有约定（新表进 migrate，init 引用）。我最初给执行方的判据是"两个文件都
必须有"——那会把一份定义复制成两份，是错的，按约定改正。

`account_id` 用 `BIGINT REFERENCES users(id) ON DELETE SET NULL` 而不是 SPEC §6.1
原写的 `TEXT`：`users.id` 是 BIGSERIAL，TEXT 会让"按账号算率"每次都 `::bigint` 强转，
转不动时（LEGACY 自报串）只能静默留 NULL，而 NULL 与"匿名上报"在表里长得一模一样。
`ON DELETE SET NULL` 让注销后**保留计数、解除关联**（CASCADE 会让历史漏斗在注销那一刻
缩水，分母变了率就不可比）。

## 测试

`tests/events-test.js` **29 项全绿**，已接入 `run-all.sh`。关键一条是 **A7「表里真的
长出了行」**——没有它，前面每条都能在一个"什么都没落库"的实现上全绿。
AC-22 不是写注释：把 `events` 表临时改名造一次真实写失败，断言仍 202 **且**
`accepted=0` **且** 带 `write_failed` **且** 恢复后行数未变（只断 202 不够 ——
任何实现都会 202，因为 catch 住了）。

客户端 `event_reporter_test.dart` 6 项全绿，其中一条钉住"先抽干再发"：发送期间
`track` 进来的新事件属于下一批，不被这一批的失败连坐（否则是"失败一次丢两批"）。

回归：permissions 60/0、account 75/0、schema 116/0、admin-api 80/0、认领 57/0、
档位与历史 99/0；客户端全量 **595 通过 / 2 失败**，两条失败均为
`libpmon_core.dylib` 未编译（Rust 核心未构建，本机环境问题，与本次改动无关）。

2026-11-08 19:46:29 +08:00

admin-queries.js

feat(plan,history): 档位展示名与升档流程、历史窗口按档位截断、保留期换配置源（M2/M3/M7）

2026-11-08 19:31:20 +08:00

audit-prune.js

fix(setup): 把实例配置真正接上线，并补上「最后管理员」漏掉的两个入口

2026-10-30 15:31:53 +08:00

device-identity.js

fix(privacy): 把 <user> 占位符改为「产品负责人」

2026-09-17 00:24:32 +08:00

instance-config.js

feat(setup): 实例初始化配置与 Web 安装向导