文档记录

docs/requirements/p0-configprovider.md

@@ -0,0 +1,99 @@
+# 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# 配置行类型
+```