# P0-5: IConfigProvider 需求详细文档

## 对齐说明

本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 配置系统只交付 JSON 强类型读取；CSV、Luban、ScriptableObject、远程配置、热重载和模块化加载全部放到 P1/P2 插件化扩展。

## 目标

提供最小可用的 JSON 配置加载和查询接口，支撑 P0 Sample 和休闲游戏基础配置读取。

## 接口

```csharp
public interface IConfigProvider
{
    Task LoadAllAsync(CancellationToken cancellationToken);
    T Get<T>(int id) where T : class, IConfigRow;
    IReadOnlyList<T> GetAll<T>() where T : class, IConfigRow;
}

public interface IConfigRow
{
    int Id { get; }
}
```

## 功能需求

- 启动时通过 `LoadAllAsync` 加载全部 JSON 配置。
- 配置行必须实现 `IConfigRow`。
- 查询使用泛型类型 + `Id`。
- `Get<T>(missingId)` 返回 null。
- `GetAll<T>()` 返回只读列表；未加载该类型时返回空列表。
- 同一配置类型内重复 Id 必须抛异常。
- JSON 格式错误必须抛异常并包含文件名。

## 配置文件约定

P0 默认采用约定路径，具体路径可由实现固定，例如：

```text
Assets/Configs/
├── weapons.json
├── levels.json
└── settings.json
```

每个 JSON 文件对应一种配置行类型。类型和文件的映射可以在 GameBootstrap 中显式注册，P0 不要求目录扫描和自动类型发现。

## 暂不做

- 字符串模块名查询。
- 混合查询模式。
- CSV。
- Luban。
- ScriptableObject 配置。
- 按模块加载/卸载。
- 远程配置。
- 热重载。
- 字段范围校验和引用完整性校验。
- 配置编辑器工具。

## 扩展方向

P1/P2 通过以下接口扩展，不修改业务调用：

```csharp
public interface IConfigParser
{
    string Format { get; }
    IReadOnlyList<T> Parse<T>(string content) where T : class, IConfigRow;
}

public interface IConfigSource
{
    Task<string> LoadTextAsync(string key, CancellationToken cancellationToken);
}
```

## 验收标准

| # | 标准 | 通过条件 |
|---|------|---------|
| 1 | JSON 加载 | `LoadAllAsync` 后配置可查询 |
| 2 | 按 Id 查询 | `Get<WeaponConfig>(101)` 返回正确对象 |
| 3 | 不存在 Id | 返回 null，不抛异常 |
| 4 | 获取列表 | `GetAll<WeaponConfig>()` 返回全部配置 |
| 5 | 重复 Id | 加载时抛异常并包含重复 Id |
| 6 | 格式错误 | 抛异常并包含文件名 |
| 7 | 取消加载 | CancellationToken 取消时抛 `OperationCanceledException` |

## 依赖关系

```text
IConfigProvider
├── JSON 库
├── 可选 IResourceService 或文件读取适配
└── 纯 C# 配置行类型
```