docs(mica-mqtt): 更新 opencode AGENTS.md

Author: ChunMengLu

AGENTS.md

@@ -11,7 +11,20 @@
 
 - **Language**: Java 8 (`<java.version>1.8</java.version>`).
 - **Build Tool**: Maven 3.x.
-- **Project Structure**: Multi-module Maven project (`mica-mqtt-client`, `mica-mqtt-server`, `mica-mqtt-codec`, `mica-mqtt-common`, `starter`).
+- **Project Structure**: Multi-module Maven project.
+
+### Modules
+
+| Module | Description |
+|--------|-------------|
+| `mica-mqtt-codec` | MQTT protocol codec |
+| `mica-mqtt-common` | Common utilities and models |
+| `mica-mqtt-core` | Core server/client interfaces |
+| `mica-mqtt-server` | MQTT broker implementation |
+| `mica-mqtt-client` | MQTT client implementation |
+| `mica-mqtt-broker` | Enhanced broker with cluster support (t-io based) |
+| `starter` | Spring Boot, Solon, JFinal integrations |
+| `example` | Usage examples |
 
 ### Key Commands
 
@@ -23,6 +36,7 @@
 | **Run Single Test Method** | `mvn -Dtest=TargetTestClass#methodName test` |
 | **Compile Only** | `mvn compile` |
 | **Package** | `mvn package -DskipTests` |
+| **Run Tests in Specific Module** | `cd mica-mqtt-broker && mvn test` |
 
 > **Note**: Always run tests after modifications to ensure no regressions.
 
@@ -40,7 +54,7 @@
 - **Packages**: `lowercase` (e.g., `org.dromara.mica.mqtt.core`).
 
 ### Lombok Usage
-- **Core Modules** (`mica-mqtt-server`, `mica-mqtt-client`, `mica-mqtt-common`, `mica-mqtt-codec`):
+- **Core Modules** (`mica-mqtt-server`, `mica-mqtt-client`, `mica-mqtt-common`, `mica-mqtt-codec`, `mica-mqtt-broker`):
   - **DO NOT USE LOMBOK**. 
   - Manually implement `getters`, `setters`, `equals`, `hashCode`, `toString`, and `constructors`.
   - Use the Builder pattern manually if complex object creation is needed (see `MqttWillMessage`).
@@ -71,13 +85,35 @@ All new Java files must include the Apache License 2.0 header:
 ### Logging
 - Use **SLF4J** for logging.
 - `private static final Logger logger = LoggerFactory.getLogger(ClassName.class);`
+- Use appropriate log levels: `debug` for verbose info, `info` for important events, `warn/error` for issues.
+- Avoid excessive `info` logging in high-frequency code paths (e.g., message handling).
 
 ### Imports
 - Avoid wildcard imports (`import java.util.*;`).
-- Group imports:
+- Group imports in this order:
   1. Project specific imports (`org.dromara...`)
   2. Third-party libraries (`org.slf4j...`, `org.tio...`)
   3. Standard Java (`java...`, `javax...`)
+- Use import statements instead of fully qualified class names in code.
+
+### Error Handling
+- Use specific exception types rather than generic `Exception`.
+- Log exceptions with appropriate context before rethrowing or handling.
+- Avoid swallowing exceptions silently unless explicitly intended.
+- Example:
+  ```java
+  try {
+      // code
+  } catch (IOException e) {
+      logger.error("Failed to process message from node: {}", nodeId, e);
+      return;
+  }
+  ```
+
+### Types
+- Use primitive types where possible for performance.
+- Use `List`, `Map`, `Set` interfaces rather than concrete implementations in method signatures.
+- Initialize collections with appropriate implementations (e.g., `ArrayList`, `HashMap`, `HashSet`).
 
 ## 3. Architecture & Patterns
 
@@ -87,16 +123,27 @@ All new Java files must include the Apache License 2.0 header:
 - **Design Patterns**:
   - **Builder**: Used for complex configuration/message objects (e.g., `MqttPublishMessage.builder()`).
   - **Listener**: Heavily used for events (`MqttProtocolListener`, `IMqttMessageListener`).
+  - **Decorator**: Used in `mica-mqtt-broker` for session management (`ClusterMqttSessionManager` wraps `IMqttSessionManager`).
+
+### Cluster Module (mica-mqtt-broker)
+- Built on t-io cluster for node-to-node communication.
+- Uses `MqttBroker.create()` as entry point for cluster brokers.
+- Fluent API for configuration (`MqttClusterConfig.enabled(true).clusterPort(9001)`).
+- Cluster messages inherit from `ClusterMessage` base class.
+- Session state is synchronized across nodes via `ClusterMqttSessionManager`.
 
 ## 4. Testing
 
-- Write unit tests for new logic using JUnit.
+- Write unit tests for new logic using JUnit (Jupiter).
 - Place tests in the `src/test/java` directory corresponding to the package structure.
 - Mock external dependencies where possible to keep tests fast.
+- Cluster integration tests may have Windows-specific cleanup issues with t-io; focus on test assertions passing.
 
 ## 5. Agent Behavior Rules
 
 - **No Assumptions**: Always verify file existence and content before editing.
 - **Minimal Changes**: Only modify what is necessary to fulfill the request.
 - **Preserve Style**: If you see a file using a specific style (even if it contradicts general rules), follow the file's local style (except for clearly erroneous logic).
 - **Safety**: Do not commit secrets or breaking changes without user confirmation.
+- **Verification**: After making changes, always run `mvn compile` to verify the code compiles.
+- **Testing**: Run relevant tests after modifications to ensure no regressions.