docs: map existing codebase

2026-03-30 15:21:07 +08:00
commit 3c2bb02e33
7 changed files with 1320 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,175 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-03-30
+
+## Directory Layout
+
+```
+D:\code\new_git_code\arc/
+├── lib/                    # Flutter Dart source code
+├── android/                # Android native implementation
+├── test/                   # Unit tests for Dart code
+├── example/                # Example Flutter application
+├── docs/                   # Documentation files
+├── .dart_tool/             # Dart tool cache (generated)
+├── .planning/              # Planning documents (generated)
+└── pubspec.yaml            # Flutter package manifest
+```
+
+## Directory Purposes
+
+**lib:**
+- Purpose: Flutter plugin Dart source code
+- Contains: Public API, platform interface, method channel implementation
+- Key files: `arc.dart`, `arc_platform_interface.dart`, `arc_method_channel.dart`
+
+**android:**
+- Purpose: Android native implementation for ArcSoft SDK integration
+- Contains: Java source, ArcSoft SDK libraries, Gradle build config
+- Key files: `src/main/java/com/xiarui/arc/ArcPlugin.java`, `libs/arcsoft_face.jar`
+
+**test:**
+- Purpose: Unit tests for Dart plugin code
+- Contains: Mock platform implementations, method channel tests
+- Key files: `arc_test.dart`, `arc_method_channel_test.dart`
+
+**example:**
+- Purpose: Demonstrates plugin usage with camera-based face detection
+- Contains: Complete Flutter app with camera preview and detection UI
+- Key files: `lib/main.dart`, `integration_test/plugin_integration_test.dart`
+
+**docs:**
+- Purpose: External SDK documentation
+- Contains: ArcSoft face recognition API documentation
+- Key files: `虹软人脸识别接口文档.md`
+
+**android/libs:**
+- Purpose: ArcSoft native SDK JAR files
+- Contains: `arcsoft_face.jar` (face recognition), `arcsoft_image_util.jar` (image utilities)
+- Generated: No (third-party SDK)
+- Committed: Yes
+
+**android/src/main/jniLibs:**
+- Purpose: Native library files for different CPU architectures
+- Contains: `.so` files for arm64-v8a, armeabi-v7a
+- Generated: No (from ArcSoft SDK)
+- Committed: Yes
+
+## Key File Locations
+
+**Entry Points:**
+- `lib/arc.dart`: Public API entry point for plugin consumers
+- `android/src/main/java/com/xiarui/arc/ArcPlugin.java`: Android plugin registration and method handling
+- `example/lib/main.dart`: Example app entry point
+
+**Configuration:**
+- `pubspec.yaml`: Flutter package configuration, SDK version constraints
+- `android/build.gradle`: Android library build configuration, SDK dependencies
+- `android/src/main/AndroidManifest.xml`: Android permissions (CAMERA, INTERNET, STORAGE)
+
+**Core Logic:**
+- `lib/arc_platform_interface.dart`: Platform interface abstract class
+- `lib/arc_method_channel.dart`: Method channel implementation
+- `android/src/main/java/com/xiarui/arc/FaceEngineManager.java`: Singleton managing FaceEngine lifecycle
+
+**Data Models:**
+- `android/src/main/java/com/xiarui/arc/FaceInfo.java`: Face detection result model
+- `android/src/main/java/com/xiarui/arc/FaceErrorCode.java`: Error code enumeration (586 lines)
+
+**Testing:**
+- `test/arc_test.dart`: Mock platform tests
+- `test/arc_method_channel_test.dart`: Method channel unit tests
+- `android/src/test/java/com/xiarui/arc/ArcPluginTest.java`: Android unit tests
+
+## Naming Conventions
+
+**Files:**
+- Dart: lowercase with underscores, e.g., `arc_platform_interface.dart`
+- Java: PascalCase for classes, e.g., `ArcPlugin.java`, `FaceEngineManager.java`
+
+**Classes:**
+- Dart: PascalCase, e.g., `Arc`, `ArcPlatform`, `MethodChannelArc`
+- Java: PascalCase, e.g., `FaceEngineManager`, `FaceErrorCode`
+
+**Methods:**
+- Dart: camelCase with descriptive names, e.g., `activeOnline`, `detectFaces`, `extractFaceFeature`
+- Java: camelCase with handler prefix for dispatch, e.g., `handleActiveOnline`, `handleDetectFaces`
+
+**Variables:**
+- Dart: camelCase for local/instance variables
+- Java: camelCase, enum constants use UPPER_SNAKE_CASE, e.g., `MERR_ASF_ACTIVATION_FAIL`
+
+## Where to Add New Code
+
+**New Feature (Dart API):**
+- Primary code: `lib/arc.dart` - add public method
+- Interface: `lib/arc_platform_interface.dart` - add abstract method
+- Implementation: `lib/arc_method_channel.dart` - add method channel invocation
+
+**New Feature (Android Native):**
+- Handler: `android/src/main/java/com/xiarui/arc/ArcPlugin.java` - add case in `onMethodCall()` switch
+- Logic: `android/src/main/java/com/xiarui/arc/FaceEngineManager.java` - add SDK operation method
+
+**New Platform Support (iOS/Web):**
+- Create platform-specific implementation in appropriate directory
+- Register in `pubspec.yaml` under `plugin.platforms`
+
+**New Data Model:**
+- Location: `android/src/main/java/com/xiarui/arc/` alongside existing models
+- Pattern: JavaBean style with getters/setters and `toMap()` method
+
+**Tests:**
+- Dart tests: `test/` directory, named `*_test.dart`
+- Android tests: `android/src/test/java/com/xiarui/arc/` directory
+
+**Utilities:**
+- Shared helpers: `android/src/main/java/com/xiarui/arc/` as utility classes
+
+## Special Directories
+
+**android/libs:**
+- Purpose: ArcSoft SDK JAR files (third-party)
+- Generated: No
+- Committed: Yes (required for build)
+- Note: Contains `arcsoft_face.jar`, `arcsoft_image_util.jar`
+
+**android/src/main/jniLibs:**
+- Purpose: Native `.so` libraries for CPU architectures
+- Generated: No (from ArcSoft SDK distribution)
+- Committed: Yes
+- Architectures: arm64-v8a, armeabi-v7a
+
+**example/build:**
+- Purpose: Flutter/Gradle build artifacts
+- Generated: Yes
+- Committed: No (should be in .gitignore)
+
+**.dart_tool:**
+- Purpose: Dart package config and tool cache
+- Generated: Yes
+- Committed: No
+
+**.planning:**
+- Purpose: GSD planning documents
+- Generated: Yes (by GSD tools)
+- Committed: Yes (for team visibility)
+
+## Package Structure
+
+**Flutter Package:**
+- Package name: `arc`
+- Version: 0.0.1
+- SDK constraint: `^3.9.0`
+- Flutter constraint: `>=3.3.0`
+- Platforms: Android only (current)
+
+**Android Package:**
+- Package name: `com.xiarui.arc`
+- Plugin class: `ArcPlugin`
+- Min SDK: 24 (Android 7.0)
+- Compile SDK: 36
+- Java version: 11
+
+---
+
+*Structure analysis: 2026-03-30*