react-native-document-processor 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# react-native-document-processor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Phiên bản **0.2.0** — thư viện React Native chụp tài liệu, tạo PDF từ ảnh và đọc
+QR/barcode bằng native trên iOS và Android.
+
+- [Repository](https://github.com/quocvu12345/react-native-document-processor)
+- [Package npm](https://www.npmjs.com/package/react-native-document-processor)
+- Source của phiên bản này: tag `v0.2.0`.
+
+## Cài đặt
+
+```sh
+yarn add react-native-document-processor@0.2.0 --exact
+# Hoặc: npm install react-native-document-processor@0.2.0 --save-exact
+pod install --project-directory=ios
+```
+
+Yêu cầu Android API 28+, iOS 15.1+ và React Native có autolinking. Đã kiểm tra
+trong ứng dụng host dùng React Native 0.83. Camera Android cần Google Play services;
+model ML Kit đọc barcode được đóng gói sẵn. iOS cần khai báo
+`NSCameraUsageDescription` trong `Info.plist` của ứng dụng.
+
+Rebuild native app sau khi cài hoặc nâng cấp thư viện. Reload JavaScript hoặc
+cập nhật OTA không thêm được native module vào binary đã cài. Thư viện cần
+native build riêng, chẳng hạn Expo development build.
+
+Metadata giấy phép hiện là `UNLICENSED`.
+
+## Thay đổi trong 0.2.0
+
+- Sửa lỗi không đọc được QR trên iOS Simulator khi Vision không tạo được
+  inference context: yêu cầu chỉ đọc QR sử dụng Vision revision 1 trên Simulator.
+- Thiết bị iOS thật tiếp tục dùng revision mặc định. API JavaScript giữ nguyên.
+- Bản sửa được đóng gói trực tiếp trong source native của npm.
+
+## Chụp tài liệu và tạo PDF
+
+`scanDocument` mở camera native: VisionKit trên iOS và ML Kit Document Scanner
+trên Android. Người dùng có thể phát hiện biên, crop và xác nhận các trang.
+
+```ts
+import {
+  processDocumentImages,
+  scanDocument,
+} from 'react-native-document-processor';
+import RNFS from 'react-native-fs';
+
+const capture = await scanDocument({ croppedImageQuality: 100 });
+if (capture.status === 'cancel') return;
+
+let output: Awaited<ReturnType<typeof processDocumentImages>> | undefined;
+try {
+  output = await processDocumentImages(capture.scannedImages, {
+    onProgress: (completed, total) => updateProgress(completed, total),
+    isCancelled: () => hasLeftScreen,
+  });
+  // output.pdfUri: PDF để lưu hoặc upload
+  // output.pages: mã QR, trạng thái và preview của từng trang
+  // output.directoryUri: thư mục chứa PDF và preview, do caller sở hữu
+  await consumeDocument(output);
+} finally {
+  // Chỉ dọn output sau khi mọi thao tác lưu/upload/hiển thị đã hoàn tất.
+  const temporaryPaths = [
+    ...capture.scannedImages,
+    ...(output ? [output.directoryUri] : []),
+  ];
+  await Promise.all(
+    temporaryPaths.map(path => RNFS.unlink(path).catch(() => undefined)),
+  );
+}
+```
+
+`updateProgress`, `hasLeftScreen` và `consumeDocument` là logic của ứng dụng host.
+Ví dụ dùng `react-native-fs` để dọn file; thư viện này không phải dependency của
+package và có thể được thay bằng API filesystem của ứng dụng.
+
+`croppedImageQuality` nhận giá trị từ 0 đến 100; Android giữ JPEG gốc của scanner.
+Mỗi lần chụp trả về `{ status: 'success' | 'cancel', scannedImages: string[] }`.
+iOS trả tối đa 24 trang trong một lần chụp. Ứng dụng có thể gọi lại camera và gộp
+các ảnh theo thứ tự trước khi tạo PDF.
+
+`processDocumentImages` trả về các trang đánh số từ 1:
+
+```ts
+{
+  pdfUri: 'file:///cache/session/document.pdf',
+  directoryUri: 'file:///cache/session',
+  pages: [
+    {
+      page: 1,
+      rawValues: ['doc|d|0030358'],
+      status: 'decoded', // 'decoded' | 'not-detected' | 'error'
+      previewUri: 'file:///cache/session/page-1.jpg', // tùy chọn
+    },
+  ],
+}
+```
+
+Dùng `{ scanQr: false }` khi chỉ cần PDF. Khi đó native bỏ qua đọc QR và tạo
+preview. Native không xóa ảnh đầu vào. Sau thành công, caller chịu trách nhiệm
+xóa output và ảnh chụp khi không còn sử dụng. Nếu hủy hoặc có lỗi trước khi
+chuyển quyền sở hữu, wrapper tự giải phóng output của session.
+
+Hủy được kiểm tra giữa các trang và trước/sau khi đóng PDF. Trang đang được
+Vision/ML Kit xử lý sẽ hoàn tất trước khi dọn tài nguyên. Lỗi đọc QR nằm trong
+trạng thái từng trang; lỗi decode ảnh hoặc ghi PDF hủy cả session để tránh trả
+PDF thiếu trang. Lỗi tạo preview không làm mất mã đã đọc được.
+
+## Luồng xử lý native
+
+```text
+Ảnh đã chụp
+  → decode và chuẩn hóa hướng EXIF
+  → đọc QR trên bitmap
+  → tạo preview và ghi trang PDF
+  → trả PDF URI, mã QR và trạng thái từng trang về JavaScript
+```
+
+Các trang được xử lý tuần tự trên worker. Không truyền bitmap/base64 qua bridge
+và không cần render lại PDF vừa tạo để đọc QR.
+
+- iOS dùng ImageIO, Vision, Core Graphics và autorelease pool theo từng trang.
+- Android dùng ImageDecoder, ML Kit barcode-scanning bundled 17.3.0 và PDF writer
+  ghi JPEG trực tiếp; camera dùng play-services-mlkit-document-scanner 16.0.0.
+- Ảnh đầu vào được giới hạn cạnh dài 4096 px; PDF tối đa 3000 px, JPEG 92%;
+  preview tối đa 1000 px, JPEG 85%. Không phóng to ảnh nhỏ.
+- Luồng xử lý tài liệu thử thêm bốn vùng chồng lấn 60% khi chưa thấy payload
+  `doc|...|<số>`. Kết quả vẫn chứa các chuỗi QR thô để ứng dụng tự parse, đối chiếu
+  và gộp mã theo nghiệp vụ.
+
+## Đọc QR/barcode từ ảnh
+
+```ts
+import { scanBarcodes, scanQrImage } from 'react-native-document-processor';
+
+const qr = await scanQrImage('/path/to/image.jpg');
+const all = await scanBarcodes('file:///path/to/image.jpg');
+const selected = await scanBarcodes('content://provider/image', {
+  formats: ['qr', 'ean-13'],
+});
+// { values: ['0030358'], codes: [{ value: '0030358', format: 'qr' }] }
+```
+
+API chạy trên worker, giới hạn ảnh 4096 px và chuẩn hóa EXIF. Không mở camera,
+tạo PDF hoặc xóa ảnh đầu vào. Hỗ trợ đường dẫn tuyệt đối, `file://` và thêm
+`content://` trên Android; không nhận URL mạng hoặc base64.
+
+Không phát hiện mã trả `{ values: [], codes: [] }`. Ảnh hỏng hoặc lỗi decoder
+reject Promise. Kết quả hỗ trợ nhiều mã, loại mã trùng và giữ nguyên chuỗi,
+kể cả số 0 đầu.
+
+Các format: `qr`, `ean-13`, `ean-8`, `upc-a`, `upc-e`, `code-128`, `code-39`,
+`code-93`, `codabar`, `itf`, `pdf-417`, `aztec`, `data-matrix`. iOS quy đổi UPC-A
+từ EAN-13 có số 0 đầu khi yêu cầu UPC-A.
+
+Package không render PDF có sẵn. Để đọc QR trong PDF local, ứng dụng cần render
+lần lượt từng trang thành ảnh bằng một thư viện PDF, rồi gọi `scanQrImage` và
+xóa ảnh tạm sau khi xử lý. Giữ tệp PDF gốc để lưu hoặc upload.
+
+## Phát triển và kiểm tra
+
+Clone repository và dùng dependency `file:` trong ứng dụng host để thử source
+local. Chạy autolinking/pod install rồi rebuild native khi thay đổi iOS/Android.
+
+Repository chứa:
+
+- `src/__tests__/index.test.ts`: kiểm tra API, format, camera, thứ tự trang,
+  hủy, lỗi native và quyền sở hữu file. Chạy với Jest preset React Native của
+  ứng dụng host; cấu hình Jest để bao gồm thư mục source của thư viện.
+- `tests/check-pdf-writer.sh`: tạo PDF 30 trang bằng Java rồi đọc/render bằng
+  PDFKit để kiểm tra số trang, thứ tự, kích thước và hướng ảnh.
+- Android instrumentation tests cho ML Kit, PDF, EXIF, nhiều QR, barcode,
+  cleanup và xử lý camera khi không có foreground activity.
+
+```sh
+# Tại repository thư viện, cần macOS, Xcode và JDK
+bash tests/check-pdf-writer.sh
+
+# Tại thư mục android của ứng dụng host đã autolink, cần thiết bị ADB
+./gradlew :react-native-document-processor:connectedReleaseAndroidTest
+```
+
+Nếu JDK không nằm trong PATH, đặt `DOCUMENT_PROCESSOR_JAVAC` và
+`DOCUMENT_PROCESSOR_JAVA` thành đường dẫn executable tương ứng.
+
+Bản sửa iOS Simulator đã được kiểm tra với PDF mẫu 30 trang, đọc đủ 10 QR trong
+ứng dụng host. Camera trên thiết bị thật vẫn cần kiểm tra với giấy nhỏ/mờ/xoay,
+chụp nhiều đợt và thao tác hủy. Không công bố tỷ lệ tăng tốc hoặc mức RAM chung
+cho mọi thiết bị.
+
+## Log Android
+
+Log native dùng tag `DocumentScan`, mặc định tắt. Bật trên thiết bị kiểm tra:
+
+```sh
+adb shell setprop log.tag.DocumentScan DEBUG
+adb logcat -v threadtime 'DocumentScan:D' 'AndroidRuntime:E' '*:S'
+```
+
+Các sự kiện gồm `camera.*`, `session.*`, `page.*`, `pdf.complete` và `barcode.*`.
+Ứng dụng có thể bổ sung sự kiện qua `logDocumentEvent(event, data)`. Log có thể
+chứa mã tài liệu; chỉ bật khi cần chẩn đoán. Không ghi bitmap/base64.
+
+Tắt khi hoàn tất hoặc khởi động lại thiết bị:
+
+```sh
+adb shell setprop log.tag.DocumentScan INFO
+```

package/android/build.gradle

@@ -0,0 +1,24 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace 'vn.money24h.documentprocessor'
+    testBuildType 'release'
+    compileSdkVersion rootProject.ext.has('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion 28
+        targetSdkVersion rootProject.ext.has('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-android'
+    implementation 'com.google.mlkit:barcode-scanning:17.3.0'
+    implementation 'com.google.android.gms:play-services-mlkit-document-scanner:16.0.0'
+    androidTestImplementation 'androidx.test:runner:1.6.1'
+    androidTestImplementation 'com.google.zxing:core:3.5.2'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/vn/money24h/documentprocessor/BarcodeImageScanner.java

@@ -0,0 +1,81 @@
+package vn.money24h.documentprocessor;
+
+import android.graphics.Bitmap;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.ReadableArray;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+import com.google.android.gms.tasks.Tasks;
+import com.google.mlkit.vision.barcode.BarcodeScanner;
+import com.google.mlkit.vision.barcode.BarcodeScannerOptions;
+import com.google.mlkit.vision.barcode.BarcodeScanning;
+import com.google.mlkit.vision.barcode.common.Barcode;
+import com.google.mlkit.vision.common.InputImage;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Set;
+
+/** Stateless image decoding on the processor worker; no document session/files. */
+final class BarcodeImageScanner {
+    private static final Map<String, Integer> FORMATS = new LinkedHashMap<>();
+    static {
+        FORMATS.put("qr", Barcode.FORMAT_QR_CODE);
+        FORMATS.put("ean-13", Barcode.FORMAT_EAN_13);
+        FORMATS.put("ean-8", Barcode.FORMAT_EAN_8);
+        FORMATS.put("upc-a", Barcode.FORMAT_UPC_A);
+        FORMATS.put("upc-e", Barcode.FORMAT_UPC_E);
+        FORMATS.put("code-128", Barcode.FORMAT_CODE_128);
+        FORMATS.put("code-39", Barcode.FORMAT_CODE_39);
+        FORMATS.put("code-93", Barcode.FORMAT_CODE_93);
+        FORMATS.put("codabar", Barcode.FORMAT_CODABAR);
+        FORMATS.put("itf", Barcode.FORMAT_ITF);
+        FORMATS.put("pdf-417", Barcode.FORMAT_PDF417);
+        FORMATS.put("aztec", Barcode.FORMAT_AZTEC);
+        FORMATS.put("data-matrix", Barcode.FORMAT_DATA_MATRIX);
+    }
+
+    private BarcodeImageScanner() { }
+
+    static WritableMap scan(Bitmap bitmap, ReadableArray formats) throws Exception {
+        if (formats == null || formats.size() == 0) {
+            throw new IllegalArgumentException("At least one barcode format is required.");
+        }
+        int mask = 0;
+        for (int i = 0; i < formats.size(); i++) {
+            Integer format = FORMATS.get(formats.getString(i));
+            if (format == null) { throw new IllegalArgumentException("Unsupported barcode format."); }
+            mask |= format;
+        }
+        BarcodeScanner scanner = BarcodeScanning.getClient(new BarcodeScannerOptions.Builder()
+                .setBarcodeFormats(mask).build());
+        try {
+            WritableArray codes = Arguments.createArray();
+            Set<String> values = new LinkedHashSet<>();
+            Set<String> uniqueCodes = new LinkedHashSet<>();
+            for (Barcode barcode : Tasks.await(scanner.process(InputImage.fromBitmap(bitmap, 0)))) {
+                String value = barcode.getRawValue();
+                if (value == null || value.isEmpty()) { continue; }
+                for (Map.Entry<String, Integer> format : FORMATS.entrySet()) {
+                    if (format.getValue() != barcode.getFormat() || (mask & format.getValue()) == 0) { continue; }
+                    if (uniqueCodes.add(format.getKey() + "\n" + value)) {
+                        WritableMap code = Arguments.createMap();
+                        code.putString("value", value);
+                        code.putString("format", format.getKey());
+                        codes.pushMap(code);
+                        values.add(value);
+                    }
+                    break;
+                }
+            }
+            WritableArray rawValues = Arguments.createArray();
+            for (String value : values) { rawValues.pushString(value); }
+            WritableMap result = Arguments.createMap();
+            result.putArray("values", rawValues);
+            result.putArray("codes", codes);
+            return result;
+        } finally {
+            scanner.close();
+        }
+    }
+}

package/android/src/main/java/vn/money24h/documentprocessor/DocumentCapture.java

@@ -0,0 +1,163 @@
+package vn.money24h.documentprocessor;
+
+import android.app.Activity;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.SystemClock;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.BaseActivityEventListener;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.UiThreadUtil;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions;
+import com.google.mlkit.vision.documentscanner.GmsDocumentScanning;
+import com.google.mlkit.vision.documentscanner.GmsDocumentScanningResult;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/** Owns camera lifecycle and copies scanner results into files owned by our caller. */
+final class DocumentCapture extends BaseActivityEventListener {
+    private static final int REQUEST_SCAN = 24861;
+    private final ReactApplicationContext context;
+    private final ExecutorService worker = Executors.newSingleThreadExecutor();
+    private Promise pending;
+    private boolean closed;
+    private long startedAt;
+
+    DocumentCapture(ReactApplicationContext context) {
+        this.context = context;
+        context.addActivityEventListener(this);
+    }
+
+    synchronized void scan(Promise promise) {
+        if (closed || pending != null) {
+            DocumentScanLog.event("camera.busy", "closed=" + closed);
+            promise.reject("DOCUMENT_CAPTURE_BUSY", "Document camera is busy or closed.");
+            return;
+        }
+        pending = promise;
+        startedAt = SystemClock.elapsedRealtime();
+        DocumentScanLog.event("camera.start", "format=JPEG mode=FULL");
+        UiThreadUtil.runOnUiThread(() -> {
+            if (!isActive(promise)) { return; }
+            Activity activity = context.getCurrentActivity();
+            if (activity == null || activity.isFinishing() || activity.isDestroyed()) {
+                fail(promise, new IOException("No foreground activity for document camera."));
+                return;
+            }
+            try {
+                GmsDocumentScannerOptions options = new GmsDocumentScannerOptions.Builder()
+                        .setResultFormats(GmsDocumentScannerOptions.RESULT_FORMAT_JPEG)
+                        .setScannerMode(GmsDocumentScannerOptions.SCANNER_MODE_FULL)
+                        .build();
+                GmsDocumentScanning.getClient(options).getStartScanIntent(activity)
+                        .addOnSuccessListener(sender -> {
+                            if (!isActive(promise)) { return; }
+                            try {
+                                DocumentScanLog.event("camera.ready", "elapsedMs=" + (SystemClock.elapsedRealtime() - startedAt));
+                                activity.startIntentSenderForResult(sender, REQUEST_SCAN, null, 0, 0, 0);
+                            } catch (Exception error) {
+                                fail(promise, error);
+                            }
+                        })
+                        .addOnFailureListener(error -> fail(promise, error));
+            } catch (Exception error) {
+                fail(promise, error);
+            }
+        });
+    }
+
+    private synchronized boolean isActive(Promise promise) {
+        return !closed && pending == promise;
+    }
+
+    private synchronized void fail(Promise promise, Exception error) {
+        if (pending == promise) {
+            pending = null;
+            DocumentScanLog.error("camera.error", error);
+            promise.reject("DOCUMENT_CAPTURE_ERROR", error.getMessage(), error);
+        }
+    }
+
+    private synchronized boolean complete(Promise promise, String status, List<File> files) {
+        if (!isActive(promise)) { return false; }
+        WritableArray images = Arguments.createArray();
+        for (File file : files) { images.pushString(Uri.fromFile(file).toString()); }
+        WritableMap result = Arguments.createMap();
+        result.putString("status", status);
+        result.putArray("scannedImages", images);
+        pending = null;
+        DocumentScanLog.event("camera.complete", "status=" + status + " pages=" + files.size()
+                + " elapsedMs=" + (SystemClock.elapsedRealtime() - startedAt));
+        promise.resolve(result);
+        return true;
+    }
+
+    @Override
+    public synchronized void onActivityResult(Activity activity, int requestCode, int resultCode, Intent data) {
+        if (requestCode != REQUEST_SCAN || pending == null || closed) { return; }
+        Promise promise = pending;
+        DocumentScanLog.event("camera.result", "resultCode=" + resultCode);
+        if (resultCode == Activity.RESULT_CANCELED) {
+            complete(promise, "cancel", new ArrayList<>());
+            return;
+        }
+        GmsDocumentScanningResult result = GmsDocumentScanningResult.fromActivityResultIntent(data);
+        if (resultCode != Activity.RESULT_OK || result == null || result.getPages() == null
+                || result.getPages().isEmpty()) {
+            fail(promise, new IOException("Document camera returned no pages."));
+            return;
+        }
+        List<GmsDocumentScanningResult.Page> pages = new ArrayList<>(result.getPages());
+        DocumentScanLog.event("camera.copy.start", "pages=" + pages.size());
+        worker.execute(() -> {
+            long copyStartedAt = SystemClock.elapsedRealtime();
+            List<File> files = new ArrayList<>();
+            boolean transferred = false;
+            try {
+                byte[] buffer = new byte[64 * 1024];
+                for (GmsDocumentScanningResult.Page page : pages) {
+                    if (!isActive(promise)) { return; }
+                    File file = File.createTempFile("document-capture-", ".jpg", context.getCacheDir());
+                    files.add(file);
+                    try (InputStream input = context.getContentResolver().openInputStream(page.getImageUri());
+                         FileOutputStream output = new FileOutputStream(file)) {
+                        if (input == null) { throw new IOException("Cannot read scanned page."); }
+                        int count;
+                        while ((count = input.read(buffer)) != -1) { output.write(buffer, 0, count); }
+                    }
+                    if (file.length() == 0) { throw new IOException("Scanned page is empty."); }
+                    DocumentScanLog.event("camera.copy.page", "page=" + files.size() + " bytes=" + file.length());
+                }
+                DocumentScanLog.event("camera.copy.complete", "pages=" + files.size()
+                        + " elapsedMs=" + (SystemClock.elapsedRealtime() - copyStartedAt));
+                transferred = complete(promise, "success", files);
+            } catch (Exception error) {
+                fail(promise, error);
+            } finally {
+                if (!transferred) {
+                    for (File file : files) { file.delete(); }
+                }
+            }
+        });
+    }
+
+    synchronized void invalidate() {
+        if (closed) { return; }
+        closed = true;
+        if (pending != null) {
+            pending.reject("DOCUMENT_CAPTURE_CANCELLED", "Document camera was closed.");
+            pending = null;
+        }
+        context.removeActivityEventListener(this);
+        worker.shutdown();
+    }
+}