# FlowScope Scope / Feature 架构需求草案

## 目标

这份文档用于约束下一版 FlowScope 核心架构实现。目标不是复刻 QFramework，也不是照搬 ft_3 当前容器用法，而是形成一套能服务真实 Unity 项目的可落地框架：

- 能力向 ft_3 靠拢：支持动态注册、父子 Scope、局部覆盖、运行期灵活组合。
- 规则向 QFramework 靠拢：业务代码默认在当前架构上下文中工作，不鼓励直接拿根容器乱 Resolve。
- 默认使用简单：大多数业务只需要 `Root -> Feature` 两级。
- 保留扩展能力：复杂业务可以继续创建子 Scope，但不把每个 UI、流程、函数调用都强制变成 Scope。

## 核心结论

下一版的第一主角应该是统一的 `ArchitectureScope`，不是固定的 `RootContext + FeatureScope` 两层结构。

`RootScope`、`FeatureScope`、`ChildScope` 本质都是同一种 Scope，只是所在层级和安装内容不同：

```text
Root Scope
  BossFightFeature Scope
  ScratchTicketFeature Scope
```

必要时可以继续细分：

```text
Root Scope
  BossFightFeature Scope
    BattleRound Scope
    RevivePanel Scope
```

但这不是默认推荐路径。默认推荐是每个活动、玩法、业务模块对应一个 Feature Scope，Feature 内部再按 MVC、MVVM、MVP、Controller、ViewModel、Service、State Machine 等方式组织。

## 概念定义

### ArchitectureScope

`ArchitectureScope` 是框架的核心上下文，也是受规则约束的容器节点。

它负责：

- 保存当前 Scope 的注册项。
- 从当前 Scope 开始解析依赖。
- 找不到时向父 Scope 查找。
- 创建子 Scope。
- 创建 Feature Scope。
- 管理当前 Scope 生命周期。
- 允许当前 Scope 覆盖父 Scope 的能力。

它不应该只是一个裸 DI Container，而是一个带层级、生命周期和使用规则的运行时上下文。

### RootScope

`RootScope` 是没有父节点的 `ArchitectureScope`。

它不应该拥有一套和普通 Scope 不同的能力。它只是树的根：

```text
RootScope = Parent == null 的 ArchitectureScope
```

Root 适合注册跨 Feature 的基础能力，例如：

- 配置服务
- 资源服务
- 存档服务
- 音频服务
- 网络服务
- 全局账号/环境信息

Root 不应该成为业务代码到处直接访问的全局服务定位器。

### Feature

`Feature` 是一个业务模块的安装定义，不是另一种容器。

一个 Feature 代表一个可独立理解的业务边界，例如：

- BossFightFeature
- ScratchTicketFeature
- Event1v1BattleFeature
- MainMenuFeature

创建 Feature 时，框架会自动创建一个新的 `ArchitectureScope`，然后把 Feature 安装到这个 Scope 上。

推荐 API：

```csharp
var boss = game.CreateFeature<BossFightFeature>();
```

等价概念：

```csharp
var boss = game.CreateScope("BossFight");
new BossFightFeature().Install(boss);
```

但调用侧不应该手写安装流程。

### Child Scope

Child Scope 是 Feature 内部或任意 Scope 下的局部生命周期工具。

它适合处理：

- 生命周期明显短于 Feature 的对象。
- 需要局部覆盖某个服务的场景。
- 一组临时对象需要一起释放的场景。
- 同一个 Feature 内存在多个并行实例的场景。
- 特殊流程需要隔离依赖解析的场景。

它不适合处理：

- 普通 UI Panel。
- 普通 ViewModel。
- 普通 Controller。
- 普通业务函数调用。
- 只是为了“看起来更分层”的拆分。

默认原则：能放在 Feature 内部 MVC/MVVM 结构里的，不要先拆成 Scope。

## Register / Resolve 规则

这版设计不应该限制只能在安装期 Register。

更准确的规则是：

```text
Register 本身不是问题。
问题是越级注册、越级修改、污染父级、绕开当前 Scope 解析。
```

因此下一版需要遵守：

1. 任意 Scope 都可以随时 Register。
2. Register 永远只写当前 Scope。
3. Resolve 永远从当前 Scope 开始。
4. 当前 Scope 找不到时，才向 Parent 查找。
6. 子 Scope 可以覆盖父 Scope 的注册。
6. 子 Scope 不能修改父 Scope 的注册。
7. Root 只是普通 Scope 的根节点，不是特殊全局服务定位器。
8. Feature 是创建出来并自动安装的 Scope。

示例：

```csharp
var game = FlowScope.Create();

game.Register<IConfigService, ConfigService>().AsSingleton();

var boss = game.CreateFeature<BossFightFeature>();
boss.Register<IRewardService, BossRewardService>().PerScope();

using var revive = boss.CreateScope("RevivePanel");
revive.Register<IRewardService, ReviveRewardService>().PerScope();

var reward = revive.Resolve<IRewardService>();
```

解析顺序：

```text
RevivePanel Scope -> BossFight Scope -> Root Scope
```

此时 `revive.Register` 不会污染 `boss`，`boss.Register` 不会污染 `root`。


## 容器策略

下一版不应该只包装 ft_3 的 `asap.core.Container`，而应该吸收它的核心设计，形成 FlowScope 自己的 Container。

已通过 `asap.core.dll` 元数据确认，ft_3 当前底层容器具备这些值得保留的设计：

- `(Type, string)` 作为注册 key。
- `Register<T>().AsSingleton()` 的声明式生命周期 API。
- `Register<TService, TImplementation>().AsSingleton()` 的接口到实现注册。
- `Register<T>(name).PerScope()` 的命名注册。
- `Register(Type serviceType, string name, Type implementationType).PerScope()` 的运行时类型注册。
- `RegisterInstance(instance)` 的现有实例注册。
- `Resolve<T>()` / `Container.IScope.GetInstance(...)` 的解析入口。
- `CreateScope()` 的 Scope 生命周期入口。
- `PerScope()` 通过 Scope lifetime 在具体 Scope 解析时生成/缓存实例。

同时也确认了 ft_3 当前公开接口的限制：

- `Container.IScope` 公开接口只有 `GetInstance((Type, string))`。
- `Container.IScope` 没有公开 `Parent` 属性。
- `Container.IScope` 没有公开 `Register` 方法。
- 底层注册入口主要在根 `Container` 上，不是每个 Scope 都能注册到自己。
- 底层只确认有 `AsSingleton()` 和 `PerScope()`，没有确认 `AsTransient()`。
- 底层没有确认存在 `TryResolve<T>()`。

因此下一版不采用“薄包装 asap.core.Container”的方案。

原因是 FlowScope 当前目标和 ft_3 底层公开模型不完全一致：

```text
ft_3 当前模型：Root Container 注册，Scope 负责按 Scope 生命周期解析/缓存。
FlowScope 目标模型：每个 ArchitectureScope 都可以注册到自己，并从自己开始 Resolve，再向父级查找。
```

如果只包装，会出现两套语义：外层说 Scope-local Register，内层却只有 Root Register。长期看会让 `ArchitectureScope` 变成补丁层，代码容易拧巴。

下一版应该选择：

```text
借鉴 ft_3 Container 的算法和 API 手感
但实现 FlowScope 自己的 Container / Scope Tree
```

## FlowScope Container 目标模型

FlowScope 的容器节点应该同时承担三件事：

```text
Container 负责能力
ArchitectureScope 负责规则
Feature 工厂负责业务模块创建
```

但实现上不再拆成“外层 Scope 包内层 Container.IScope”，而是统一为 FlowScope 自己的 Scope 节点：

```text
ContainerScope / ArchitectureScope
  Name
  Parent
  Children
  Dictionary<ServiceKey, Registration>
  CreateScope()
  CreateFeature<TFeature>()
  Register()
  Resolve()
  TryResolve()
  Dispose()
```

其中 `ServiceKey` 继续沿用 ft_3 的核心思路：

```csharp
public readonly struct ServiceKey
{
    public Type Type { get; }
    public string Name { get; }
}
```

## 生命周期规则

下一版容器至少支持：

```text
Singleton
注册所在 Scope 持有一个实例。

PerScope
每个 Resolve 发起 Scope 持有一个实例。

Transient
每次 Resolve 都创建新实例。

Instance
注册现有实例。是否 Dispose 需要显式规则，默认不销毁外部传入实例更安全。
```

`PerScope` 是从 ft_3 里最值得保留的能力之一。它适合活动、Feature、局部流程这种“同一个注册，不同 Scope 下得到不同实例”的场景。

## Register / Resolve 目标规则

FlowScope 自己的 Container 需要直接支持当前讨论确定的规则：

1. 任意 Scope 都可以随时 Register。
2. Register 永远只写当前 Scope。
3. Resolve 永远从当前 Scope 开始。
4. 当前 Scope 找不到时，才向 Parent 查找。
5. 子 Scope 可以覆盖父 Scope 的注册。
6. 子 Scope 不能修改父 Scope 的注册。
7. Root 只是没有 Parent 的普通 Scope。
8. Parent / Children 是 FlowScope 自己容器模型的一部分，不依赖底层外部容器。

示例：

```csharp
var game = FlowScope.Create();

game.Register<IConfigService, ConfigService>().AsSingleton();

var boss = game.CreateFeature<BossFightFeature>();
boss.Register<IRewardService, BossRewardService>().PerScope();

using var revive = boss.CreateScope("RevivePanel");
revive.Register<IRewardService, ReviveRewardService>().PerScope();

var reward = revive.Resolve<IRewardService>();
```

解析顺序：

```text
RevivePanel Scope -> BossFightFeature Scope -> Root Scope
```

`revive.Register` 不污染 `boss`，`boss.Register` 不污染 `root`。

## CreateFeature 规则

`CreateFeature<TFeature>()` 是 Scope 创建 + Feature 安装的语义封装。

调用者不传 name 时，默认使用 `typeof(TFeature).Name`：

```csharp
var boss = game.CreateFeature<BossFightFeature>();
// 等价于 game.CreateFeature<BossFightFeature>(typeof(BossFightFeature).Name)
```

推荐 API：

```csharp
IArchitectureScope CreateFeature<TFeature>()
    where TFeature : IFeature, new();

IArchitectureScope CreateFeature<TFeature>(string name)
    where TFeature : IFeature, new();
```

第一版可以先使用 `where TFeature : IFeature, new()`，保持简单：

```csharp
public IArchitectureScope CreateFeature<TFeature>(string name)
    where TFeature : IFeature, new()
{
    var child = CreateScope(name);
    var feature = new TFeature();
    feature.Install(child);
    return child;
}
```

后续如果 `TFeature` 需要依赖注入构造，可以改为从当前 Scope 创建：

```csharp
child.Register<TFeature>().PerScope();
var feature = child.Resolve<TFeature>();
feature.Install(child);
```

调用侧不应该手写：

```csharp
boss.InstallFeature(new BossFightFeature());
boss.UseArchitecture(new BossFightArchitecture());
```

Feature 的安装和 Scope 的创建应该被 `CreateFeature<TFeature>()` 收住。
## Feature 默认边界

大多数业务默认只需要：

```text
Root Scope
  Feature Scope
```

例如：

```text
Root Scope
  BossFightFeature Scope
  ScratchTicketFeature Scope
```

BossFight 内部的战斗、复活、奖励、UI，不应该默认都拆成 Scope。它们可以优先放在 Feature 内部架构里：

```text
BossFightFeature
  Model
  Service
  Controller
  ViewModel
  ViewBinder
  StateMachine
```

只有当局部生命周期、依赖覆盖、并行实例、独立释放这些需求明确存在时，才创建 Child Scope。

## Feature 与 MVC / MVVM

`Feature` 只定义业务模块边界，不强制决定内部表现层架构。

Feature 内部可以选择：

- MVC
- MVVM
- MVP
- Presenter
- Flow Controller
- State Machine
- 简单 Service + View 组合

框架不应该强制所有 Feature 使用同一种 UI 或业务组织模式。

示例：

```csharp
public sealed class BossFightFeature : IFeature
{
    public void Install(IArchitectureScope scope)
    {
        scope.Register<BossFightModel>().PerScope();
        scope.Register<IBossFightService, BossFightService>().PerScope();

        scope.UseMvvm<BossFightViewModel>();
        scope.UseMvc<BossFightController>();
    }
}
```

`UseMvvm`、`UseMvc` 这类 API 可以作为后续扩展模块，不一定属于第一版核心。

## 与 ft_3 Activity 的关系

Activity 不应该等同于大 Feature 内部的所有业务实现。

更合理的职责划分：

```text
Activity
  负责活动开关、入口、可见性、预加载、跳转、生命周期接入。

Feature
  负责活动作为业务模块的运行边界。

ArchitectureScope
  负责该模块的依赖注册、解析、父子继承、局部覆盖和生命周期。

MVC / MVVM / State
  负责 Feature 内部具体业务和 UI 组织。
```

也就是说，Activity 更像外部接入器，Feature 才是业务模块边界。

## 约束方式

约束重点不应该是禁止 Register，而是让代码默认只能操作当前 Scope。

建议通过接口和可见性控制：

```csharp
public interface IArchitectureScope : IDisposable
{
    string Name { get; }
    IScopeInfo Parent { get; }

    IArchitectureScope CreateScope(string name);

    IArchitectureScope CreateFeature<TFeature>()
        where TFeature : IFeature, new();
    IArchitectureScope CreateFeature<TFeature>(string name)
        where TFeature : IFeature, new();

    IRegistrationBuilder Register<TImplementation>();
    IRegistrationBuilder Register<TService, TImplementation>()
        where TImplementation : TService;

    T Resolve<T>();
    T Resolve<T>(string name);
}
```

`Parent` 可以只暴露只读元信息，避免业务代码通过 Parent 直接写父 Scope。

```csharp
public interface IScopeInfo
{
    string Name { get; }
    IScopeInfo Parent { get; }
}
```

如果确实需要高级能力，可以后续通过内部接口或显式高级 API 暴露，而不是默认给所有业务代码。

## 推荐最小核心 API

第一版可以先只实现：

```csharp
public interface IFeature
{
    void Install(IArchitectureScope scope);
}

public interface IArchitectureScope : IDisposable
{
    string Name { get; }
    IScopeInfo Parent { get; }

    IArchitectureScope CreateScope(string name);
    IArchitectureScope CreateFeature<TFeature>()
        where TFeature : IFeature, new();
    IArchitectureScope CreateFeature<TFeature>(string name)
        where TFeature : IFeature, new();

    IRegistrationBuilder Register<TImplementation>();
    IRegistrationBuilder Register<TImplementation>(string name);
    IRegistrationBuilder Register<TService, TImplementation>()
        where TImplementation : TService;
    IRegistrationBuilder Register<TService, TImplementation>(string name)
        where TImplementation : TService;

    void RegisterInstance<T>(T instance);
    void RegisterInstance<T>(T instance, string name);

    T Resolve<T>();
    T Resolve<T>(string name);
    bool TryResolve<T>(out T value);
    bool TryResolve<T>(out T value, string name);
}
```

工厂方法：

```csharp
var game = FlowScope.Create();
var boss = game.CreateFeature<BossFightFeature>();
```

## 暂不进入的内容

以下能力暂时不作为下一版第一阶段重点：

- Command / Query / Event 通信模型。
- 完整 MVC / MVVM 框架。
- 自动扫描所有 Feature。
- UI Panel 生命周期统一接管。
- 复杂诊断面板。
- 热更新资源接入细节。

原因是当前最核心的问题还在：

```text
Scope / Feature / Container / Architecture 的第一层抽象需要先稳定。
```

通信和表现层规则应该建立在稳定 Scope 模型之上。

## 验收标准

下一版实现完成后，应满足：

1. Root 和普通 Scope 使用同一种 `ArchitectureScope` 模型。
2. `CreateFeature<TFeature>()` 默认使用 `typeof(TFeature).Name` 作为 Scope 名称。
3. `CreateFeature<TFeature>(name)` 会自动创建子 Scope 并调用 `TFeature.Install(scope)`。
4. 任意 Scope 可以随时 Register，且只能注册到自己。
5. Resolve 从当前 Scope 开始，支持向父 Scope 查找。
6. 子 Scope 可以覆盖父 Scope 注册。
7. 子 Scope Dispose 不会释放父 Scope 对象。
8. 父 Scope Dispose 会释放子 Scope。
9. Feature Scope 默认就是主要业务边界。
10. Child Scope 能用，但文档和测试不鼓励把普通 UI/VM/Controller 都拆成 Scope。
11. 第一阶段不要求实现 Command / Query / Event。

## 当前设计取舍

这套设计选择了：

```text
默认 Root -> Feature，复杂时再 Child Scope。
```

而不是：

```text
强制 Root -> Feature -> Flow -> UI -> Task。
```

原因是 FlowScope 应该帮助真实项目收住边界，而不是替业务制造额外层级。框架应提供可递归的 Scope 能力，但默认心智模型必须保持简单。