一致性测试向量

测试向量把抽象规范变成前端、服务端和清理任务都能执行的共同样例。

1. 测试原则

  • 测试输入使用人工生成数据,不复制真实用户轨迹。
  • 前端和服务端读取同一组 JSON fixture。
  • 生命周期边界必须一致;纯视觉参数允许约定范围内的误差。
  • 每次规则版本升级都新增向量,不覆盖旧版本样例。
  • 旧向量至少保留到使用旧规则的事件全部过期。

2. 目录建议

test-vectors/
├── trace-decay/
│   ├── fresh-human-track.json
│   ├── half-faded-track.json
│   ├── expired-track.json
│   └── wind-accelerated-decay.json
├── world-clock/
│   ├── client-clock-jump.json
│   ├── resume-after-sleep.json
│   └── reconnect-time-correction.json
├── protocol/
│   ├── duplicate-submit.json
│   ├── invalid-speed.json
│   └── region-boundary.json
├── creatures/
│   ├── two-observers-same-creature.json
│   └── late-observer.json
└── lifecycle/
    ├── render-expired.json
    ├── purge-expired.json
    └── restore-does-not-resurrect.json

3. 通用向量格式

{
  "name": "half-faded human track",
  "ruleset": "desert_decay_v1",
  "input": {},
  "expected": {}
}

expected 至少断言:

phase
visible
purge_eligible

如果涉及协议,还应断言事件数量、错误码或幂等结果。

4. 新鲜脚印

{
  "name": "fresh human track",
  "ruleset": "desert_decay_v1",
  "input": {
    "imprinted_at": "2026-10-21T00:00:00.000Z",
    "world_time": "2026-10-21T00:01:00.000Z",
    "base_lifetime_ms": 7200000,
    "surface": "fine_dry_sand",
    "initial_strength": 1.0,
    "environment_events": []
  },
  "expected": {
    "phase": "fresh",
    "visible": true,
    "purge_eligible": false
  }
}

5. 衰退中的脚印

{
  "name": "half faded human track",
  "ruleset": "desert_decay_v1",
  "input": {
    "imprinted_at": "2026-10-21T00:00:00.000Z",
    "world_time": "2026-10-21T01:00:00.000Z",
    "base_lifetime_ms": 7200000,
    "surface": "fine_dry_sand",
    "initial_strength": 1.0,
    "environment_events": []
  },
  "expected": {
    "phase": "softening",
    "visible": true,
    "purge_eligible": false
  }
}

示例使用两小时基础寿命,未叠加地表和天气修正。正式规则参数确定后,fixture 必须由正式参数重新生成并冻结。

6. 被遗忘的脚印

测试必须区分视觉过期和可清理:

{
  "name": "render expired but not purge eligible",
  "ruleset": "desert_decay_v1",
  "input": {
    "render_expires_at": "2026-10-21T02:00:00.000Z",
    "purge_after": "2026-10-21T02:30:00.000Z",
    "world_time": "2026-10-21T02:10:00.000Z"
  },
  "expected": {
    "phase": "forgotten",
    "visible": false,
    "purge_eligible": false,
    "included_in_snapshot": false
  }
}

超过 purge_after 后,purge_eligible 才变为 true。

7. 风加速衰减

同一条痕迹分别在有风和无风输入下运行。预期:

  • 有风版本的 normalized_life 更大;
  • 两端使用同一个环境事件 ID,不能重复计入;
  • 当有风版本进入 forgotten 时,客户端和服务端必须同时判定不可见。

8. 客户端时钟跳变

输入:

服务端最后同步时间不变
设备墙上时钟向前跳一天
单调计时只经过几秒

预期:

  • estimated_world_time 只前进几秒;
  • 痕迹不会因为设备时间变化突然消失;
  • 下一次服务端同步后平滑校正。

9. 休眠后恢复

输入:客户端休眠,世界时间已经越过痕迹的 render_expires_at。

预期:

  • 恢复后先同步时间或重取快照;
  • 不从休眠前的透明度继续播放;
  • 已过期痕迹立即不再显示;
  • 不出现倒放或短暂复活。

10. 重复提交

两次提交使用相同 client_message_id 和相同 payload。

预期:

  • 服务端只创建一个权威事件;
  • 第二次返回第一次的确认结果;
  • 区域订阅者只收到一次 trace.segment.created。

同一个 client_message_id 携带不同 payload 时必须拒绝,并记录不含完整路径的安全告警。

11. 两个观察者看同一动物

输入:两个客户端订阅同一区域,收到同一 creature.traverse.scheduled。

预期:

  • 两端物种、路径和时间轴一致;
  • 视觉帧率可以不同;
  • 在相同世界时间查询时,动物所处路径区间一致;
  • 动物离开后,两端生成的足迹生命周期阶段一致。

12. 晚到的观察者

输入:动物事件已经开始后,客户端才进入区域。

预期:

  • 不从路径起点重新播放;
  • 如果动物仍在事件时间窗内,从当前世界时间对应位置出现;
  • 如果动物已经离开,只返回仍有效的足迹;
  • 如果足迹也已过期,不返回该事件。

13. 区域边界

输入:一条路径跨越两个区域。

预期:

  • 权威路径连续;
  • 两个区域中的片段没有重复脚印;
  • 边界双订阅期间不会重复广播;
  • 任何一侧单独查询都能得到本区域所需部分。

14. 备份恢复不复活

输入:从较早快照恢复事件存储,但当前世界时间已经超过若干事件的 purge_after。

预期:

  1. 服务启动先执行过期过滤;
  2. 过期事件不进入缓存和空间索引;
  3. 区域快照不包含它们;
  4. 清理任务删除恢复出来的过期记录。

15. CI 门槛

以下变更必须运行全部向量:

  • 衰减公式;
  • 时间同步;
  • 规则版本选择;
  • 区域快照;
  • 数据清理;
  • 动物调度;
  • 路径幂等逻辑。

任何实现如果只让渲染截图看起来正确,却无法通过生命周期和清理向量,不得合并。