docs: sync api and planning docs

docs/api/XCEngine/Input/Input.md

@@ -10,15 +10,34 @@
 
 `XCEngine::Input` 解决的是“如何把平台消息变成引擎可查询输入状态”这个问题。当前模块的核心由两层组成：
 
-- `InputManager` 负责保存当前帧输入状态、提供轮询查询接口，并同步分发输入事件。
+- `InputManager` 负责保存键盘、鼠标的按住态、本帧按下边沿、本帧释放边沿、鼠标位移和滚轮状态，并同步广播输入事件。
 - `InputModule` 负责定义平台桥接接口，把操作系统窗口消息翻译成 `InputManager::Process*` 调用。
 
 当前版本的成熟度是分层的：
 
 - 键盘与鼠标的基础轮询和事件分发已经可用，并且有单元测试覆盖。
-- Windows 路径已经有实际桥接实现 `WindowsInputModule`。
+- Windows 路径已经有实际桥接实现 [WindowsInputModule](../Platform/Windows/WindowsInputModule/WindowsInputModule.md)。
 - 触摸与摇杆相关 API 仍然偏预留位，当前 `InputManager` 自身并不会产生这些输入。
 
+## 当前帧语义
+
+当前输入模块明确区分三类状态：
+
+- 按住态
+  - `IsKeyDown()`、`IsMouseButtonDown()`、`GetAxis()`、`GetAxisRaw()`、`GetButton()`、`IsAnyKeyDown()`
+- 抬起态
+  - `IsKeyUp()`、`IsMouseButtonUp()`
+  - 这类查询只是“当前没有按住”，不是“本帧刚释放”
+- 边沿态
+  - 按下边沿: `IsKeyPressed()`、`IsMouseButtonClicked()`、`GetButtonDown()`、`IsAnyKeyPressed()`
+  - 释放边沿: `IsKeyReleased()`、`IsMouseButtonReleased()`、`GetButtonUp()`
+
+这里最容易误解的点有两个：
+
+- `IsKeyUp()` / `IsMouseButtonUp()` 与 `IsKeyReleased()` / `IsMouseButtonReleased()` 不是一回事。
+- `GetAxisRaw()` 当前和 `GetAxis()` 使用同一套实现，都会根据持续按住状态返回 `-1 / 0 / 1`；它现在不是“只在本帧按下才非零”的边沿接口。
+- 键盘按下边沿查询当前不会过滤 `repeat`。如果平台在后续帧继续发送重复 `KeyDown`，`IsKeyPressed()`、`GetButtonDown()`、`IsAnyKeyPressed()` 仍可能再次成立。
+
 ## 设计要点
 
 - 同时保留轮询接口和事件接口，方便游戏逻辑与 UI 系统按各自习惯接入。
@@ -28,9 +47,12 @@
 
 ## 当前实现限制
 
-- `GetAxisRaw` 当前按“本帧按下边沿”计算，而不是按“持续按住”计算，这一点和很多引擎的 `GetAxisRaw` 直觉不同。
-- `ClearAxes` 会同时清空轴和按钮映射，名字比实际行为更窄。
+- `GetAxisRaw()` 当前与 `GetAxis()` 完全一致，都不做平滑、重力或灵敏度处理。
+- 默认注册的 `Mouse X` / `Mouse Y` 轴虽然存在，但仍绑定到 `KeyCode::None`，所以当前查询结果始终为 `0.0f`。
+- 键盘按下边沿语义是“本帧收到 `ProcessKeyDown()` 消息”，不是“严格意义上的首次物理按下”。
+- `ClearAxes()` 会同时清空轴和按钮映射，名字比实际行为更窄。
 - `InputTypes::KeyCode` 的底层数值当前存在重复项，而 `InputManager` 又直接把这些值当作数组下标。
+- `InputManager::Shutdown()` 不会清空事件监听器；如果跨生命周期复用单例，需要调用方自己管理订阅。
 - `InputManager` 暴露了触摸接口，但当前代码路径没有填充触摸状态。
 
 ## 头文件
@@ -43,7 +65,7 @@
 
 ## 相关指南
 
-- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、帧边界和平台桥接如何配合工作。
+- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、边沿状态、帧边界和平台桥接如何配合工作。
 
 ## 相关实现