一致性测试向量

# 一致性测试向量

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

## 1. 测试原则

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

## 2. 目录建议

```text
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. 通用向量格式

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

`expected` 至少断言:

```text
phase
visible
purge_eligible
```

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

## 4. 新鲜脚印

```json
{
  "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. 衰退中的脚印

```json
{
  "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. 被遗忘的脚印

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

```json
{
  "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. 客户端时钟跳变

输入:

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

预期:

- `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 门槛

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

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

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