175 lines
5.9 KiB
Markdown
175 lines
5.9 KiB
Markdown
# 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* |