docs: 添加 Axis Innovators Box 框架完整 API 文档

- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
2026-01-03 08:46:19 +08:00
parent 06f36fc3f0
commit 7badbb0d8e
29 changed files with 3011 additions and 2275 deletions
--- a/事件类集合技术文档.md
+++ b/事件类集合技术文档.md
@@ -0,0 +1,122 @@
+# Axis Innovators Box 事件类集合技术文档
+
+**包路径:** `com.axis.innovators.box.events.*`  
+**主要功能:** 作为事件总线（EventBus）的载体，定义系统各模块间的通信数据结构  
+**作者:** tzdwindows 7
+
+---
+
+## 1. 概述
+
+本篇文档总结了 **Axis Innovators Box** 框架中定义的核心事件类。这些类作为 `EventBus` 分发的数据负载（Payload），涵盖了应用程序生命周期、UI 渲染、用户交互及系统设置等多个维度。
+
+框架采用了 **Java Records (JDK 16+)** 和 **常规 POJO** 混合编写的方式：
+*   **Records**: 用于纯数据传输，简洁高效。
+*   **Classes**: 用于需要逻辑处理或可变状态（如事件拦截）的复杂场景。
+
+---
+
+## 2. 核心事件分类详解
+
+### 2.1 系统生命周期事件
+
+#### `StartupEvent` (Record)
+*   **触发时机**: 应用程序启动阶段。
+*   **用途**: 允许插件或子模块在系统就绪时获取主程序实例并执行初始化。
+*   **字段**:
+    *   `AxisInnovatorsBox main`: 主程序入口实例。
+
+---
+
+### 2.2 主窗口与 UI 交互事件
+
+#### `MainWindowEvents` (Container Class)
+内部包含两个核心 Record，用于处理主窗口的不同阶段：
+*   **`initialize` (Record)**:
+    *   **触发时机**: 主窗口初始化加载时。
+    *   **用途**: 向主面板 (`mainPanel`) 添加自定义组件。
+*   **`update` (Record)**:
+    *   **触发时机**: 窗口重绘或更新周期。
+    *   **用途**: 执行基于 `Graphics` 的自定义绘制逻辑。
+
+#### `TABUIEvents` (Class)
+*   **用途**: 管理选项卡（Tab）组件的 UI 属性设置。
+*   **内部类 `update`**: 专门用于选项卡的重绘事件，传递 `Graphics` 上下文。
+
+#### `TopicsUpdateEvents` (Class)
+*   **触发时机**: 当系统主题发生变更（如切换深色模式/更换皮肤）时。
+*   **用途**: 通知所有 UI 组件同步更新样式。
+*   **字段**:
+    *   `String themeName`: 主题名称。
+    *   `boolean darkTheme`: 是否为暗黑模式。
+
+---
+
+### 2.3 文件与 IO 操作事件
+
+#### `OpenFileEvents` (Class)
+*   **触发时机**: 当程序接收到外部文件打开请求（如拖拽文件入窗口）时。
+*   **核心功能**: **流程控制**。
+*   **关键字段**:
+    *   `File filePath`: 文件路径。
+    *   `String extension`: 文件后缀名。
+    *   `boolean isContinue`: 默认值为 `true`。监听器可以通过 `setContinue(false)` 来**拦截**后续操作，阻止程序打开该文件。
+
+---
+
+### 2.4 设置与配置事件
+
+#### `SettingsLoadEvents` (Record)
+*   **触发时机**: 设置对话框加载时。
+*   **用途**: 动态扩展设置界面。开发者可以获取 `JPanel content` 容器，向其中注入新的设置项（如复选框、输入框）。
+*   **字段**:
+    *   `WindowsJDialog dialog`: 设置窗口实例。
+    *   `JPanel content`: 承载设置内容的容器面板。
+
+---
+
+## 3. 事件一览表
+
+| 事件类名 | 类型 | 核心字段 | 应用场景 |
+| :--- | :--- | :--- | :--- |
+| `StartupEvent` | Record | `main` | 插件初始化、全局资源准备 |
+| `MainWindowEvents.initialize` | Record | `mainWindow`, `mainPanel` | 注入主界面组件 |
+| `MainWindowEvents.update` | Record | `mainWindow`, `g` | 自定义画布渲染 |
+| `OpenFileEvents` | Class | `filePath`, `isContinue` | 文件打开监听、格式校验与拦截 |
+| `SettingsLoadEvents` | Record | `dialog`, `content` | 动态添加设置选项 |
+| `TABUIEvents` | Class | `javax`, `card` | 选项卡组件管理 |
+| `TopicsUpdateEvents` | Class | `themeName`, `darkTheme` | 皮肤切换、实时调色板更新 |
+
+---
+
+## 4. 使用代码示例
+
+### 示例 1：拦截特定格式的文件打开
+```java
+@SubscribeEvent
+public void onFileOpen(OpenFileEvents event) {
+    if (event.getExtension().equalsIgnoreCase("tmp")) {
+        System.out.println("拒绝打开临时文件");
+        event.setContinue(false); // 拦截流程
+    }
+}
+```
+
+### 示例 2：在系统启动时注册组件
+```java
+@SubscribeEvent
+public void onStartup(StartupEvent event) {
+    System.out.println("Axis Innovators Box 已启动: " + event.main().getClass().getName());
+}
+```
+
+### 示例 3：动态添加设置项
+```java
+@SubscribeEvent
+public void onSettingsLoad(SettingsLoadEvents event) {
+    event.content().add(new JButton("扩展插件设置"));
+}
+```
+
+---
+*文档生成时间: 2026-01-02*
--- a/api-documentation/events/BrowserCreationCallback.md
+++ b/api-documentation/events/BrowserCreationCallback.md
@@ -0,0 +1,83 @@
+# BrowserCreationCallback 接口技术文档
+
+**包路径:** `com.axis.innovators.box.events.BrowserCreationCallback`  
+**类型:** 接口 (Interface)  
+**主要功能:** 浏览器窗口布局自定义回调  
+**作者:** tzdwindows 7
+
+---
+
+## 1. 概述
+
+`BrowserCreationCallback` 是 **Axis Innovators Box** 框架中用于高度定制浏览器窗口布局的扩展接口。
+
+在框架启动嵌入式浏览器窗口（如 HTML 查看器、数据库管理工具、或 AI 界面）时，默认会执行一套标准的布局逻辑（通常是将浏览器组件充满整个内容区域）。通过实现此接口，开发者可以拦截并接管窗口的布局过程，从而在浏览器组件周边添加自定义的 UI 元素（如侧边栏、工具栏、状态栏等）。
+
+## 2. 核心方法详解
+
+### 2.1 `onLayoutCustomization`
+
+```java
+boolean onLayoutCustomization(
+        Window window,
+        Container contentPane,
+        Component browserComponent,
+        Object builder
+);
+```
+
+#### 参数说明：
+*   **`window`**: 当前正在创建的顶级窗口对象（通常是 `JFrame` 或 `JDialog` 的实例）。
+*   **`contentPane`**: 窗口的主内容面板。开发者应在此容器上执行 `setLayout` 或 `add` 操作。
+*   **`browserComponent`**: 已经实例化完成的浏览器渲染组件（UI 组件）。
+*   **`builder`**: 触发创建流程的构建器对象（通常是内部的 `BrowserWindowBuilder`）。通过此对象可以获取更多上下文配置。
+
+#### 返回值逻辑：
+*   **`true` (已处理)**: 告诉框架：*“我已经手动安排好了所有组件的布局，请不要再执行系统默认的布局逻辑。”*
+*   **`false` (未完全处理)**: 告诉框架：*“我可能做了一些预处理（如设置了背景色），但请继续执行默认的布局逻辑（通常是将 `browserComponent` 放入 `BorderLayout.CENTER`）。”*
+
+---
+
+## 3. 使用场景
+
+该回调接口通常用于以下高级自定义需求：
+1.  **添加导航栏**: 在浏览器组件上方添加地址栏、后退/前进按钮。
+2.  **集成侧边栏**: 在浏览器左侧添加树状菜单或历史记录面板。
+3.  **多组件混排**: 将浏览器作为界面的一部分，与其他 Swing 组件（如表格、控制台）共同展示。
+4.  **注入装饰器**: 为浏览器窗口添加自定义的边框、水印或重写背景。
+
+---
+
+## 4. 代码示例：在浏览器上方添加工具栏
+
+以下示例展示了如何使用该回调在浏览器窗口中插入一个简单的工具栏：
+
+```java
+BrowserCreationCallback myCallback = (window, contentPane, browserComponent, builder) -> {
+    // 1. 设置内容面板布局
+    contentPane.setLayout(new BorderLayout());
+    
+    // 2. 创建自定义工具栏
+    JPanel toolbar = new JPanel(new FlowLayout(FlowLayout.LEFT));
+    toolbar.add(new JButton("刷新"));
+    toolbar.add(new JButton("主页"));
+    
+    // 3. 将自定义组件和浏览器组件添加到面板
+    contentPane.add(toolbar, BorderLayout.NORTH);
+    contentPane.add(browserComponent, BorderLayout.CENTER);
+    
+    // 4. 返回 true，表示我们已经手动完成了布局
+    return true; 
+};
+```
+
+---
+
+## 5. 设计优势
+
+*   **非侵入式修改**: 无需修改框架核心代码即可改变浏览器窗口的呈现方式。
+*   **灵活性**: 基于接口的设计允许每个工具（Tool）根据自身业务需求定义完全不同的布局方案。
+*   **控制反转 (IoC)**: 框架负责处理繁琐的浏览器引擎初始化，而将 UI 的最终决定权交还给开发者。
+
+---
+*文档生成时间: 2026-01-02*
--- a/api-documentation/events/EventBus.md
+++ b/api-documentation/events/EventBus.md
@@ -0,0 +1,105 @@
+# EventBus 类技术文档
+
+**包路径:** `com.axis.innovators.box.events.EventBus`  
+**主要功能:** 发布-订阅（Publish-Subscribe）模式的事件中心  
+**作者:** tzdwindows 7
+
+---
+
+## 1. 概述
+
+`EventBus` 是 **Axis Innovators Box** 框架的核心通信组件。它通过事件驱动的方式实现模块间的解耦，允许应用程序的不同部分在无需相互引用的情况下进行信息交换。
+
+该实现采用了 **基于注解（Annotation-based）** 的方法，通过反射动态扫描和分发事件。它不仅支持简单的事件发布，还具备完整的对象生命周期管理（注册/注销）以及跨类层级的事件监听能力。
+
+## 2. 核心架构设计
+
+### 2.1 存储机制
+`EventBus` 内部维护了两个关键的映射表，以保证高效的事件分发和快速的资源清理：
+1.  **`eventSubscribers` (Map<Class<?>, List<Subscriber>>)**:
+    *   **用途**: 用于事件发布。
+    *   **逻辑**: 以事件的 `Class` 类型为键，快速找到所有订阅了该事件的监听者列表。
+2.  **`targetSubscribers` (Map<Object, List<Subscriber>>)**:
+    *   **用途**: 用于对象注销。
+    *   **逻辑**: 以订阅对象实例为键，记录该对象注册的所有监听器，确保在对象销毁时能一次性清理所有相关引用，防止内存泄漏。
+
+### 2.2 订阅者封装 (`Subscriber`)
+内部类 `Subscriber` 封装了执行事件回调所需的三个要素：
+*   **Target**: 接收事件的对象实例。
+*   **Method**: 标记了 `@SubscribeEvent` 的方法对象。
+*   **EventType**: 该监听器关注的事件类型（方法参数类型）。
+
+---
+
+## 3. 关键功能详解
+
+### 3.1 动态注册 (`register`)
+当一个对象调用 `register` 时，`EventBus` 会：
+1.  **递归扫描**: 遍历目标对象的所有方法，包括从父类继承的方法（通过 `getSuperclass()` 向上递归）。
+2.  **注解验证**: 筛选出带有 `@SubscribeEvent` 注解的方法。
+3.  **参数检查**: 确保方法有且仅有一个参数（该参数即为监听的事件类型）。
+4.  **建立索引**: 将符合条件的方法封装成 `Subscriber` 并存入上述两个映射表中。
+
+### 3.2 事件发布 (`post`)
+当发布一个事件对象时：
+1.  **类型匹配**: 获取事件的 `Class` 类型。
+2.  **副本保护**: 在遍历订阅者列表前创建 `copySubs` 副本。这是为了防止在执行事件回调过程中，某个监听者尝试注销自己而引发 `ConcurrentModificationException`。
+3.  **反射调用**: 通过 `setAccessible(true)` 强制调用（即使是私有方法），并将事件对象传入。
+
+### 3.3 生命周期管理
+*   **注销 (`unregister`)**: 彻底切断事件总线对目标对象的引用，是资源清理的关键步骤。
+*   **熔断 (`shutdown`)**: 一旦总线关闭，所有的 `post` 操作将失效，确保在应用关闭阶段不再产生新的业务逻辑执行。
+
+---
+
+## 4. API 接口说明
+
+| 方法 | 描述 |
+| :--- | :--- |
+| `void register(Object target)` | 扫描目标对象并注册所有合法的事件监听器。 |
+| `void unregister(Object target)` | 移除该对象在总线上的所有订阅关系。 |
+| `boolean post(Object event)` | 向所有订阅了该事件类型的监听者发送事件。 |
+| `void shutdown()` | 关闭事件总线。 |
+
+---
+
+## 5. 技术亮点
+
+*   **继承支持**: 通过 `while (clazz != null)` 循环，支持在父类中定义通用的事件处理逻辑，子类只需注册即可继承该能力。
+*   **解耦性**: 发布者完全不知道谁在处理事件，监听者也无需知道事件由谁产生，只需关注事件本身。
+*   **健壮性**: 内置 `handleException` 机制，确保某个监听器执行失败时不会影响总线上其他监听器的正常运行。
+
+---
+
+## 6. 使用代码示例
+
+### 定义事件
+```java
+public class UserLoginEvent {
+    public final String username;
+    public UserLoginEvent(String name) { this.username = name; }
+}
+```
+
+### 注册监听器
+```java
+public class LogModule {
+    @SubscribeEvent
+    public void onUserLogin(UserLoginEvent event) {
+        System.out.println("用户登录: " + event.username);
+    }
+}
+
+// 在初始化处
+EventBus bus = new EventBus();
+LogModule logModule = new LogModule();
+bus.register(logModule);
+```
+
+### 发布事件
+```java
+bus.post(new UserLoginEvent("Admin"));
+```
+
+---
+*文档生成时间: 2026-01-02*
--- a/api-documentation/events/GlobalEventBus.md
+++ b/api-documentation/events/GlobalEventBus.md
@@ -0,0 +1,101 @@
+# GlobalEventBus 类技术文档
+
+**包路径:** `com.axis.innovators.box.events.GlobalEventBus`  
+**主要功能:** 全局单例事件总线访问点  
+**作者:** tzdwindows 7
+
+---
+
+## 1. 概述
+
+`GlobalEventBus` 是 **Axis Innovators Box** 框架中 `EventBus` 机制的静态包装类。它的核心作用是提供一个**全局唯一的、线程安全**的事件分发中心。
+
+在一个复杂的解耦系统中，虽然可以实例化多个 `EventBus`（用于局部通信），但通常需要一个贯穿整个应用程序生命周期的主总线。`GlobalEventBus` 通过预定义的静态实例，消除了在不同模块、控制器或类之间传递 `EventBus` 引用的复杂性，实现了真正的“随处注册，随处发布”。
+
+## 2. 核心架构设计
+
+### 2.1 单例模式 (Singleton)
+该类采用了最简洁的静态常量初始化方式：
+```java
+public static final EventBus EVENT_BUS = new EventBus();
+```
+*   **线程安全性**: 依赖于 Java 类加载机制，保证了 `EVENT_BUS` 实例在全局范围内的唯一性且只会被初始化一次。
+*   **可见性**: `public` 修饰符允许框架内任何位置的代码直接访问，无需通过复杂的依赖注入（DI）容器。
+
+### 2.2 职责定位
+`GlobalEventBus` 本身不包含复杂的逻辑，它更像是一个“门户”：
+1.  **持有者**: 持有 `EventBus` 的核心实例。
+2.  **默认中心**: 作为系统默认的、最高层级的通信渠道。
+
+---
+
+## 3. 关键特性
+
+*   **零配置访问**: 开发者无需关心 `EventBus` 的初始化时机，直接通过 `GlobalEventBus.EVENT_BUS` 即可获取能力。
+*   **一致性**: 确保了核心系统事件（如应用启动、配置变更、全局错误处理）都在同一个频道内流动。
+*   **低耦合**: 模块 A 只需要知道 `GlobalEventBus` 和事件类，而无需知道模块 B 的存在，即可实现与模块 B 的交互。
+
+---
+
+## 4. API 使用指南
+
+由于 `GlobalEventBus` 是对 `EventBus` 的静态引用，其主要操作均通过 `EVENT_BUS` 成员完成。
+
+| 操作类型 | 代码示例 | 说明 |
+| :--- | :--- | :--- |
+| **注册监听** | `GlobalEventBus.EVENT_BUS.register(this);` | 在组件初始化（如 `onInit`）时调用。 |
+| **发送事件** | `GlobalEventBus.EVENT_BUS.post(new ConfigChangedEvent());` | 在任何业务逻辑发生点触发。 |
+| **取消注册** | `GlobalEventBus.EVENT_BUS.unregister(this);` | 在组件销毁（如 `onDestroy`）时调用，防止内存泄漏。 |
+
+---
+
+## 5. 最佳实践
+
+### 5.1 何时使用 GlobalEventBus？
+*   **全局生命周期事件**: 如用户登录/登出、系统配置刷新。
+*   **跨层级通信**: 例如底层的网络模块需要通知最顶层的 UI 界面显示通知。
+*   **临时任务**: 不需要长期维护引用关系的瞬时事件处理。
+
+### 5.2 注意事项
+1.  **内存管理**: 凡是使用 `GlobalEventBus.EVENT_BUS.register()` 的对象，必须在生命周期结束时手动调用 `unregister()`，否则该对象将因为被全局静态引用持有而无法被 JVM 回收。
+2.  **性能考量**: 虽然单次分发效率很高，但若全局总线上挂载了数千个监听器，频繁发布高频事件（如鼠标移动）可能会产生性能抖动。
+
+---
+
+## 6. 使用代码示例
+
+### 场景：全局错误处理系统
+```java
+// 1. 定义全局异常事件
+public class GlobalErrorEvent {
+    public final String message;
+    public GlobalErrorEvent(String msg) { this.message = msg; }
+}
+
+// 2. 在 UI 层注册监听
+public class MainNotificationUI {
+    public MainNotificationUI() {
+        GlobalEventBus.EVENT_BUS.register(this);
+    }
+
+    @SubscribeEvent
+    public void onErrorMessage(GlobalErrorEvent event) {
+        showToast("系统错误: " + event.message);
+    }
+}
+
+// 3. 在底层业务逻辑处发布
+public class DatabaseWorker {
+    public void doWork() {
+        try {
+            // 某些业务操作...
+        } catch (Exception e) {
+            // 发现错误，直接向全局总线抛出，无需持有 UI 的引用
+            GlobalEventBus.EVENT_BUS.post(new GlobalErrorEvent(e.getMessage()));
+        }
+    }
+}
+```
+
+---
+*文档生成时间: 2026-01-02*
--- a/api-documentation/events/SubscribeEvent.md
+++ b/api-documentation/events/SubscribeEvent.md
@@ -0,0 +1,102 @@
+# SubscribeEvent 注解技术文档
+
+**包路径:** `com.axis.innovators.box.events.SubscribeEvent`  
+**主要功能:** 标记事件订阅方法并定义执行优先级  
+**作者:** tzdwindows 7
+
+---
+
+## 1. 概述
+
+`@SubscribeEvent` 是 **Axis Innovators Box** 事件系统的核心元数据注解。它被用于标记类中的方法，使其能够被 `EventBus` 识别并注册为事件监听器（Listener）。
+
+该注解的存在实现了“声明式”的事件监听。开发者无需实现复杂的接口，只需在任意方法上添加此注解，并确保方法签名符合规范（单参数），即可自动参与系统的事件流转。
+
+## 2. 注解配置说明
+
+### 2.1 运行时保留 (`@Retention`)
+设置为 `RetentionPolicy.RUNTIME`。这意味着注解信息在类加载后依然保留在 JVM 中，允许 `EventBus` 在运行时通过**反射（Reflection）**动态扫描到这些方法。
+
+### 2.2 目标范围 (`@Target`)
+设置为 `ElementType.METHOD`。明确限定该注解仅能用于方法上。
+
+---
+
+## 3. 核心属性详解
+
+### 3.1 `priority()`
+*   **类型**: `int`
+*   **默认值**: `0`
+*   **功能**: 定义事件处理的先后顺序。
+*   **逻辑规则**:
+    *   当一个事件被发布时，`EventBus` 会根据所有订阅该事件的方法的 `priority` 值进行排序。
+    *   **值越大，优先级越高**，该方法将越早接收到事件通知。
+    *   当优先级相同时，执行顺序取决于系统反射获取方法的自然顺序（通常不保证固定顺序）。
+
+---
+
+## 4. 订阅方法规范
+
+为了使 `@SubscribeEvent` 生效，标记的方法必须遵循以下约束：
+
+1.  **参数限制**: 方法必须有且仅有一个参数。该参数的类型即为该监听器关注的事件类型。
+2.  **访问权限**: 虽然 `EventBus` 内部通过 `setAccessible(true)` 支持私有方法，但建议根据模块化设计合理设置方法的可见性。
+3.  **返回类型**: 通常为 `void`。因为事件发布是单向的分发过程，`EventBus` 不会处理监听方法的返回值。
+
+---
+
+## 5. 使用示例
+
+### 5.1 基础用法
+```java
+@SubscribeEvent
+public void onGenericEvent(MessageEvent event) {
+    System.out.println("收到消息: " + event.getContent());
+}
+```
+
+### 5.2 优先级应用场景
+假设有一个日志系统，需要在业务逻辑处理前记录日志，在业务逻辑处理后进行清理：
+
+```java
+public class SecurityMonitor {
+    // 高优先级：先检查权限
+    @SubscribeEvent(priority = 100)
+    public void checkPermission(UserActionEvent event) {
+        if (!event.user.hasAccess()) {
+            event.setCancelled(true);
+        }
+    }
+}
+
+public class BusinessLogic {
+    // 默认优先级：正常执行业务
+    @SubscribeEvent(priority = 0)
+    public void handleAction(UserActionEvent event) {
+        if (!event.isCancelled()) {
+            executeTask();
+        }
+    }
+}
+```
+
+---
+
+## 6. 技术亮点
+
+*   **非侵入式设计**: 业务类不需要继承任何父类或实现特定接口，保持了代码的纯净性。
+*   **精细化控制**: 通过 `priority` 属性，解决了传统观察者模式中监听器执行顺序不可控的问题。
+*   **自描述性**: 开发者通过阅读代码中的注解，可以清晰地识别出哪些逻辑是响应式的，增强了代码的可读性。
+
+---
+
+## 7. 配合 EventBus 的工作流程
+
+1.  **扫描**: `EventBus.register(obj)` 被调用。
+2.  **识别**: 遍历 `obj` 及其父类，筛选出所有带有 `@SubscribeEvent` 的方法。
+3.  **解析**: 读取 `priority` 数值以及参数类型。
+4.  **排序**: 将这些信息封装为 `Subscriber` 对象并根据优先级存入订阅列表。
+5.  **分发**: `post(event)` 时，按优先级从高到低依次反射调用。
+
+---
+*文档生成时间: 2026-01-02*