# P0-1: Container 需求详细文档

## 对齐说明

本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 允许 DI 自动注入进入首版，但必须保持 Container 核心轻量：核心只负责注册、解析、作用域和释放；Source Generator 与运行时反射只是生成工厂函数的适配层。

## 目标

提供 Game Core 的基础依赖容器，支持显式工厂注册、Attribute + Source Generator 自动注入、Attribute + 运行时反射降级、子作用域和可预测释放。

## P0 功能需求

### 1. 显式注册

```csharp
public sealed class Container : IDisposable
{
    public void RegisterInstance<T>(T instance);
    public void RegisterFactory<T>(Func<Container, T> factory);
    public T Resolve<T>();
    public bool TryResolve<T>(out T value);
    public Container CreateScope();
    public void Dispose();
}
```

规则：

- `RegisterInstance<T>` 注册外部实例，Container 不负责释放。
- `RegisterFactory<T>` 首次 Resolve 时创建实例，后续返回同一实例。
- 工厂创建且实现 `IDisposable` 的实例由当前 scope 释放。
- 子 scope 可访问父 scope 注册。
- 子 scope 可覆盖父 scope 注册，且不污染父 scope。
- 已 Dispose 的 scope 调用 Register/Resolve 必须抛 `ObjectDisposedException`。

### 2. Attribute 自动注入

```csharp
[AttributeUsage(AttributeTargets.Class)]
public sealed class InjectableAttribute : Attribute
{
}
```

```csharp
public sealed class Container : IDisposable
{
    public void RegisterType<TInterface, TImplementation>()
        where TImplementation : TInterface;

    public void RegisterType<TImplementation>();
    public void RegisterAssembly();
}
```

规则：

- 自动注入只支持构造函数注入。
- 只允许一个 public 构造函数。
- 构造函数参数从当前 Container 递归 Resolve。
- 循环依赖必须检测，并输出完整依赖链。
- `[Inject]` 属性注入和方法注入不进入 P0。

### 3. Source Generator 推荐路径

Source Generator 是 P0 推荐自动注入路径。

要求：

- 编译期扫描 `[Injectable]` 类型。
- 为每个 Injectable 类型生成等价于手写工厂的静态工厂方法。
- 编译期检查构造函数依赖是否可解析，无法确认时发出诊断。
- Generator 程序集与 Runtime 程序集分离。
- 未启用 Source Generator 时，显式工厂模式仍可独立使用。

### 4. 运行时反射降级路径

运行时反射是 P0 可选降级路径。

要求：

- 仅在启用反射模式时使用。
- 反射只在首次 Resolve 时构造并缓存结果。
- 行为必须与 Source Generator 模式一致。
- IL2CPP/AOT 风险需要在文档中明确提示。

### 5. 释放规则

- 当前 scope Dispose 时按创建逆序释放本 scope 管理的 `IDisposable`。
- 父 scope Dispose 时，先释放未释放的子 scope。
- `Dispose()` 可重复调用，后续调用静默忽略。
- 某个实例 Dispose 抛异常时，记录错误并继续释放其余实例。

## 暂不做

- `[Inject]` 属性注入。
- `[Inject]` 方法注入。
- Transient / Scoped / Singleton 多生命周期模式。
- 开放泛型注册。
- 装饰器注册。
- 条件注册。
- 运行时动态切换 DI 模式。

## 验收标准

| # | 标准 | 通过条件 |
|---|------|---------|
| 1 | 显式实例注册 | `RegisterInstance` 后 `Resolve` 返回同一实例 |
| 2 | 显式工厂注册 | `RegisterFactory` 首次 Resolve 创建实例，后续复用 |
| 3 | Source Generator 自动注入 | `[Injectable]` 类型可通过 `RegisterType` 正常解析 |
| 4 | 运行时反射自动注入 | 反射模式下行为与 Source Generator 一致 |
| 5 | 递归解析 | A 依赖 B、B 依赖 C 时 Resolve A 可自动解析整条链 |
| 6 | 循环依赖检测 | A -> B -> A 抛异常，错误包含依赖链 |
| 7 | 子 scope 读取父级 | 子 scope 可 Resolve 父 scope 注册 |
| 8 | 子 scope 覆盖父级 | 子 scope 覆盖后父 scope 不受影响 |
| 9 | 逆序释放 | 多个工厂实例按创建逆序 Dispose |
| 10 | 外部实例不释放 | `RegisterInstance` 传入的实例不由 Container Dispose |
| 11 | 重复 Dispose | 第二次 Dispose 不重复释放、不抛异常 |
| 12 | 已释放 scope 防护 | 已 Dispose scope 调用 Register/Resolve 抛 `ObjectDisposedException` |

## 依赖关系

```text
Container Runtime
├── 纯 C#，不依赖 Unity API
├── 不依赖 R3
├── Source Generator 适配层依赖 Roslyn
└── Reflection 适配层依赖 System.Reflection
```