---
name: level_data_validator.aivalidator
description: 关卡数据校验器。对 RawLevelJson 格式进行编译期 + 运行期双重校验：坐标越界、路径长度、自交叉、可解性检测。开发模式自动输出警告。
triggers: 关卡数据校验,validate,level data,坐标越界,路径错误,无解关卡,数据质量
---

# 关卡数据校验器（Level Data Validator）

## 说明

`validateLevel()` 在开发模式下自动校验关卡数据，发现问题立即报错而非等到运行时崩溃。

**检测规则：**
1. 基础结构：行列 > 0、arrows 数组非空
2. 坐标越界：所有点必须在 `[0, col)` × `[0, row)` 范围内
3. 路径长度：每条路径至少 2 个点
4. 路径重叠：两条路径不应共享格子（警告）
5. 可解性：至少存在一条路径可以直接消除（警告）

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|------|
| `src/game/levels/LevelValidator.ts` | `ref/LevelValidator.ts` | 校验函数 |

## Recipe

| 决策 | 原因 |
|------|------|
| **开发期校验，生产期跳过** | 校验逻辑本身有一定性能开销；通过 `NODE_ENV !== 'production'` 保护，生产版本零开销 |
| **错误与警告双通道** | 坐标越界是致命错误（游戏必然崩溃），路径重叠是设计警告（游戏能运行但关卡可能有问题）；两者严重程度不同，分通道报告 |
| **与 solvability_validator 分离** | 基础数据格式校验（坐标、结构）与玩法可解性校验（消除顺序、篮子容量）是不同关注点；分离后各自可独立加载 |

## Adapter

- **Role**: `levelDataValidator` — 关卡数据开发期格式与约束校验器
- **Provides**: `validateLevel()` 函数、`ValidationResult` 类型（`valid`、`errors[]`、`warnings[]`）
- **Requires**: `arrow_path_data_format.aicomponent`（RawLevelJson 类型）
- **Consumed by**: `game_scene.aicomponent`（开发模式下在 `parseLevelJson()` 前校验）、`gameplay_unit_test.aivalidator`（集成数据校验测试）
- **Integration point**: `src/game/levels/LevelValidator.ts` —— 在 `parseLevelJson(raw)` 调用前插入 `validateLevel(raw)` 检查

## Imports

- `arrow_path_data_format.aicomponent`（硬依赖：RawLevelJson 类型）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: ref/LevelValidator.ts
outputs:
  - validator: validateLevel() function + ValidationResult type
```

## 使用方式

```typescript
import { validateLevel } from "./levels/LevelValidator";

// 在加载关卡时调用
const raw = LevelData[index];
const result = validateLevel(raw);
if (!result.valid) {
  console.error("[LevelValidator] Level", index, "has errors:", result.errors);
}
if (result.warnings.length > 0) {
  console.warn("[LevelValidator] Level", index, "warnings:", result.warnings);
}
```

## 集成到 Game.ts

```typescript
// 只在开发模式校验（生产模式跳过）
if (process.env.NODE_ENV !== 'production') {
  const validation = validateLevel(raw);
  if (!validation.valid) {
    console.error('[Game] Invalid level data:', validation.errors);
  }
}
const level = parseLevelJson(raw);
```