# DevCompass Racing Jumbotron 子系统定义

Jumbotron 子系统是 DevCompass Racing 的赛事主视觉子系统。它由运行时 **Jumbotron / Race Live View** 与设计时 **Track Profile Calibrator** 组成，目标是让赛马主视觉可以被稳定资产、可信几何和 DCR 快照数据驱动。

## 子系统定位

```text
DCR RaceSnapshot
  → Jumbotron Adapter
  → RacingEntrySnapshot[]
  → track-runtime
  → Jumbotron / Race Live View
```

```text
AI / Design Track Background
  → Track Profile Calibrator
  → track.profile.json
  → track-runtime
  → Jumbotron / Race Live View
```

## 子系统组成

```text
Jumbotron Subsystem
├── Runtime Side
│   ├── Jumbotron / Race Live View
│   ├── Jumbotron Adapter
│   ├── track-runtime
│   ├── ui-primitives
│   └── mock-racing-data
├── Design-time Side
│   ├── Track Profile Calibrator
│   ├── Track Profile Validator
│   └── AI-assisted Asset Pipeline
└── Shared Assets / Contracts
    ├── track-profile schema
    ├── track.profile.json
    ├── background.webp
    ├── preview.png
    └── RacingEntrySnapshot contract
```

## 运行时 Jumbotron / Race Live View

职责：

- 展示赛事标题、LIVE、Round / Phase、计时；
- 展示赛事 KPI：总进度、活跃骑手、Tokens、Codex / Claude 使用；
- 展示赛道主视觉；
- 根据 `RacingEntrySnapshot.roundProgress` 渲染马匹位置；
- 展示马匹编号、项目 / 骑手标签、TOP3、高亮 Entry；
- 展示 Riding Message 气泡；
- 展示底部 ticker 中的 Riding Message、风险和违规提醒；
- 支持 debug mode 验证几何、路径、车道和 stale 状态。

不负责：

- 真实后端聚合；
- 权限、房间、Workshop 上下文；
- 排名语义最终定义；
- Remote Racing Cockpit 协作流程；
- 复杂 3D 或真实物理模拟。

## Track Profile Calibrator

设计时赛道校准工具，职责：

- 导入赛道底图；
- 创建或导入候选 Track Profile；
- 编辑 centerline points；
- 设置赛道方向；
- 设置起点 / 终点；
- 配置 lane offsets；
- 配置 checkpoints；
- 预览单马和多马运行；
- 预览消息气泡；
- 运行 validation；
- 导出冻结后的 `track.profile.json`。

Calibrator 不是运行时 UI。它是设计 / 资产生产工具。

## track-runtime

Jumbotron 与 Calibrator 共享的核心运行包。

职责：

- 加载和校验 Track Profile；
- 将 centerline 转换为可采样路径；
- 计算路径长度；
- 根据 `s` 采样中心点；
- 计算切线方向；
- 计算法线方向；
- 应用 lane offset；
- 计算 horse pose；
- 管理 horse animation state；
- 提供 message bubble 的候选位置；
- 提供 runtime validation。

关键原则：Calibrator 预览必须复用 `track-runtime`，不能另写一套预览逻辑。

```text
track.profile.json
  → track-runtime
      ├── Jumbotron / Race Live View
      └── Track Profile Calibrator Preview
```

## Jumbotron Adapter

输入：

```text
RaceSnapshot
  - competition metadata
  - KPI summary
  - racing entries
  - recent messages
  - risks / violations
```

输出：

```text
RacingEntrySnapshot[]
RidingMessageSnapshot[]
AttentionItem[]
```

职责：

1. 选择用于赛道位置的进度字段；
2. 默认使用 `roundProgress`；
3. 在只有 `overallProgress` 时显式标记临时映射；
4. 映射 CA provider；
5. 映射风险状态；
6. 分配 lane；
7. 处理缺失数据；
8. 处理 stale；
9. 提取 Riding Message。

## Calibrator MVP 功能

1. 导入底图；
2. 加载 / 创建 Track Profile；
3. 添加、删除、拖拽 centerline points；
4. 平滑路径预览；
5. 闭合路径；
6. 一键反转路径方向；
7. 设置起点；
8. 配置 lane offsets；
9. 配置 checkpoints；
10. 通过 scrubber 预览一匹马从 0% 到 100%；
11. 预览多匹马；
12. Validate；
13. Export JSON。

## 共享数据契约

### Track Profile

Track Profile 是赛道的语义资产，也是运行时事实来源。

```text
TrackProfile
├── schemaVersion
├── trackId
├── name
├── viewBox
├── background
├── centerline
│   ├── type
│   ├── closed
│   ├── points
│   └── smoothing
├── direction
├── startFinish
├── lanes
├── checkpoints
├── messageZones
└── noBubbleZones
```

### RacingEntrySnapshot

```ts
export interface RacingEntrySnapshot {
  entryId: string;
  riderName: string;
  projectName: string;
  cockpitId?: string;
  caProvider: "codex" | "claude" | "other";
  rank?: number;
  overallProgress: number;
  roundProgress: number;
  phaseProgress?: number;
  currentPhase?: "PRD" | "DEV" | "REL" | "OPS" | "PM";
  costTokens?: number;
  costUsd?: number;
  riskLevel: "none" | "low" | "medium" | "high";
  obstacleCount: number;
  violationCount: number;
  status: "idle" | "running" | "blocked" | "pit_stop" | "takeover" | "finished" | "stale";
  laneId?: string;
  lastMessage?: RidingMessageSnapshot;
  updatedAt: string;
}
```

## 位置与动画规则

赛马位置不能手写 `x/y`，也不能运行时从图片识别。

```text
RacingEntrySnapshot.roundProgress
  → normalized s
  → sampled centerline point
  → tangent vector
  → normal vector
  → lane offset
  → horse x/y/rotation
```

位置补间应在 `s` 轴上进行，而不是直接在 `x/y` 上补间：

```text
s0 → s1 → sample pose at s(t)
```

这样可以避免弯道处马匹穿越赛道内侧。

## 资产生产与冻结

推荐流程：

```text
1. 编写赛道视觉 prompt
2. AI 生成 16:9 赛道底图
3. AI 输出候选 centerline points
4. 导入 Calibrator
5. 人工校准路径
6. 预览多马运行
7. Validate
8. Export
9. 提交资产
```

资产目录规范：

```text
assets/tracks/<track-id>/
  background.webp
  track.profile.json
  preview.png
  notes.md
  source.prompt.md
```

一个 track asset 进入 DCR 前必须通过 schema validation、geometry validation、单马预览、多马预览和 16:9 大屏视觉稳定性检查。