Workspace/Docs/JustAnyProjectArchitectureAudit.md

# justanyproject 代码框架组织审计

> 审计日期：2026-08-24
> 源项目：`D:\UnityBuilds\justanyproject`
> 源基线：`main` / `b336715`，工作树干净，Unity `2022.3.62f3`
> 证据范围：`AGENTS.md`、`Assets/Scripts`、`Assets/Tests`、asmdef、`Packages/manifest.json` 和相关模块文档。本文是源码与工程结构审计，不代表重新执行过源项目的 Unity 编译、EditMode、PlayMode 或运行时验收。

## 1. 当前组织概况

源项目的第一方运行时代码主要位于 `Assets/Scripts`：共 564 个 C# 文件，按 24 个业务目录组织。规模最大的三个目录是 `EndlessMode`（205）、`CombatRuntime`（82）和 `Bootstrap`（41）。

项目共有 12 个第一方 asmdef，其中大部分基础模块已有独立程序集；但 `SeedsKey.Game` 仍引用 28 个程序集，并承载大量未拆分目录。测试分为 EditMode 与 PlayMode 两个程序集，二者都直接引用多个生产程序集。

当前框架可以概括为：

```text
Entry / AppBootstrapper
        |
Bootstrap + AppCompositionRoot
        |
全局 Manager / 领域系统 / Scene Composition Root
        |
CombatRuntime / EndlessMode / StrategicMap / 其它业务模块
        |
ShrinkEventBus / ShrinkDataSaver / ShrinkNetwork / ShrinkModFramework
```

目录层面的领域划分已经清楚，但编译边界、对象所有权和运行时入口仍处于新旧模式并存状态：显式组合根、窄接口和结构化 facade 已出现，业务单例、静态入口和事件协调仍然大量存在。

## 2. 值得迁移的经验

### 2.1 显式 Composition Root

`AppCompositionRoot` 和 `EndlessBattleCompositionRoot` 把关键依赖集中在可检查的绑定边界。后者通过序列化字段表达场景依赖，并提供 `ValidateRequiredBindings()` 汇总缺失项。这比在业务对象内部临时查找单例、场景对象或 prefab 子节点更容易审计。

`AppScope`、`SessionScope`、`SceneScope` 目前只是借用关系和已释放状态的标记：它们会拒绝失效父作用域，但不持有资源集合，也不会级联或反向释放对象。因此可迁移的是“显式作用域边界”，不是现有实现本身。

ShrinkSDK 的承载方式：

- App 级组合继续由 `ShrinkAppLoaderBootstrapper`、Composition Profile 与 `ShrinkAppLoaderHost` 表达。
- Session/Scene/Mod 生命周期继续映射为 `ShrinkContext` fiber、派生 context 和可逆 effect，不再增加第二套 Scope 容器。
- 场景组件仍应使用显式序列化引用和独立校验结果，不允许运行时静默补建或猜路径。

### 2.2 命令、查询和事实事件分离

源项目正在把跨模块调用收敛为三类：

- 查询依赖窄的只读接口，例如 `ISquadReadOnly`、`IInventorySlotReadOnly`。
- 改变状态的操作经过 command facade，并返回 `Succeeded / Failed / Rejected` 等结构化结果。
- EventBus 只广播已经发生的事实；请求事件仅作为有清理计划的兼容桥。

`GameSessionFlowFacade` 和 `SceneTransitionFlowFacade` 还处理了重复请求拒绝、异常转结果以及 `finally` 恢复运行状态。这些行为使调用方不必从日志或事件顺序猜测执行结果。

ShrinkSDK 的承载方式：

- `ShrinkCommandExecutionResult`、Network RPC 结果、Context 事务诊断继续作为状态变更的明确结果面。
- Context key 和 App service 应优先发布消费者真正需要的窄契约；只读消费者不应获得完整可写服务对象。
- EventBus bridge 只传递事实、通知或明确的异步请求合同，不用事件绕开 Command/Network 的返回值、权限和失败语义。

### 2.3 Owner-aware 内容注册表

`ContentRegistry<T>` 对内容 id、owner、覆盖优先级和冻结阶段有明确规则：

- 新增内容必须使用 owner namespace。
- 同目标、同优先级覆盖直接报冲突。
- 覆盖目标必须存在。
- 启动完成后冻结，运行阶段只读。

这套规则适合“启动时装载、运行时固定”的游戏内容。ShrinkModFramework 现已把其中可兼容热替换的部分落地：基础项强制使用 `<ownerModId>:<localKey>`，覆盖目标和优先级显式声明，同目标同优先级直接拒绝，owner 卸载时自动恢复下一个覆盖或基础项。

没有复制冻结模型。ShrinkModFramework 支持 revision 热替换和失败回滚，注册表必须随组件 effect 撤回；全局冻结会与此生命周期冲突。模组通过 `RegisterContent` / `OverrideContent` 写入，查询只暴露 `IReadOnlyShrinkModRegistry<T>`，owner 由当前 `ShrinkModContext` 决定。

### 2.4 把架构约束写成门禁

源项目的 EditMode architecture gate 会检查：

- 只读接口没有混入写操作。
- 已迁移调用方没有重新引入 Service Locator。
- command facade 返回结构化结果。
- 事实事件只在状态变更成功后发布。
- 兼容请求事件受 allowlist 约束。

方向正确，但部分测试通过读取 C# 源文本并匹配字符串实现，重命名、格式化或等价重构都可能导致误报。ShrinkSDK 应优先使用编译期类型检查、Cecil/程序集元数据、package.json/asmdef 图检查和真实 UPM 消费测试；只有无法从语义层验证的临时迁移约束才使用源码文本门禁。

### 2.5 文档按所有权分层

源项目使用总索引说明模块所有权和主流程，再由目录 README 说明模块内部细节，同时把高代价故障沉淀到 `KNOWN_PITFALLS.md`。这种结构比一份不断膨胀的全局文档更容易维护。

ShrinkSDK 继续保持：

- `DESIGN.md` 只描述当前架构和跨包约束。
- 包级用法、API 和限制放到各包 README。
- 已完成迁移与旧地图进入 `Docs/Archive`。
- 经验文档必须区分源码事实、工具验证和真实运行时验证。

## 3. 不应迁移的部分

### 3.1 大总程序集

`SeedsKey.Game` 的 28 个程序集引用和大量目录归属，使很多“模块”只有文件夹边界，没有独立编译边界。它适合渐进式游戏工程重构，不适合作为 SDK 包组织模板。

ShrinkSDK 必须继续以 UPM 包为发布边界、asmdef 为编译边界，主包不得反向依赖集成包。

### 3.2 业务单例与全局初始化入口

源项目仍有 32 个包含 `BaseManager<T>` 的文件、10 个运行时自动初始化文件，以及大量静态 `Instance`/EventBus 调用。它们说明迁移需要兼容面，不说明 SDK 应复制这种全局所有权模型。

ShrinkSDK 的静态入口只能是默认实例 facade；真实生命周期由实例、Context fiber 和 effect 拥有。

### 3.3 字符串场景名和补救式 Bootstrap

源项目的主流程依赖 `Entry -> MainMenu -> ...`、字符串场景名和 `DevBooter` 补齐孤立场景依赖。它们是具体游戏的流程合同，不属于通用 SDK。

SDK 可以提供组合、诊断和校验能力，但不应内置游戏场景名、玩法 ready 顺序或自动修复缺失场景对象。

### 3.4 游戏内容类型

存档槽、库存、法杖、战斗、房间、无尽模式和 Steam Workshop 的具体状态都应留在游戏层。SDK 只提供生命周期、注册、存储、传输和扩展机制。

## 4. 对 ShrinkSDK 的实际结论

这次审计没有发现需要从源项目复制的新容器或通用框架。ShrinkSDK 当前在包边界、可逆生命周期、热替换回滚、生成式注册和真实 UPM 消费验证上已经更严格。有效经验应表现为边界规则，而不是移植源项目实现：

1. 在组合入口集中显式绑定并一次性报告缺失项。
2. 查询依赖窄的只读能力；状态变更使用 command/RPC 并返回结构化结果。
3. 事件表达事实，不作为无结果的跨模块命令通道。
4. 可扩展注册表必须记录 owner，冲突要显式拒绝，卸载必须可逆。
5. 架构规则进入自动化门禁，但优先验证程序集和包语义，避免长期依赖源码字符串测试。
6. 文档中的数量、测试结果和运行时状态必须标注快照日期与证据来源。

上述规则已同步进入 `DESIGN.md`，并完成两项实现：

- `ShrinkModFramework 0.2.0` 使用只读查询接口与 owner-bound 写命令，支持 namespace、优先级覆盖、冲突拒绝和卸载恢复。
- UPM Consumer Validation 新增内部包循环和主包反向依赖 Integration 包的门禁，并支持 `-GraphOnly` 快速检查。

EventBus 2.0、Context、ModFramework 和 UPM Consumer Validation 继续作为这些规则的主要承载面，没有新增一套并行容器或 Service Locator。

## 5. 当前验证边界

- 已读取并对照源项目当前 git 基线、目录、asmdef、Composition、Modding 和 architecture gate 源码。
- 已读取并对照 ShrinkSDK 当前 App、Context、Mod registry、包清单与 UPM 消费验证脚本。
- 本次没有修改 Unity 序列化资产，也没有修改源项目 `justanyproject`。
- ShrinkSDK Unity Editor 已确认 `productName=ShrinkSDK`，重新编译为 0 error / 0 warning。
- `ShrinkModFramework.Tests` EditMode 为 13/13，通过 namespace、覆盖优先级、冲突、只读 API 边界和真实外部 DLL 热替换回滚。
- `dotnet build ShrinkSDK.sln /m:1` 为 0 warning / 0 error。
- UPM Consumer Validation 的 `-GraphOnly` 通过；仓库外临时 Unity 工程成功加载 20 个包和 42 个 asmdef。本次该轮使用 `-SkipTests`，包内 EditMode 覆盖由上述定向 Test Runner 承担。
- 没有重新运行 `justanyproject` 测试、ShrinkSDK PlayMode、Player Build 或运行时场景；附录 A 的历史结果仍不是本次验证。

## 附录 A：既有 EventBus 2.0 落地记录

以下内容保留此前审计推动的 EventBus 2.0 设计与验证记录。它描述 ShrinkSDK 当前工作树中的既有改造，不是本次重新执行的结果。

### A.1 统一事件模型

ShrinkSDK 使用一个事件协议和多个命名 Bus 实例：

```text
game       -> Unity 主线程
scene:id   -> Scene/Context 生命周期
mod:id     -> 模组专属线程或宿主指定调度
server     -> Inline 或专属线程
world:id   -> ECS playback 后进入对应 Bus
```

公共契约为 `IShrinkEvent`、`IShrinkCancelableEvent`、`IShrinkResultEvent<TResult>` 和 `IShrinkEventBus.Post/PostAsync/Attach`。订阅通过 `[ShrinkEventSubscriber]`、`[ShrinkSubscribe]` 声明，实例生命周期由 App、Context、Mod 或 Mono scope 接管。

### A.2 调度与生成

`ShrinkBusOptions` 固定 Bus 创建时的调度策略：

- `Inline`：调用线程直接执行。
- `MainThread`：Unity 环境切换到 UniTask PlayerLoop。
- `DedicatedThread`：单线程串行状态机。
- `TaskPool`：适合并行计算和 IO。

跨线程 `Post` 表示投递；需要等待完成、取消或结果时使用 `PostAsync`。队列容量、关闭排空、取消和异常策略由 options 明确配置。

生产注册由 Unity ILPostProcessor 或纯 .NET Roslyn Generator 生成强类型调用，不使用 `MethodInfo.Invoke` 或 `Delegate.DynamicInvoke`。没有生成合同的外部 DLL 不自动进入反射扫描。ECS/Burst 通过 `ShrinkEcsEventQueue<T>` 的 NativeQueue writer/playback 接入，Job 不直接调用托管 delegate 或 UniTask。

### A.3 参考边界

NeoForge 的 owner/lifecycle、稳定优先级、取消事件和并行事件约束可用于定义行为；MessagePipe 的专用 broker、稳定 handler 快照和低分配发布路径可用于实现参考。ShrinkSDK 不复制 NeoForge 的双协议模型，也不引入 MessagePipe 的 DI 或第二套 Publisher/Subscriber API。

### A.4 历史验证快照

此前工作记录的结果为：Unity EditMode `206/206`、EventBus PlayMode `1/1`，纯 .NET smoke 覆盖 Inline、DedicatedThread、实例与静态生成绑定；UI Toolkit 调试窗口完成结构读回和截图检查；Windows x64 Development IL2CPP Player 构建成功。

此前记录的 Play Mode benchmark 三轮中位数为：8 handler class `25.32M publish/s`、8 handler struct `35.02M publish/s`、30 handler `10.82M publish/s`，同步 struct Post 为 `0 B / 10,000,000` 次。真实 Burst Job 性能、其它平台 AOT 和设备侧吞吐仍属于发布前门禁；这些历史数字本次未重新运行确认。