1

2026-04-21 12:57:33 +08:00
commit c000eb12f8
64 changed files with 7970 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,217 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-16
+
+## Directory Layout
+
+```
+ch34/                              # Flutter plugin root
+├── lib/                           # Dart source code
+│   ├── ch34.dart                  # Main library entry point (exports)
+│   ├── ch34_platform_interface.dart  # Backward compat: re-exports src/
+│   ├── ch34_method_channel.dart   # Backward compat: re-exports src/
+│   └── src/                       # Core implementation
+│       ├── ch34_manager.dart      # Public static API facade
+│       ├── ch34_platform_interface.dart  # Abstract platform interface
+│       ├── ch34_method_channel.dart      # MethodChannel implementation
+│       └── types/
+│           └── ch34_types.dart    # All data types and enums
+├── android/                       # Android native code
+│   ├── build.gradle               # Android library build config
+│   ├── settings.gradle            # Gradle settings
+│   ├── libs/                      # Native dependency JARs
+│   │   └── CH34XUARTDriver.jar    # WCH UART library
+│   └── src/
+│       ├── main/java/com/example/ch34/
+│       │   ├── Ch34Plugin.java           # Main plugin + MethodCallHandler
+│       │   ├── Ch34DataStreamHandler.java # Data EventChannel handler
+│       │   ├── Ch34ModemStreamHandler.java # Modem EventChannel handler
+│       │   ├── Ch34UsbStateStreamHandler.java # USB hotplug handler
+│       │   └── Ch34TypeConverter.java    # Type conversion utilities
+│       └── test/java/com/example/ch34/
+│           └── Ch34PluginTest.java       # Unit tests
+├── example/                       # Example Flutter app
+│   ├── lib/
+│   │   └── main.dart              # Example app with device scan/connect/send
+│   ├── test/
+│   │   └── widget_test.dart       # Widget test (stub)
+│   └── integration_test/
+│       └── plugin_integration_test.dart  # Integration test
+├── test/                          # Plugin unit tests
+│   ├── ch34_test.dart             # Platform interface + manager tests
+│   └── ch34_method_channel_test.dart     # MethodChannel mock tests
+├── docs/
+│   └── CH34X-api_docs.md          # WCH API documentation reference
+├── pubspec.yaml                   # Plugin package manifest
+├── analysis_options.yaml          # Dart linting config
+├── CHANGELOG.md                   # Version history
+├── LICENSE                        # License file
+├── README.md                      # Plugin documentation
+└── .gitignore                     # Git ignore rules
+```
+
+## Directory Purposes
+
+### `lib/` - Dart Source
+- **Purpose:** All Dart code for the Flutter plugin
+- **Key files:**
+  - `lib/ch34.dart` - Primary consumer import: `import 'package:ch34/ch34.dart';`
+  - `lib/src/ch34_manager.dart` - Static facade, all public APIs
+  - `lib/src/ch34_platform_interface.dart` - Abstract interface with 33 methods
+  - `lib/src/ch34_method_channel.dart` - MethodChannel + EventChannel implementation
+  - `lib/src/types/ch34_types.dart` - Shared data models and enums
+
+### `android/` - Android Native
+- **Purpose:** Java implementation bridging to WCH CH34X UART library
+- **Key files:**
+  - `android/src/main/java/com/example/ch34/Ch34Plugin.java` - Plugin entry point (788 lines)
+  - `android/build.gradle` - Library configuration (compileSdk 34, minSdk 21, Java 8)
+  - `android/libs/CH34XUARTDriver.jar` - WCH vendor SDK (binary dependency)
+
+### `example/` - Sample Application
+- **Purpose:** Demonstrates plugin usage for development and testing
+- **Key files:**
+  - `example/lib/main.dart` - Full working example: scan devices, open, set params, send/receive data
+
+### `test/` - Plugin Tests
+- **Purpose:** Unit tests for the Dart plugin code
+- **Contains:** MethodChannel mock tests, platform interface mock implementation
+
+## Key File Locations
+
+**Entry Points:**
+- `lib/ch34.dart`: Main library entry, consumer-facing import
+- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Android plugin entry, registered via `pubspec.yaml`
+
+**Configuration:**
+- `pubspec.yaml`: Plugin declaration, Android platform registration (`package: com.example.ch34`, `pluginClass: Ch34Plugin`)
+- `android/build.gradle`: Android library build configuration
+- `analysis_options.yaml`: Dart linting (extends `flutter_lints`)
+
+**Core Logic:**
+- `lib/src/ch34_manager.dart`: Static API facade (all consumer methods)
+- `lib/src/ch34_platform_interface.dart`: Abstract interface contract
+- `lib/src/ch34_method_channel.dart`: Channel communication implementation
+- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Native bridge logic
+
+**Types:**
+- `lib/src/types/ch34_types.dart`: All data classes (`UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`) and enums (`DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`)
+
+**Testing:**
+- `test/ch34_method_channel_test.dart`: Unit tests with mock platform
+- `test/ch34_test.dart`: Integration-style tests with real MethodChannel mock
+- `example/integration_test/plugin_integration_test.dart`: On-device integration test
+
+## Naming Conventions
+
+**Files:**
+- Dart: `snake_case.dart` for all files (e.g., `ch34_manager.dart`, `ch34_types.dart`)
+- Java: `PascalCase.java` for all classes (e.g., `Ch34Plugin.java`, `Ch34TypeConverter.java`)
+
+**Dart Classes:**
+- Public API class: `Ch34Manager` (static methods, facade pattern)
+- Platform interface: `Ch34Platform` (abstract, extends `PlatformInterface`)
+- Channel implementation: `MethodChannelCh34` (extends `Ch34Platform`)
+- Data types: `UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`
+- Enums: `DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`
+- Exception: `Ch34Exception`
+
+**Java Classes:**
+- Main plugin: `Ch34Plugin` (implements `FlutterPlugin`, `MethodCallHandler`)
+- Stream handlers: `Ch34DataStreamHandler`, `Ch34ModemStreamHandler`, `Ch34UsbStateStreamHandler`
+- Utility: `Ch34TypeConverter` (static methods only, private constructor)
+
+**MethodChannel names:**
+- Method channel: `'ch34'`
+- Data event channel: `'ch34/data'`
+- Modem event channel: `'ch34/modem'`
+- USB state event channel: `'ch34/usb_state'`
+
+**Method names:** Match Dart method names exactly (e.g., `enumDevice`, `openDevice`, `setSerialParameter`, `writeData`, `readData`)
+
+## Where to Add New Code
+
+**New Dart API Method:**
+1. Add abstract method signature to `lib/src/ch34_platform_interface.dart`
+2. Add concrete implementation to `lib/src/ch34_method_channel.dart` (using `methodChannel.invokeMethod()`)
+3. Add static wrapper to `lib/src/ch34_manager.dart` (delegating to `Ch34Platform.instance`)
+4. Add mock implementation in `test/ch34_method_channel_test.dart` for testing
+5. Add native handler in `android/src/main/java/com/example/ch34/Ch34Plugin.java`
+
+**New EventChannel (streaming):**
+1. Create new `*StreamHandler.java` in `android/src/main/java/com/example/ch34/`
+2. Register in `Ch34Plugin.onAttachedToEngine()`
+3. Add `EventChannel` and `StreamSubscription` in `lib/src/ch34_method_channel.dart`
+4. Add platform interface methods to `Ch34Platform`
+5. Add static wrappers to `Ch34Manager`
+
+**New Data Type:**
+- Add to `lib/src/types/ch34_types.dart`
+- Add corresponding conversion in `android/src/main/java/com/example/ch34/Ch34TypeConverter.java`
+
+**New Native Utility:**
+- Add to `android/src/main/java/com/example/ch34/` as a new Java class or extend existing
+
+## Module Boundaries
+
+### Dart Layer
+```
+lib/ch34.dart (exports)
+    |
+    v
+lib/src/ch34_manager.dart (static facade)
+    |
+    v
+lib/src/ch34_platform_interface.dart (abstract contract)
+    |
+    v
+lib/src/ch34_method_channel.dart (concrete implementation)
+    |
+    +---> lib/src/types/ch34_types.dart (shared types)
+```
+
+### Native Layer
+```
+Ch34Plugin.java (MethodCallHandler + 3 EventChannels)
+    |
+    +---> Ch34DataStreamHandler.java (data streaming)
+    +---> Ch34ModemStreamHandler.java (modem status streaming)
+    +---> Ch34UsbStateStreamHandler.java (USB hotplug streaming)
+    +---> Ch34TypeConverter.java (type conversion utilities)
+    |
+    v
+CH34XUARTDriver.jar (WCH vendor SDK)
+```
+
+### Platform Bridge
+```
+Dart: MethodChannel('ch34') <---> Java: Ch34Plugin (MethodCallHandler)
+Dart: EventChannel('ch34/data') <---> Java: Ch34DataStreamHandler
+Dart: EventChannel('ch34/modem') <---> Java: Ch34ModemStreamHandler
+Dart: EventChannel('ch34/usb_state') <---> Java: Ch34UsbStateStreamHandler
+```
+
+## Special Directories
+
+**`android/libs/`:**
+- Purpose: Contains binary JAR dependency (`CH34XUARTDriver.jar`)
+- Generated: No, committed to repo
+- Referenced by: `android/build.gradle` via `flatDir` repository
+
+**`example/`:**
+- Purpose: Self-contained Flutter app demonstrating plugin usage
+- Generated: No, committed to repo
+- Note: The example app package is `ch34_example`
+
+**`docs/`:**
+- Purpose: API documentation reference for WCH WCHUARTManager
+- Contains: `CH34X-api_docs.md` - comprehensive API documentation in Markdown
+
+**`lib/` root-level files:**
+- Purpose: Backward compatibility re-exports
+- `lib/ch34_platform_interface.dart` exports `src/ch34_platform_interface.dart`
+- `lib/ch34_method_channel.dart` exports `src/ch34_method_channel.dart`
+
+---
+
+*Structure analysis: 2026-04-16*