系统架构

# 系统架构

本文件描述满足世界语义的最小系统结构,不绑定具体云厂商。

## 1. 总体结构

```text
浏览器客户端
  ├── 地形与光照渲染
  ├── 痕迹派生与衰减
  ├── 输入采样与路径分段
  ├── 动物动画
  └── 实时连接
          │
          ▼
世界网关 / 实时服务
  ├── 会话与短期 presence
  ├── 区域订阅
  ├── 命令验证
  ├── 事件广播
  └── 服务端时间
          │
          ├────────► 世界调度器
          │            ├── 动物经过
          │            └── 环境事件
          │
          ▼
有限寿命事件存储
  ├── 痕迹片段
  ├── 动物路径
  ├── 环境事件
  └── 空间与过期索引
          │
          ▼
清理任务
  ├── 删除过期索引
  ├── 删除事件
  └── 失效区域缓存
```

## 2. 浏览器客户端

职责:

- 根据世界 seed 和地形版本生成可见地形;
- 维护经服务端校正的世界时间;
- 将用户移动采样为连续路径片段;
- 根据权威事件和规则派生脚印状态;
- 播放共享动物事件;
- 对低频 presence 更新进行插值;
- 在性能不足时降低视觉精度,不改变事实判断。

客户端不得:

- 宣布自己的路径已经成为共享事实;
- 使用设备时间决定权威生命周期;
- 永久保存其他人的轨迹;
- 独立随机生成应被多人共同看见的动物。

## 3. 世界网关与实时服务

职责:

- 建立匿名短期会话;
- 返回权威世界时间;
- 管理区域订阅;
- 验证路径命令;
- 为接受的片段生成权威事件;
- 广播区域增量事件;
- 维护短期 presence;
- 对重复 `client_message_id` 提供幂等响应。

该服务不需要竞技游戏级帧同步。重点是:

- 路径最终一致;
- 偶遇位置足够平滑;
- 同一事件的时间语义一致;
- 断线重连不会制造重复脚印。

## 4. 世界调度器

世界调度器负责低频共享事件:

- 动物何时、在哪里经过;
- 环境风力何时变化;
- 事件使用哪套规则版本。

调度器生成事件,不直接生成最终画面。

MVP 可以使用单进程定时任务,但输出必须走与正式服务相同的事件模型,不能在前端写一套临时随机逻辑。

## 5. 事件存储

MVP 需要的能力:

- 按 `event_id` 幂等写入;
- 按区域和时间查询仍有效事件;
- 按 `purge_after` 批量清理;
- 支持路径片段的空间索引;
- 不要求永久事件溯源。

逻辑索引:

```text
by_event_id
by_region_and_render_expiry
by_purge_after
by_trace_id_and_time
```

`by_trace_id_and_time` 只服务片段连续性和生命周期内重建,不得扩展为跨会话用户历史。

## 6. 技术选型建议

### 客户端

优先:

- TypeScript;
- Three.js 或 React Three Fiber;
- WebGL,后续再评估 WebGPU;
- Web Worker 处理路径采样和衰减批计算。

### 服务端

MVP 可选择熟悉的单体服务:

- Go、Rust、TypeScript 或 Python 均可;
- HTTP 提供快照;
- WebSocket 提供实时事件;
- 单进程调度器产生动物和风事件。

### 存储

第一版不必引入复杂流处理系统。可以使用:

- PostgreSQL 加空间索引;或
- SQLite 作为单机原型,外加明确的区域和过期索引。

当连接规模证明需要扩展时,再拆分实时网关和事件存储。

## 7. 路径采样

路径采样需要同时满足:

- 视觉连续;
- 消息量可控;
- 服务端可验证;
- 不依赖具体脚印模型。

建议流程:

```text
高频读取本地移动
  → 距离/时间阈值降采样
  → 形成短路径片段
  → 提交服务端
  → 本地先显示候选痕迹
  → 收到确认后转为权威痕迹
  → 被拒绝时平滑移除候选痕迹
```

候选痕迹只能存在于当前客户端,不能广播给别人。

## 8. 衰减计算

客户端和服务端共享同一语义实现或同一组测试向量。

- 客户端计算视觉阶段和参数;
- 服务端计算是否应进入快照、是否可以清理;
- 两端必须对 `visible`、`phase` 和 `purge_eligible` 达成一致;
- 浮点视觉参数允许小误差;
- 不允许生命周期边界发生分歧。

## 9. 区域快照与增量

进入区域时:

1. 客户端请求区域快照;
2. 服务端按当前世界时间过滤过期事件;
3. 客户端构建当前可见痕迹;
4. WebSocket 继续接收快照版本之后的增量事件;
5. 离开区域后取消订阅并释放派生渲染对象。

跨区域时允许短暂双订阅,避免路径和动物在边界跳变。

## 10. 故障处理

### 客户端休眠

恢复后先校时和取增量;如果中断过久,直接重取快照,不从旧动画进度继续。

### 服务端重启

- presence 可以丢失并重新建立;
- 已接受的路径事件不能丢失;
- 世界时间不能重置;
- 调度器不得重复产生相同动物事件。

### 数据库暂时不可用

- 不得先广播后落库;
- 路径提交返回可重试错误;
- 客户端可以短暂保留候选痕迹,但不能把它当共享事实。

## 11. 安全边界

至少限制:

- 单条消息大小;
- 路径点数量;
- 提交频率;
- 合法坐标范围;
- 速度和转向;
- 区域订阅数量;
- WebSocket 空闲连接时间。

不得因为反滥用而建立永久用户轨迹。安全数据和作品数据必须分库存储或至少逻辑隔离,并使用独立保留期。

## 12. 可观测性

记录聚合指标:

```text
活跃连接数
区域订阅数
路径提交数与拒绝率
消息大小分布
快照生成耗时
事件存储延迟
过期事件清理数量
客户端性能档位
```

不记录完整真实路径 payload。

## 13. 演进原则

先保持单体和少量明确模块。只有出现真实瓶颈时才拆分:

- 实时连接成为瓶颈,再拆网关;
- 空间查询成为瓶颈,再升级存储;
- 调度规模扩大,再拆世界调度器;
- 不为假设中的百万并发提前引入事件总线、微服务和多区域一致性。