docs: rebuild Input API content

docs/api/XCEngine/Input/Input.md

@@ -4,19 +4,50 @@
 
 **类型**: `module`
 
-**描述**: 输入状态查询、输入事件与平台接入接口。
+**描述**: 提供输入状态查询、逻辑轴与按钮映射、同步事件分发以及平台输入桥接接口。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Input` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine::Input` 解决的是“如何把平台消息变成引擎可查询输入状态”这个问题。当前模块的核心由两层组成：
+
+- `InputManager` 负责保存当前帧输入状态、提供轮询查询接口，并同步分发输入事件。
+- `InputModule` 负责定义平台桥接接口，把操作系统窗口消息翻译成 `InputManager::Process*` 调用。
+
+当前版本的成熟度是分层的：
+
+- 键盘与鼠标的基础轮询和事件分发已经可用，并且有单元测试覆盖。
+- Windows 路径已经有实际桥接实现 `WindowsInputModule`。
+- 触摸与摇杆相关 API 仍然偏预留位，当前 `InputManager` 自身并不会产生这些输入。
+
+## 设计要点
+
+- 同时保留轮询接口和事件接口，方便游戏逻辑与 UI 系统按各自习惯接入。
+- 逻辑轴和逻辑按钮采用名字映射，风格上接近 Unity 旧版 Input Manager，而不是设备级输入系统。
+- 平台桥接与输入状态解耦，`InputModule` 可以替换，而游戏代码继续依赖 `InputManager`。
+- 当前实现是轻量级同步模型，不是线程安全的跨平台输入框架。
+
+## 当前实现限制
+
+- `GetAxisRaw` 当前按“本帧按下边沿”计算，而不是按“持续按住”计算，这一点和很多引擎的 `GetAxisRaw` 直觉不同。
+- `ClearAxes` 会同时清空轴和按钮映射，名字比实际行为更窄。
+- `InputTypes::KeyCode` 的底层数值当前存在重复项，而 `InputManager` 又直接把这些值当作数组下标。
+- `InputManager` 暴露了触摸接口，但当前代码路径没有填充触摸状态。
 
 ## 头文件
 
-- [InputAxis](InputAxis/InputAxis.md) - `InputAxis.h`
-- [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h`
-- [InputManager](InputManager/InputManager.md) - `InputManager.h`
-- [InputModule](InputModule/InputModule.md) - `InputModule.h`
-- [InputTypes](InputTypes/InputTypes.md) - `InputTypes.h`
+- [InputAxis](InputAxis/InputAxis.md) - `InputAxis.h`，逻辑轴配置对象。
+- [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h`，输入事件结构体定义。
+- [InputManager](InputManager/InputManager.md) - `InputManager.h`，全局输入状态与事件中心。
+- [InputModule](InputModule/InputModule.md) - `InputModule.h`，平台输入桥接接口。
+- [InputTypes](InputTypes/InputTypes.md) - `InputTypes.h`，键盘、鼠标和摇杆的基础枚举。
+
+## 相关指南
+
+- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、帧边界和平台桥接如何配合工作。
+
+## 相关实现
+
+- [WindowsInputModule](../Platform/Windows/WindowsInputModule/WindowsInputModule.md) - Windows 平台当前的具体输入桥接实现。
 
 ## 相关文档