docs: update resources API docs

docs/api/resources/filearchive/close.md

@@ -0,0 +1,22 @@
+# FileArchive::Close
+
+关闭归档。
+
+## 方法签名
+
+```cpp
+void Close() override;
+```
+
+## 详细描述
+
+关闭归档并重置内部状态。清空归档路径并标记为无效状态。
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/textures/");
+// 使用归档...
+archive.Close();
+```

docs/api/resources/filearchive/enumerate.md

@@ -0,0 +1,31 @@
+# FileArchive::Enumerate
+
+枚举匹配的文件。
+
+## 方法签名
+
+```cpp
+void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override;
+```
+
+## 详细描述
+
+枚举归档目录中与指定模式匹配的文件。当前实现为 stub，仅清空输出数组，未实现实际的模式匹配功能。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `pattern` | `const Containers::String&` | 文件匹配模式（如 `*.png`、`textures/*.jpg`） |
+| `outFiles` | `Containers::Array<Containers::String>&` | 输出容器，接收匹配的文件路径列表 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+Containers::Array<Containers::String> files;
+archive.Enumerate("*.png", files);
+// 注意：当前实现返回空数组
+```

docs/api/resources/filearchive/exists.md

@@ -0,0 +1,36 @@
+# FileArchive::Exists
+
+检查文件是否存在。
+
+## 方法签名
+
+```cpp
+bool Exists(const Containers::String& fileName) const override;
+```
+
+## 详细描述
+
+检查归档内是否存在指定文件。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要检查的文件名（相对于归档路径） |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 文件存在返回 `true`，否则返回 `false` |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+if (archive.Exists("textures/player.png")) {
+    // 文件存在
+}
+```

docs/api/resources/filearchive/filearchive.md

@@ -2,19 +2,17 @@
 
 **命名空间**: `XCEngine::Resources`
 
-**类型**: `class` (extends IArchive)
+**类型**: `class`
 
-**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。
+**头文件**: `XCEngine/Resources/FileArchive.h`
+
+**继承自**: `IArchive`
+
+**描述**: 文件归档读取器，将文件系统目录作为虚拟归档进行访问。
 
 ## 概述
 
-`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。
-
-## 头文件
-
-```cpp
-#include <XCEngine/Resources/FileArchive.h>
-```
+`FileArchive` 实现了 `IArchive` 接口，用于将文件系统目录作为虚拟归档进行访问。它维护已打开目录的路径和有效性状态，支持读取文件、检查存在性、获取文件大小等操作。
 
 ## 继承关系
 
@@ -25,60 +23,53 @@ IArchive
 
 ## 公共方法
 
-### 构造与析构
-
 | 方法 | 描述 |
 |------|------|
-| `FileArchive()` | 默认构造 |
-| `~FileArchive()` | 析构函数，关闭归档 |
-
-### IArchive 接口实现
-
-| 方法 | 描述 |
-|------|------|
-| `bool Open(const Containers::String& path) override` | 打开归档文件 |
-| `void Close() override` | 关闭归档文件 |
-| `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 |
-| `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 |
-| `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 |
-| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） |
-| `bool IsValid() const override` | 检查归档是否有效 |
-
-## 实现说明
-
-**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。
-
-### 访问器
-
-| 方法 | 描述 |
-|------|------|
-| `const Containers::String& GetPath() const` | 获取归档文件路径 |
+| [`FileArchive()`](filearchive.md) | 默认构造 |
+| [`~FileArchive()`](filearchive.md) | 析构函数，自动关闭归档 |
+| [`Open(...)`](open.md) | 打开归档目录 |
+| [`Close()`](close.md) | 关闭归档 |
+| [`Read(...)`](read.md) | 读取文件数据 |
+| [`GetSize(...)`](getsize.md) | 获取文件大小 |
+| [`Exists(...)`](exists.md) | 检查文件是否存在 |
+| [`Enumerate(...)`](enumerate.md) | 枚举匹配的文件（暂未实现） |
+| [`IsValid()`](filearchive.md) | 检查归档是否有效 |
+| [`GetPath()`](filearchive.md) | 获取归档路径 |
 
 ## 使用示例
 
 ```cpp
+#include <XCEngine/Resources/FileArchive.h>
+
+// 创建并打开归档
 FileArchive archive;
-if (archive.Open("data/resources.pak")) {
+if (archive.Open("resources/textures/")) {
     // 检查文件是否存在
-    if (archive.Exists("textures/player.png")) {
+    if (archive.Exists("player.png")) {
         // 获取文件大小
-        size_t size = archive.GetSize("textures/player.png");
+        size_t size = archive.GetSize("player.png");
         
         // 读取文件内容
         Containers::Array<Core::uint8> buffer(size);
-        archive.Read("textures/player.png", buffer.Data(), size, 0);
+        if (archive.Read("player.png", buffer.Data(), size, 0)) {
+            // 处理文件数据
+        }
     }
     
-    // 枚举文件
+    // 枚举匹配的文件
     Containers::Array<Containers::String> files;
-    archive.Enumerate("textures/*.png", files);
+    archive.Enumerate("*.png", files);
     
     archive.Close();
 }
 ```
 
+## 实现说明
+
+- `Enumerate()` 当前为 stub，仅清空输出数组，未实现模式匹配功能。
+
 ## 相关文档
 
-- [IArchive](../filesystem/filesystem.md) - 归档接口
-- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
-- [Resources 总览](../resources.md) - 返回模块总览
+- [Resources 模块总览](../resources.md) - 返回模块总览
+- [IArchive](../resourcefilesystem/resourcefilesystem.md) - 归档接口定义
+- [ResourceFileSystem](../resourcefilesystem/resourcefilesystem.md) - 资源文件系统

docs/api/resources/filearchive/getsize.md

@@ -0,0 +1,37 @@
+# FileArchive::GetSize
+
+获取文件大小。
+
+## 方法签名
+
+```cpp
+size_t GetSize(const Containers::String& fileName) const override;
+```
+
+## 详细描述
+
+获取归档内指定文件的字节大小。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要查询的文件名（相对于归档路径） |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `size_t` | 文件字节大小，文件不存在或归档无效时返回 0 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+size_t size = archive.GetSize("textures/player.png");
+if (size > 0) {
+    // 文件存在，准备读取
+}
+```

docs/api/resources/filearchive/open.md

@@ -0,0 +1,34 @@
+# FileArchive::Open
+
+打开归档目录。
+
+## 方法签名
+
+```cpp
+bool Open(const Containers::String& path) override;
+```
+
+## 详细描述
+
+打开指定路径的目录作为归档。归档路径可以是绝对路径或相对路径。方法会设置内部路径并标记归档为有效状态。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `path` | `const Containers::String&` | 归档目录路径 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 始终返回 `true`。当前实现不验证路径是否真实存在。 |
+
+## 示例
+
+```cpp
+FileArchive archive;
+if (archive.Open("resources/textures/")) {
+    // 归档已打开
+}
+```

docs/api/resources/filearchive/read.md

@@ -0,0 +1,42 @@
+# FileArchive::Read
+
+读取文件数据。
+
+## 方法签名
+
+```cpp
+bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override;
+```
+
+## 详细描述
+
+从归档中读取指定文件的全部或部分内容。文件路径是相对于归档目录的路径。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `fileName` | `const Containers::String&` | 要读取的文件名（相对于归档路径） |
+| `buffer` | `void*` | 读取数据的目标缓冲区 |
+| `size` | `size_t` | 要读取的字节数 |
+| `offset` | `size_t` | 文件内起始偏移位置 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 读取成功返回 `true`，失败返回 `false` |
+
+## 示例
+
+```cpp
+FileArchive archive;
+archive.Open("resources/");
+
+size_t fileSize = archive.GetSize("textures/player.png");
+Containers::Array<Core::uint8> buffer(fileSize);
+
+if (archive.Read("textures/player.png", buffer.Data(), fileSize, 0)) {
+    // 文件读取成功
+}
+```