docs: map existing codebase

.planning/codebase/CONCERNS.md

@@ -0,0 +1,195 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-03-30
+
+## Tech Debt
+
+**iOS Platform Support Missing:**
+- Issue: The plugin only supports Android platform; iOS implementation is completely absent
+- Files: `pubspec.yaml` (no iOS platform definition), `lib/arc_platform_interface.dart`, `lib/arc_method_channel.dart`
+- Impact: Plugin cannot be used in iOS applications; limits market reach
+- Fix approach: Create iOS native implementation using Swift/Objective-C with ArcSoft SDK iOS bindings
+
+**Unimplemented Mock Methods in Tests:**
+- Issue: `MockArcPlatform` in test file does not implement `registerFaceFeature` and `registerFaceFeatureBatch` methods
+- Files: `test/arc_test.dart` (lines 8-60)
+- Impact: Tests will fail when calling registration methods; incomplete test coverage
+- Fix approach: Add mock implementations for all missing methods in `MockArcPlatform`
+
+**Placeholder Documentation:**
+- Issue: CHANGELOG.md and LICENSE files contain placeholder TODO text
+- Files: `CHANGELOG.md` (line 3), `LICENSE` (line 1)
+- Impact: Project appears incomplete; may confuse users about licensing
+- Fix approach: Replace placeholder text with actual content
+
+## Known Bugs
+
+**No explicit engine disposal:**
+- Symptoms: `FaceEngine` instance in `FaceEngineManager` is never nullified after `unInit()`
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (lines 268-278)
+- Trigger: Calling `unInit()` then attempting to reuse engine
+- Workaround: Re-initialize engine after disposal
+
+**State inconsistency after initialization failure:**
+- Symptoms: If `init()` fails, `isInitialized` remains false but `faceEngine` object still exists
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (lines 141-159)
+- Trigger: Engine initialization with invalid parameters
+- Workaround: Check both `isInitialized` flag and error code before proceeding
+
+## Security Considerations
+
+**Hardcoded SDK Credentials in Example:**
+- Risk: Real SDK credentials (appId, sdkKey, activeKey) hardcoded in example application
+- Files: `example/lib/main.dart` (lines 41-43)
+  ```dart
+  final String _appId = '4nPFuS2TYAQh9werHL2qbKjtTH9nnoixk7G6yqSUyjVH';
+  final String _sdkKey = 'aWMTT3coxNQFETg9f3BGHCiBznAApXmcHFF3J5yQbsZ';
+  final String _activeKey = 'NEAT7AU4KLCEK682';
+  ```
+- Current mitigation: Comment instructs users to replace with own keys (line 286)
+- Recommendations: Use environment variables or config file; never commit real credentials; add `.env.example` template
+
+**Credential Transmission via Method Channel:**
+- Risk: Sensitive credentials (appId, sdkKey, activeKey) passed through method channel without encryption
+- Files: `lib/arc_method_channel.dart` (lines 24-28), `android/src/main/java/com/xiarui/arc/ArcPlugin.java` (lines 95-97)
+- Current mitigation: None
+- Recommendations: Credentials are passed to native SDK which handles secure activation; acceptable for current architecture
+
+**Feature Data Privacy:**
+- Risk: Face feature data transmitted between Flutter and native layers could be intercepted
+- Files: `lib/arc_method_channel.dart`, `android/src/main/java/com/xiarui/arc/FaceEngineManager.java`
+- Current mitigation: Data stays within app boundary
+- Recommendations: Ensure no logging of feature data; consider encryption for stored features
+
+## Performance Bottlenecks
+
+**Large Binary Data Transfer:**
+- Problem: Image data (NV21 format, potentially several MB per frame) transferred through method channel for each detection
+- Files: `lib/arc_method_channel.dart` (lines 55-61), `android/src/main/java/com/xiarui/arc/ArcPlugin.java` (lines 154-157)
+- Cause: Method channel serialization overhead for large byte arrays
+- Improvement path: Consider using FFI for direct memory access; reduce image resolution; implement frame skipping
+
+**Real-time Detection Frame Rate:**
+- Problem: `_isDetecting` flag prevents concurrent processing but may cause frame drops
+- Files: `example/lib/main.dart` (lines 406-407, 471-473)
+- Cause: Sequential processing - new frames wait until current detection completes
+- Improvement path: Implement queue-based processing with configurable frame skip; use dedicated detection thread
+
+**Feature Extraction Overhead:**
+- Problem: Feature extraction called synchronously, blocking UI thread potential
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (lines 365-366)
+- Cause: SDK operation runs on method channel thread
+- Improvement path: Move heavy processing to background thread pool; provide async callbacks
+
+## Fragile Areas
+
+**NV21 Format Constraints:**
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (lines 179-189)
+- Why fragile: Image width must be multiple of 4, height must be multiple of 2 for NV21 format - violation causes runtime errors
+- Safe modification: Always validate dimensions before calling SDK; add Flutter-side validation
+- Test coverage: No tests for invalid dimension handling
+
+**Singleton State Management:**
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (lines 54-59)
+- Why fragile: Singleton pattern with mutable `lastRgbLiveness` field; concurrent access risk
+- Safe modification: Add synchronization for mutable fields; or use ThreadLocal for liveness results
+- Test coverage: No concurrent access tests
+
+**Camera Preview Orientation:**
+- Files: `example/lib/main.dart` (line 556)
+- Why fragile: Fixed `quarterTurns: -1` rotation may not work for all devices/orientations
+- Safe modification: Calculate rotation based on device orientation and camera sensor orientation
+- Test coverage: No tests for different device orientations
+
+## Scaling Limits
+
+**Face Database Size:**
+- Current capacity: Depends on ArcSoft SDK limits (typically 50,000 faces)
+- Limit: Memory consumption increases with registered faces; search time increases
+- Scaling path: Implement pagination; use external database for large-scale deployments; consider face clustering
+
+**Image Resolution:**
+- Current capacity: Default camera resolution (medium preset)
+- Limit: Higher resolution = slower detection, more memory usage
+- Scaling path: Allow configurable resolution; implement dynamic resolution adjustment based on device capability
+
+**Concurrent Detection Requests:**
+- Current capacity: Single detection at a time (`_isDetecting` flag)
+- Limit: Multiple simultaneous requests queue up
+- Scaling path: Implement request queue with priority; batch processing; dedicated worker threads
+
+## Dependencies at Risk
+
+**ArcSoft Face SDK:**
+- Risk: Third-party proprietary SDK; licensing and availability concerns
+- Impact: Plugin entirely dependent on ArcSoft SDK availability and compatibility
+- Migration plan: Abstract SDK interface; allow alternative face recognition backends (e.g., ML Kit, OpenCV)
+
+**camera package:**
+- Risk: External dependency in example app; version compatibility
+- Impact: Example app functionality dependent on camera plugin stability
+- Migration plan: Keep camera package updated; abstract camera interface for alternative implementations
+
+**Flutter SDK Version:**
+- Risk: Requires SDK ^3.9.0 which is relatively new
+- Files: `pubspec.yaml` (line 7)
+- Impact: Older Flutter versions cannot use plugin
+- Migration plan: Consider lowering SDK constraint if backward compatibility needed
+
+## Missing Critical Features
+
+**Face Search (1:N Matching):**
+- Problem: `registerFaceFeature` and `registerFaceFeatureBatch` exist but no `searchFaceFeature` method to query registered faces
+- Files: `lib/arc.dart`, `android/src/main/java/com/xiarui/arc/FaceEngineManager.java`
+- Blocks: Cannot implement 1:N face recognition workflow (find matching face from database)
+
+**Engine Uninit from Flutter:**
+- Problem: No Flutter API to release engine resources
+- Files: `lib/arc.dart` (no unInit method)
+- Blocks: Memory leak if engine not properly released; cannot reset engine state
+
+**Error Code Documentation for Flutter:**
+- Problem: Error codes defined in Java but no Flutter-accessible documentation
+- Files: `android/src/main/java/com/xiarui/arc/FaceErrorCode.java` (comprehensive), `lib/arc.dart` (no error code constants)
+- Blocks: Flutter developers cannot interpret error codes without referencing native code
+
+**IR Liveness Detection:**
+- Problem: Only RGB liveness detection implemented; IR liveness not exposed
+- Files: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` (only ASF_LIVENESS mask)
+- Blocks: Cannot use more secure IR-based liveness detection if hardware available
+
+## Test Coverage Gaps
+
+**Native Unit Tests:**
+- What's not tested: All methods except `getPlatformVersion` in `ArcPluginTest.java`
+- Files: `android/src/test/java/com/xiarui/arc/ArcPluginTest.java` (only 1 test method)
+- Risk: Native method handling bugs undetected
+- Priority: High
+
+**Flutter Integration Tests:**
+- What's not tested: Actual face detection with real image data; end-to-end workflows
+- Files: No integration test files in `test/` directory
+- Risk: Real-world usage patterns not validated
+- Priority: High
+
+**Method Channel Tests:**
+- What's not tested: All methods except `getPlatformVersion` in method channel test
+- Files: `test/arc_method_channel_test.dart` (lines 24-26)
+- Risk: Method channel communication bugs for complex methods undetected
+- Priority: Medium
+
+**Edge Case Tests:**
+- What's not tested: Invalid parameters, null data, oversized images, engine not initialized
+- Files: All test files lack edge case coverage
+- Risk: Runtime crashes on invalid inputs
+- Priority: Medium
+
+**Mock Implementation Completeness:**
+- What's not tested: `registerFaceFeature`, `registerFaceFeatureBatch` methods in mock
+- Files: `test/arc_test.dart` (`MockArcPlatform` missing methods)
+- Risk: Tests fail or skip when new methods are used
+- Priority: Low
+
+---
+
+*Concerns audit: 2026-03-30*