docs: rebuild audio and core api docs

docs/api/XCEngine/Core/Asset/AsyncLoader/AsyncLoader.md

@@ -2,41 +2,132 @@
 
 **命名空间**: `XCEngine::Resources`
 
-**类型**: `class (singleton)`
+**类型**: `class`
 
 **头文件**: `XCEngine/Core/Asset/AsyncLoader.h`
 
-**描述**: 定义 `XCEngine/Core/Asset` 子目录中的 `AsyncLoader` public API。
+**描述**: 为资源异步加载预留的请求队列与回调分发接口，但当前实现仍明显未完成。
 
-## 概述
+## 角色概述
 
-`AsyncLoader.h` 是 `XCEngine/Core/Asset` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`AsyncLoader` 的 API 形状表达得很清楚：它想成为资源系统里的后台加载服务，负责接收 `LoadRequest`、在工作线程里执行 loader，然后把结果回送给主线程或调用方。
 
-## 声明概览
+这也是商业引擎资源系统非常常见的一层设计，因为真正的资源加载通常要考虑：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `LoadRequest` | `struct` | 头文件中的公开声明。 |
-| `AsyncLoader` | `class` | 头文件中的公开声明。 |
+- 后台 I/O
+- 导入配置复制
+- 回调线程切换
+- 进度统计
+- 取消与批量清理
 
-## 公共方法
+但当前版本还只搭好了外形，没有把执行链真正闭环。
 
-| 方法 | 描述 |
-|------|------|
-| [Get](Get.md) | 获取相关状态或对象。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Submit](Submit.md) | 公开方法，详见头文件声明。 |
-| [Update](Update.md) | 更新运行时状态。 |
-| [IsLoading](IsLoading.md) | 查询当前状态。 |
-| [GetPendingCount](GetPendingCount.md) | 获取相关状态或对象。 |
-| [GetProgress](GetProgress.md) | 获取相关状态或对象。 |
-| [CancelAll](CancelAll.md) | 判断当前条件下是否可执行。 |
-| [Cancel](Cancel.md) | 判断当前条件下是否可执行。 |
-| [~AsyncLoader()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [AsyncLoader()](Constructor.md) | 构造对象。 |
+## 当前结构
+
+`LoadRequest` 当前包含：
+
+- `path`
+- `type`
+- `callback`
+- `settings`
+- `requestId`
+
+`requestId` 通过原子自增静态计数器生成。
+
+`AsyncLoader` 自身同时提供两种使用方式：
+
+- `AsyncLoader::Get()` 返回全局单例
+- [ResourceManager](../ResourceManager/ResourceManager.md) 在 `Initialize()` 中再拥有一个自己的 `AsyncLoader` 实例
+
+这说明当前架构上已经出现“双入口”现象。真实运行时主要走的是 `ResourceManager` 持有的那一份，而不是 `AsyncLoader::Get()` 单例。
+
+## 当前行为
+
+### 初始化与关闭
+
+- `Initialize(workerThreadCount)` 当前直接忽略参数，不创建线程。
+- `Shutdown()` 当前只是调用 `CancelAll()`。
+
+也就是说，初始化并不会启动任何真正的后台执行环境。
+
+### 提交请求
+
+`Submit()` 当前流程是：
+
+1. 组装 `LoadRequest`
+2. 通过 `FindLoader(type)` 查找 loader
+3. 如果没有 loader，立即通过回调返回失败结果
+4. 如果有 loader，只把请求推入 `m_pendingQueue`
+5. 递增 `m_pendingCount` 与 `m_totalRequested`
+
+关键点在第 4 步之后就结束了。当前没有工作线程，也没有任何地方会真正从 `m_pendingQueue` 取出请求并调用 `loader->Load()`。
+
+### 更新与完成回调
+
+`Update()` 当前只会处理 `m_completedQueue`。但现在的 `QueueCompleted()` 是空实现，所以成功加载请求根本不会进入完成队列。
+
+这意味着：
+
+- “无 loader”的失败回调会立即触发
+- “有 loader”的请求会一直留在 pending 队列里
+- `IsLoading()` 可能长期保持 true
+- `GetProgress()` 也不会自然推进到你期待的完成状态
+
+## 导入配置与生命周期边界
+
+`LoadRequest` 保存的是 `ImportSettings*` 裸指针。当前版本里：
+
+- `Submit()` 不会克隆 settings
+- 队列里只是保留原始指针
+- 由于真正后台执行逻辑还没做完，这个问题暂时没有完全暴露
+
+但从接口契约上讲，这已经说明未来如果异步路径做实，调用方就不能假设 settings 会被安全复制。当前文档必须把这个生命周期边界讲清楚。
+
+## 设计取向
+
+把异步加载单独做成服务是对的。它让资源系统可以朝商业引擎常见的“主线程驱动资源引用，后台线程完成 I/O 与解码”的方向演进。
+
+但当前版本更准确的描述应该是：
+
+- 它是异步加载架构草图
+- 不是已经可投产的后台加载器
+
+如果你需要稳定的当前行为，应该优先走 [ResourceManager::Load](../ResourceManager/Load.md) 的同步路径。
+
+## 线程语义
+
+- `m_pendingQueue` 和 `m_completedQueue` 各自有独立 mutex 保护。
+- `m_pendingCount` / `m_completedCount` 使用原子计数。
+- 但没有真实工作线程，也没有完整的跨线程回调时序保证。
+
+## 当前实现限制
+
+- `Initialize()` 忽略 `workerThreadCount`。
+- 没有后台线程处理 `m_pendingQueue`。
+- `QueueCompleted()` 是空实现。
+- `Update()` 只能消费完成队列，但当前没有成功请求会进入完成队列。
+- `Cancel(requestId)` 是 stub。
+- `AsyncLoader::Get()` 与 `ResourceManager` 自持实例并存，架构入口不统一。
+- `ImportSettings*` 当前按裸指针跨请求传递，没有复制或所有权说明。
+
+## 相关方法
+
+- [Constructor](Constructor.md)
+- [Destructor](Destructor.md)
+- [Get](Get.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)
+- [Submit](Submit.md)
+- [Update](Update.md)
+- [IsLoading](IsLoading.md)
+- [GetPendingCount](GetPendingCount.md)
+- [GetProgress](GetProgress.md)
+- [CancelAll](CancelAll.md)
+- [Cancel](Cancel.md)
 
 ## 相关文档
 
-- [当前目录](../Asset.md) - 返回 `Asset` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [当前模块](../Asset.md)
+- [ResourceManager](../ResourceManager/ResourceManager.md)
+- [ImportSettings](../ImportSettings/ImportSettings.md)
+- [API 总索引](../../../../main.md)