Explorar o código

在贵州大学分支上,修改人脸照片改成特征值构建人脸识别

donggaosheng hai 2 semanas
pai
achega
4dea9edbfb

+ 2 - 0
.gitignore

@@ -9,3 +9,5 @@
 .externalNativeBuild
 .cxx
 local.properties
+/tools/cardlibrary-patch/build/
+/.cardlib_work/

+ 55 - 0
AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+电子信息牌 (Electronic Information Board) — Android terminal app for campus/lab information boards. Built with Gradle + AGP; mixes Java (134 files) and Kotlin (95 files) in one `app` module.
+
+## Setup commands
+
+- JDK: **17 required** (AGP 8.6.1 rejects Java 8). Known local path: `F:\java17\jdk-17.0.7`
+- Android SDK path lives in `local.properties` (`sdk.dir`), git-ignored
+- Build: `gradlew.bat assembleDebug`
+- Build release APK: `gradlew.bat assembleRelease`
+- Unit tests: `gradlew.bat test`
+- Lint: `gradlew.bat :app:lintDebug`
+- Install on device: `gradlew.bat installDebug`
+
+Before any Gradle command on Windows, set `JAVA_HOME` to a JDK 17 install — the default `D:\Java\jdk1.8.0_181` fails with "No matching variant of com.android.tools.build:gradle".
+
+## Project layout
+
+- `app/` — the single application module (namespace `xn.xxp`)
+- `app/src/main/java/xn/xxp/` — app code: `app/` (sync/lifecycle), `home/` (UI), `room/` (Room DB), `main/`, `mqtt/`, `receiver/`, `utils/`, `widget/`
+- `app/src/main/java/core/` — shared base classes (event, ui, util)
+- `app/src/main/java/http/` — OkHttp/Retrofit client, request/response VOs
+- `app/src/main/java/play/` — multi-window video playback widgets
+- `app/libs/` — vendored binary deps (`.jar` / `.aar`), all pulled in via `fileTree`
+- `app/src/main/jniLibs/` — native `.so` payloads (`armeabi-v7a` + `arm64-v8a`)
+- `gradle/libs.versions.toml` — version catalog; all dependency versions live here
+- `app/schemas/` — exported Room schemas (one JSON per DB version)
+
+## Code style
+
+- Java 17 language level, Kotlin jvmTarget 17; 4-space indent, UTF-8
+- Version catalog is mandatory for new deps — do not hardcode versions in `build.gradle`
+- `app/build.gradle` bundles `app/libs` via `fileTree(dir: "libs", include: ["*.jar"])` and `include: ["*.aar"]`
+- **Vendored SDK conflict hazard**: `cardlibrary-release.aar` embeds its own copy of `face_sdk.jar` under `libs/`. Adding a separate `face_sdk.jar` to `app/libs` creates hundreds of `Duplicate class` errors and breaks the build. Run `gradlew.bat :app:checkDebugDuplicateClasses` after touching `app/libs`
+- Prefer Gson + `LogUtils` for logging; `xn.xxp.utils.Tool` and `xn.xxp.room.RoomTool` hold common singletons
+- Room entities live in `app/src/main/java/xn/xxp/room/bean/`, DAOs in `room/dao/`; DB version is declared in `RoomTool` and schemas must be re-exported after entity changes
+
+## Testing instructions
+
+- Unit tests: `gradlew.bat test` (JUnit4, `app/src/test/`)
+- Instrumented tests: `gradlew.bat connectedDebugAndroidTest` (JUnit4 + Espresso, `app/src/androidTest/`)
+- No CI is configured in this repo — run `gradlew.bat test lintDebug assembleDebug` locally before opening a PR
+- The build must pass `checkDebugDuplicateClasses` and `compileDebugJavaWithJavac` before any APK is considered good
+
+## PR & commit conventions
+
+- Current working branch: `xn-xxp-gzdx-feature`
+- Commit messages in history are short Chinese descriptions, e.g. `去掉扫码验证`, `播放器修改`, `崩溃问题修复` — follow that style
+- Never commit `local.properties`, `.idea/`, or `*.iml` (already git-ignored)
+
+## Security
+
+- Never commit secrets — `local.properties` (SDK path) is git-ignored
+- `local.properties` and `.gradle/` must stay out of version control
+- Vendor binaries under `app/libs/` are proprietary SDKs; do not edit their contents in place

+ 4 - 0
app/build.gradle

@@ -46,6 +46,10 @@ android {
         viewBinding true
     }
 
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
+
     kotlinOptions {
         jvmTarget = '17'
     }

BIN=BIN
app/libs/cardlibrary-release.aar


+ 5 - 2
app/src/main/java/http/client/HttpTool.java

@@ -60,13 +60,16 @@ public final class HttpTool {
         }
     }
 
-    public static Response getLabFaceList() {
+    /**
+     * 拉取人脸特征值(人员资料 + 特征值二进制)。
+     */
+    public static Response getLabFaceFeatureList() {
         try {
             DeviceConfig deviceConfig = RoomTool.getInstance().deviceConfigDao().getDeviceConfig();
             LabConfig labConfig = RoomTool.getInstance().labConfigDao().getLabConfig();
             JSONObject jsonObject = new JSONObject();
             jsonObject.put("subId", labConfig.getLabId());
-            return OkHttpUtils.postSync(deviceConfig.getBaseUrl() + "terminal/sys/face/data/sub", jsonObject.toString(), 300000);
+            return OkHttpUtils.postSync(deviceConfig.getBaseUrl() + "terminal/sys/face/data/subFeature", jsonObject.toString(), 300000);
         } catch (Exception e) {
             LogUtils.e(Log.getStackTraceString(e));
         }

+ 2 - 2
app/src/main/java/xn/xxp/HomeActivity.java

@@ -41,7 +41,7 @@ import kotlin.Unit;
 import kotlin.jvm.functions.Function1;
 import xn.xxp.app.InitTool;
 import xn.xxp.app.LabApp;
-import xn.xxp.app.SyncFaceTool;
+import xn.xxp.app.SyncFaceToolFeature;
 import xn.xxp.databinding.ActivityHomeBinding;
 import xn.xxp.home.AccessVerify;
 import xn.xxp.home.AuthTypeConfig;
@@ -261,7 +261,7 @@ public class HomeActivity extends BaseCountDownActivity<ActivityHomeBinding> imp
 
         // 身份验证
         binding.accessVerify.setOnClickListener(new FastClickDelegate(view -> {
-            if (SyncFaceTool.INSTANCE.isSyncFace) {
+            if (SyncFaceToolFeature.INSTANCE.isSyncFace) {
                 showToast("正在同步人脸,请稍后重试!");
             } else {
                 dispatchAccessVerify(AccessVerify.NORMAL);

+ 3 - 2
app/src/main/java/xn/xxp/app/InitActivity.java

@@ -173,14 +173,14 @@ public class InitActivity extends BaseActivity<ActivityInitBinding> {
         ThreadUtils.executeByCached(new ThreadUtils.SimpleTask<Object>() {
             @Override
             public Object doInBackground() throws Throwable {
-                SyncFaceTool.INSTANCE.doWork(true);
+                SyncFaceToolFeature.INSTANCE.doWork(true);
                 LogUtils.d("人脸同步结束");
                 return null;
             }
 
             @Override
             public void onSuccess(Object result) {
-                LogUtils.json("人脸数据库", RoomTool.getInstance().faceDao().getAll());
+                LogUtils.json("人脸数据库", RoomTool.getInstance().faceFeatureDao().getAll());
                 ActivityUtils.startActivity(HomeActivity.class);
                 finish();
             }
@@ -407,6 +407,7 @@ public class InitActivity extends BaseActivity<ActivityInitBinding> {
 
     @Override
     public void onBackPressed() {
+        super.onBackPressed();
         Tool.INSTANCE.exitApp();
     }
 }

+ 0 - 317
app/src/main/java/xn/xxp/app/SyncFaceDeBugTool.java

@@ -1,317 +0,0 @@
-
-package xn.xxp.app;
-
-import android.annotation.SuppressLint;
-import android.app.Activity;
-import android.os.Environment;
-import android.util.Log;
-
-import androidx.annotation.NonNull;
-import androidx.annotation.WorkerThread;
-import androidx.core.util.Pair;
-
-import com.blankj.utilcode.util.ActivityUtils;
-import com.blankj.utilcode.util.FileUtils;
-import com.blankj.utilcode.util.GsonUtils;
-import com.blankj.utilcode.util.LogUtils;
-import com.blankj.utilcode.util.ThreadUtils;
-import com.blankj.utilcode.util.Utils;
-import com.google.gson.reflect.TypeToken;
-import com.njlz.event.BuildModelEvent;
-import com.njlz.face.FaceUtils;
-import com.njlz.smartdata.FaceBuildBean;
-import com.njlz.smartdata.FaceConfig;
-
-import org.greenrobot.eventbus.EventBus;
-import org.greenrobot.eventbus.Subscribe;
-import org.greenrobot.eventbus.ThreadMode;
-import org.json.JSONObject;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.lang.reflect.Type;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CountDownLatch;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
-import java.util.concurrent.atomic.AtomicInteger;
-
-import http.OkHttpUtils;
-import http.client.HttpTool;
-import okhttp3.Request;
-import okhttp3.Response;
-import okio.BufferedSink;
-import okio.Okio;
-import xn.xxp.home.auth.ChoiceAuthActivity;
-import xn.xxp.home.setting.FaceListActivity;
-import xn.xxp.room.RoomTool;
-import xn.xxp.room.bean.Face;
-import xn.xxp.room.dao.FaceDao;
-
-public enum SyncFaceDeBugTool {
-    INSTANCE;
-
-    private static final String TAG = "SyncFaceTool";
-    private static final int MAX_DOWNLOAD_THREADS = 4;
-    private volatile boolean isBuildFaceEnd = false;
-    private List<Face> faceList;
-    public volatile boolean isSyncFace = false;
-    private long lastBuildTime = 0;
-
-    @WorkerThread
-    public void doWork() {
-        if (ThreadUtils.isMainThread()) {
-            LogUtils.e("该方法必须在子线程调用");
-            return;
-        }
-
-        if (!checkActivityState()) return;
-
-
-        if (isSyncFace) {
-            LogUtils.d("正在同步人脸");
-            return;
-        }
-
-        isSyncFace = true;
-        try {
-            FaceUtils.getInstance().init(Utils.getApp());
-            FaceConfig faceConfig = FaceUtils.getInstance().getFaceConfig();
-            LogUtils.json("底库配置", faceConfig);
-
-            EventBus.getDefault().register(this);
-
-            List<Pair<String, String>> faceUrlList = fetchLabFaceList();
-            if (faceUrlList == null || faceUrlList.isEmpty()) {
-                LogUtils.d("不需要下载变更人脸");
-                return;
-            }
-
-            List<FaceBuildBean> faceBuildBeanList = downloadFaceImages(faceUrlList);
-            if (faceBuildBeanList != null && !faceBuildBeanList.isEmpty()) {
-                processFaceBuilding(faceBuildBeanList);
-            }
-
-            cleanRedundantFaces();
-            LogUtils.d("最终底库", FaceUtils.getInstance().getAllFaceId());
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-        } finally {
-            cleanupResources();
-            isSyncFace = false;
-        }
-    }
-
-    private boolean checkActivityState() {
-        Activity topActivity = ActivityUtils.getTopActivity();
-        if (topActivity instanceof ChoiceAuthActivity) {
-            LogUtils.d("人脸识别中,不去同步人脸!");
-            return false;
-        }
-        if (topActivity instanceof FaceListActivity) {
-            LogUtils.d("正在查阅底库,不去同步人脸!");
-            return false;
-        }
-        return true;
-    }
-
-    private List<Pair<String, String>> fetchLabFaceList() {
-        try (Response response = HttpTool.getLabFaceList()) {
-            if (response == null || !response.isSuccessful()) return null;
-
-            JSONObject jsonObject = new JSONObject(response.body().string());
-            if (jsonObject.getInt("code") != 200) return null;
-
-            Type faceListType = new TypeToken<List<Face>>() {
-            }.getType();
-            faceList = GsonUtils.fromJson(jsonObject.getJSONArray("data").toString(), faceListType);
-            if (faceList == null || faceList.isEmpty()) return Collections.emptyList();
-
-            return filterNeedDownloadFaces();
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-            return null;
-        }
-    }
-
-    private List<Pair<String, String>> filterNeedDownloadFaces() {
-        List<Pair<String, String>> results = new ArrayList<>();
-        FaceDao faceDao = RoomTool.getInstance().faceDao();
-        List<String> existingFaceIds = FaceUtils.getInstance().getAllFaceId();
-
-        for (Face face : faceList) {
-            Face localFace = faceDao.getById(face.getUserId());
-            if (shouldDownloadFace(localFace, face, existingFaceIds)) {
-                results.add(Pair.create(
-                        String.valueOf(face.getUserId()),
-                        HttpTool.checkUrl(face.getFaceUrl())
-                ));
-            }
-        }
-        return results;
-    }
-
-    private boolean shouldDownloadFace(Face localFace, Face remoteFace, List<String> existingFaceIds) {
-        if (localFace == null) return true;
-        if (remoteFace.getLastUpdated() <= localFace.getLastUpdated()) return false;
-        return !existingFaceIds.contains(String.valueOf(remoteFace.getUserId()));
-    }
-
-    private List<FaceBuildBean> downloadFaceImages(List<Pair<String, String>> faceUrlList) {
-        ExecutorService executor = Executors.newFixedThreadPool(MAX_DOWNLOAD_THREADS);
-        ConcurrentHashMap<String, File> downloadedFiles = new ConcurrentHashMap<>();
-        CountDownLatch latch = new CountDownLatch(faceUrlList.size());
-        AtomicInteger failureCount = new AtomicInteger(0);
-
-        try {
-            String downloadDir = createDownloadDirectory();
-
-            for (Pair<String, String> pair : faceUrlList) {
-                executor.submit(() -> {
-                    try {
-                        File outputFile = new File(downloadDir, pair.first + ".jpg");
-                        if (downloadImage(pair.second, outputFile)) {
-                            downloadedFiles.put(pair.first, outputFile);
-                        }
-                    } finally {
-                        latch.countDown();
-                    }
-                });
-            }
-
-            latch.wait();
-            executor.shutdown();
-
-            if (failureCount.get() > 0) {
-                LogUtils.w("部分人脸下载失败,失败数量:" + failureCount.get());
-            }
-
-            return buildFaceBeans(downloadedFiles);
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            return null;
-        } finally {
-            executor.shutdownNow();
-        }
-    }
-
-    private boolean downloadImage(String url, File outputFile) {
-        Request request = new Request.Builder().url(url).build();
-        try (Response response = OkHttpUtils.client.newCall(request).execute()) {
-            if (!response.isSuccessful() || response.body() == null) {
-                LogUtils.w("下载失败: " + url);
-                return false;
-            }
-
-            try (InputStream is = response.body().byteStream();
-                 BufferedSink sink = Okio.buffer(Okio.sink(outputFile))) {
-                sink.writeAll(Okio.source(is));
-                return true;
-            }
-        } catch (IOException e) {
-            LogUtils.e("下载异常: " + url, e);
-            return false;
-        }
-    }
-
-    @NonNull
-    private String createDownloadDirectory() {
-        @SuppressLint("SdCardPath")
-        String dirPath = Environment.getExternalStorageDirectory() + "/Download/facePic/";
-        FileUtils.createOrExistsDir(dirPath);
-        FileUtils.deleteAllInDir(dirPath);
-        return dirPath;
-    }
-
-    private List<FaceBuildBean> buildFaceBeans(ConcurrentHashMap<String, File> downloadedFiles) {
-        List<FaceBuildBean> beans = new ArrayList<>();
-        downloadedFiles.forEach((id, file) -> {
-            FaceBuildBean bean = new FaceBuildBean();
-            bean.setPicPath(file.getAbsolutePath());
-            bean.setFaceUuid(id);
-            beans.add(bean);
-        });
-        return beans;
-    }
-
-    private void processFaceBuilding(List<FaceBuildBean> faceBuildBeanList)
-            throws InterruptedException {
-
-        FaceUtils.getInstance().faceBuild(faceBuildBeanList);
-        lastBuildTime = System.currentTimeMillis();
-        isBuildFaceEnd = false;
-
-        while (!isBuildFaceEnd) {
-            Thread.sleep(10);
-            if (System.currentTimeMillis() - lastBuildTime > 2000) {
-                isBuildFaceEnd = true;
-            }
-        }
-    }
-
-    @Subscribe(threadMode = ThreadMode.ASYNC)
-    public void onReceive(BuildModelEvent event) {
-        if (event.isDone()) {
-            processBuildResults();
-            isBuildFaceEnd = true;
-        }
-        lastBuildTime = System.currentTimeMillis();
-    }
-
-    private void processBuildResults() {
-        List<FaceBuildBean> results = FaceUtils.getInstance().getFaceResult();
-        if (results == null || results.isEmpty()) return;
-
-        FaceDao faceDao = RoomTool.getInstance().faceDao();
-        results.forEach(bean -> {
-            if (bean.getErrCode() != 0) {
-                LogUtils.e("建模失败", bean.getFaceUuid(), bean.getErrCode());
-            } else {
-                updateFaceDatabase(faceDao, bean.getFaceUuid());
-            }
-        });
-    }
-
-    private void updateFaceDatabase(FaceDao faceDao, String faceUuid) {
-        if (faceList == null) return;
-
-        long uuid = Long.parseLong(faceUuid);
-        for (Face face : faceList) {
-            if (face.getUserId() == uuid) {
-                faceDao.insertAll(face);
-                break;
-            }
-        }
-    }
-
-    private void cleanRedundantFaces() {
-        List<String> existingIds = FaceUtils.getInstance().getAllFaceId();
-        if (existingIds == null || existingIds.isEmpty()) return;
-
-        FaceDao faceDao = RoomTool.getInstance().faceDao();
-        existingIds.forEach(id -> {
-            if (!containsFace(id)) {
-                FaceUtils.getInstance().deleteFace(id);
-                faceDao.delete(Long.parseLong(id));
-            }
-        });
-    }
-
-    private boolean containsFace(String faceId) {
-        return faceList.stream().anyMatch(f ->
-                String.valueOf(f.getUserId()).equals(faceId));
-    }
-
-    private void cleanupResources() {
-        try {
-            EventBus.getDefault().unregister(this);
-            FaceUtils.getInstance().destroy();
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-        }
-    }
-}

+ 0 - 324
app/src/main/java/xn/xxp/app/SyncFaceTool.java

@@ -1,324 +0,0 @@
-package xn.xxp.app;
-
-import android.annotation.SuppressLint;
-import android.app.Activity;
-import android.app.DownloadManager;
-import android.content.Context;
-import android.net.Uri;
-import android.os.Environment;
-import android.os.FileObserver;
-import android.util.Log;
-
-import androidx.annotation.NonNull;
-import androidx.annotation.Nullable;
-import androidx.annotation.WorkerThread;
-import androidx.core.util.Pair;
-
-import com.blankj.utilcode.util.ActivityUtils;
-import com.blankj.utilcode.util.AppUtils;
-import com.blankj.utilcode.util.FileUtils;
-import com.blankj.utilcode.util.GsonUtils;
-import com.blankj.utilcode.util.LogUtils;
-import com.blankj.utilcode.util.ThreadUtils;
-import com.blankj.utilcode.util.Utils;
-import com.google.gson.reflect.TypeToken;
-import com.njlz.event.BuildModelEvent;
-import com.njlz.face.FaceUtils;
-import com.njlz.smartdata.FaceBuildBean;
-import com.njlz.smartdata.FaceConfig;
-
-import org.greenrobot.eventbus.EventBus;
-import org.greenrobot.eventbus.Subscribe;
-import org.greenrobot.eventbus.ThreadMode;
-import org.json.JSONObject;
-
-import java.io.File;
-import java.lang.reflect.Type;
-import java.util.ArrayList;
-import java.util.LinkedHashMap;
-import java.util.LinkedList;
-import java.util.List;
-import java.util.Map;
-
-import http.client.HttpTool;
-import okhttp3.Response;
-import xn.xxp.home.auth.ChoiceAuthActivity;
-import xn.xxp.home.setting.FaceListActivity;
-import xn.xxp.room.RoomTool;
-import xn.xxp.room.bean.Face;
-import xn.xxp.room.dao.FaceDao;
-
-public enum SyncFaceTool {
-    INSTANCE;
-
-    private DownloadManager downloadManager;
-    private long lastEventTime = 0;
-    private long lastBuildTime = 0;
-    private volatile boolean isBuildFaceEnd = false;
-    private List<Face> faceList;
-    public volatile boolean isSyncFace = false;
-
-    SyncFaceTool() {
-
-    }
-
-    @WorkerThread
-    public void doWork(boolean isInit) {
-//        if (AppUtils.isAppDebug()) {
-//            SyncFaceDeBugTool.INSTANCE.doWork();
-//        } else {
-        if (ThreadUtils.isMainThread()) {
-            LogUtils.e("该方法必须在子线程调用");
-            return;
-        }
-        Activity topActivity = ActivityUtils.getTopActivity();
-        if (topActivity instanceof ChoiceAuthActivity) {
-            LogUtils.d("人脸识别中,不去同步人脸!");
-            return;
-        }
-        if (topActivity instanceof FaceListActivity) {
-            LogUtils.d("正在查阅底库,不去同步人脸!");
-            return;
-        }
-        if (isSyncFace) {
-            LogUtils.d("正在同步人脸");
-            return;
-        }
-        if (null == downloadManager) {
-            downloadManager = (DownloadManager) Utils.getApp().getApplicationContext().getSystemService(Context.DOWNLOAD_SERVICE);
-        }
-        // 初始化
-        isSyncFace = true;
-        try {
-            // 同步人脸
-            FaceUtils.getInstance().init(Utils.getApp());
-            FaceConfig faceConfig = FaceUtils.getInstance().getFaceConfig();
-            LogUtils.json("底库配置", faceConfig);
-            if (isInit) {
-                // 删除先前的底库
-                FaceUtils.getInstance().deleteAllFace();
-                FaceDao faceDao = RoomTool.getInstance().faceDao();
-                faceDao.clear();
-            }
-            EventBus.getDefault().register(this);
-            // http请求同步
-            List<Pair<String, String>> faceUrlList = getLabFaceList();
-            if (null != faceUrlList && !faceUrlList.isEmpty()) {
-                // 下载人脸
-                List<FaceBuildBean> faceBuildBeanList = downloadPicAndBuild(faceUrlList);
-                LogUtils.json("需要变更的人脸", faceBuildBeanList);
-                if (null != faceBuildBeanList && !faceBuildBeanList.isEmpty()) {
-                    // 人脸建模
-                    FaceUtils.getInstance().faceBuild(faceBuildBeanList);
-                    lastBuildTime = System.currentTimeMillis();
-                    // 等待人脸建模
-                    while (!isBuildFaceEnd) {
-                        Thread.sleep(10);
-                        if (System.currentTimeMillis() - lastBuildTime > 2000) {
-                            isBuildFaceEnd = true;
-                        }
-                    }
-                }
-                LogUtils.json(RoomTool.getInstance().faceDao().getAll());
-            } else {
-                LogUtils.d("不需要下载变更人脸");
-            }
-            // 删除本地多余的人脸
-            delRedundantFace();
-            LogUtils.d("底库", FaceUtils.getInstance().getAllFaceId());
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-        } finally {
-            try {
-                // 销毁
-                EventBus.getDefault().unregister(this);
-                FaceUtils.getInstance().destroy();
-            } catch (Exception e) {
-                LogUtils.e(Log.getStackTraceString(e));
-            }
-        }
-        isSyncFace = false;
-//        }
-    }
-
-    private List<Pair<String, String>> getLabFaceList() {
-        try {
-            Response response = HttpTool.getLabFaceList();
-            if (null != response && response.isSuccessful()) {
-                String json = response.body().string();
-                JSONObject jsonObject = new JSONObject(json);
-                int code = jsonObject.getInt("code");
-                if (200 == code) {
-                    Type faceListType = new TypeToken<List<Face>>() {
-                    }.getType();
-                    faceList = GsonUtils.fromJson(jsonObject.getJSONArray("data").toString(), faceListType);
-
-                    if (null != faceList && !faceList.isEmpty()) {
-                        FaceDao faceDao = RoomTool.getInstance().faceDao();
-                        @SuppressLint("SdCardPath") final String savePath = "/sdcard/facePic/";
-                        FileUtils.createOrExistsDir(savePath);
-                        // 1.id 2.url
-                        List<Pair<String, String>> faceUrlList = new ArrayList<>();
-                        List<String> allFaceIdList = FaceUtils.getInstance().getAllFaceId();
-                        for (int i = 0; i < faceList.size(); i++) {
-                            Face face = faceList.get(i);
-                            Face sqlFace = faceDao.getById(face.getUserId());
-                            if (null != sqlFace) {
-                                boolean sqlInDb = false;
-                                for (int j = 0; j < allFaceIdList.size(); j++) {
-                                    if (allFaceIdList.get(j).equals(String.valueOf(sqlFace.getUserId()))) {
-                                        sqlInDb = true;
-                                    }
-                                }
-
-                                if (sqlInDb && face.getLastUpdated() <= sqlFace.getLastUpdated()) {
-                                    continue;
-                                }
-                            }
-                            faceUrlList.add(Pair.create(String.valueOf(face.getUserId()), HttpTool.checkUrl(face.getFaceUrl())));
-                        }
-                        return faceUrlList;
-                    } else {
-                        return new ArrayList<>();
-                    }
-                }
-            }
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-        }
-        return null;
-    }
-
-    private List<FaceBuildBean> downloadPicAndBuild(List<Pair<String, String>> faceUrlList) {
-        if (null == faceUrlList || faceUrlList.isEmpty()) {
-            return null;
-        }
-        try {
-            @SuppressLint("SdCardPath") final String filePathDir = "/sdcard/" + Environment.DIRECTORY_DOWNLOADS + "/facePic/";
-            FileUtils.createOrExistsDir(filePathDir);
-            FileUtils.deleteAllInDir(filePathDir);
-            List<FaceBuildBean> faceBuildBeanList = new ArrayList<>();
-            List<File> downloadList = new LinkedList<>();
-            for (int i = 0; i < faceUrlList.size(); i++) {
-                // 1.id 2.url
-                Pair<String, String> downloadPair = faceUrlList.get(i);
-                DownloadManager.Request request = new DownloadManager.Request(Uri.parse(downloadPair.second));
-                request.setDestinationInExternalPublicDir(Environment.DIRECTORY_DOWNLOADS, "facePic/" + downloadPair.first + ".jpg");
-                request.setMimeType("image/jpeg");
-                request.setVisibleInDownloadsUi(false);
-                request.setNotificationVisibility(DownloadManager.Request.VISIBILITY_HIDDEN);
-                downloadManager.enqueue(request);
-                downloadList.add(new File(filePathDir + downloadPair.first + ".jpg"));
-            }
-            // 文件观察者
-            FileObserver fileObserver = getFileObserver(filePathDir, downloadList);
-            // 开始观察
-            fileObserver.startWatching();
-            lastEventTime = System.currentTimeMillis();
-            // 观察者无响应2秒后 认为下载结束
-            while (!downloadList.isEmpty()) {
-                Thread.sleep(1000);
-                if (System.currentTimeMillis() - lastEventTime > 2000) {
-                    downloadList.clear();
-                }
-            }
-            // 停止观察
-            fileObserver.stopWatching();
-
-            // 同步人脸
-            List<File> facePicList = FileUtils.listFilesInDir(filePathDir);
-            if (!facePicList.isEmpty()) {
-                for (int i = 0; i < facePicList.size(); i++) {
-                    File file = facePicList.get(i);
-                    FaceBuildBean faceBuildBean = new FaceBuildBean();
-                    faceBuildBean.setPicPath(file.getAbsolutePath());
-                    faceBuildBean.setFaceUuid(file.getName().replace(".jpg", ""));
-                    faceBuildBeanList.add(faceBuildBean);
-                }
-            }
-            return faceBuildBeanList;
-        } catch (Exception e) {
-            LogUtils.e(Log.getStackTraceString(e));
-        }
-        return null;
-    }
-
-    @Subscribe(threadMode = ThreadMode.ASYNC)
-    public void onReceive(BuildModelEvent buildModelEvent) {
-        if (buildModelEvent.isDone()) {
-            List<FaceBuildBean> list = FaceUtils.getInstance().getFaceResult();
-            FaceDao faceDao = RoomTool.getInstance().faceDao();
-            if (list != null && !list.isEmpty()) {
-                for (FaceBuildBean faceBuildBean : list) {
-                    if (faceBuildBean.getErrCode() != 0) {
-                        LogUtils.e("建模失败", faceBuildBean.getFaceUuid(), faceBuildBean.getErrCode());
-                    } else {
-                        if (null != faceList && !faceList.isEmpty()) {
-                            long uuid = Long.parseLong(faceBuildBean.getFaceUuid());
-                            for (int i = 0; i < faceList.size(); i++) {
-                                Face face = faceList.get(i);
-                                if (face.getUserId() == uuid) {
-                                    faceDao.insertAll(face);
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            isBuildFaceEnd = true;
-        }
-        lastBuildTime = System.currentTimeMillis();
-    }
-
-    private @NonNull FileObserver getFileObserver(String filePathDir, List<File> downloadList) {
-        return new FileObserver(filePathDir) {
-            final Map<String, Integer> fileStateMap = new LinkedHashMap<>();
-
-            @Override
-            public void onEvent(int event, @Nullable String path) {
-                lastEventTime = System.currentTimeMillis();
-                if (null != path) {
-                    if (event == CLOSE_WRITE) {
-                        Integer count = fileStateMap.get(path);
-                        if (null == count) {
-                            fileStateMap.put(path, 1);
-                        } else if (count >= 2) {
-                            downloadList.removeIf(file -> path.equals(file.getName()));
-                        } else {
-                            fileStateMap.put(path, count + 1);
-                        }
-                    }
-                }
-            }
-        };
-    }
-
-    /**
-     * 删除本地多余的人脸
-     */
-    private void delRedundantFace() {
-        List<String> allFaceIdList = FaceUtils.getInstance().getAllFaceId();
-        FaceDao faceDao = RoomTool.getInstance().faceDao();
-        if (faceList != null && allFaceIdList != null && !allFaceIdList.isEmpty()) {
-            if (faceList.isEmpty()) {
-                FaceUtils.getInstance().deleteAllFace();
-                faceDao.clear();
-            } else {
-                for (int i = 0; i < allFaceIdList.size(); i++) {
-                    String uuid = allFaceIdList.get(i);
-                    boolean hasFace = false;
-                    for (int j = 0; j < faceList.size(); j++) {
-                        if (faceList.get(j).getUserId() == Long.parseLong(uuid)) {
-                            hasFace = true;
-                            break;
-                        }
-                    }
-                    if (!hasFace) {
-                        FaceUtils.getInstance().deleteFace(uuid);
-                        faceDao.delete(Long.parseLong(uuid));
-                    }
-                }
-            }
-        }
-    }
-}

+ 447 - 0
app/src/main/java/xn/xxp/app/SyncFaceToolFeature.java

@@ -0,0 +1,447 @@
+package xn.xxp.app;
+
+import android.annotation.SuppressLint;
+import android.app.Activity;
+import android.os.Environment;
+import android.util.Log;
+
+import androidx.annotation.WorkerThread;
+
+import com.blankj.utilcode.util.ActivityUtils;
+import com.blankj.utilcode.util.LogUtils;
+import com.blankj.utilcode.util.ThreadUtils;
+import com.blankj.utilcode.util.Utils;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonDeserializationContext;
+import com.google.gson.JsonDeserializer;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.reflect.TypeToken;
+import com.njlz.event.BuildModelEvent;
+import com.njlz.face.FaceUtils;
+import com.njlz.smartdata.FaceBuildBean;
+import com.njlz.smartdata.FaceConfig;
+
+import org.greenrobot.eventbus.EventBus;
+import org.greenrobot.eventbus.Subscribe;
+import org.greenrobot.eventbus.ThreadMode;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.lang.reflect.Type;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Base64;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import http.client.HttpTool;
+import okhttp3.Response;
+import xn.xxp.home.auth.ChoiceAuthActivity;
+import xn.xxp.home.setting.FaceListActivity;
+import xn.xxp.room.RoomTool;
+import xn.xxp.room.bean.FaceFeature;
+import xn.xxp.room.dao.FaceFeatureDao;
+
+/**
+ * 人脸特征值同步。
+ *
+ * <p>只对接一个接口:{@code terminal/sys/face/data/subFeature},
+ * 返回人员资料 + 人脸特征值二进制,统一落 {@link FaceFeature} 表。
+ *
+ * <p>特征值写成文件后交给 {@code FaceUtils.faceFeatureImport} 导入底库
+ * (人脸 SDK 需要的是本地文件路径 {@code FaceBuildBean.featureImportPath})。
+ */
+public enum SyncFaceToolFeature {
+    INSTANCE;
+
+    private static final String TAG = "SyncFaceToolFeature";
+
+    /** 服务端下发的全量人脸特征值(同时也是人脸名单) */
+    private List<FaceFeature> faceList;
+
+    /** 特征值文件后缀 */
+    private static final String FEATURE_FILE_EXTENSION = ".dat";
+    /** 等待人脸建模完成的最长静默时间(毫秒),期间没有任何建模事件即视为超时 */
+    private static final long BUILD_TIMEOUT = 2000;
+    /** 单次建模的绝对时长上限(毫秒),防止 SDK 持续上报进度事件导致同步线程被永久挂住 */
+    private static final long BUILD_MAX_DURATION = 60_000;
+    /** 特征值文件目录,与图片流程保持一致(人脸服务进程需要能读到) */
+    @SuppressLint("SdCardPath")
+    private static final String FEATURE_DIR = "/sdcard/" + Environment.DIRECTORY_DOWNLOADS + "/faceFeature/";
+    /** 判定为 Base64 特征值的最小解码长度,真实人脸特征值至少几百字节 */
+    private static final int MIN_FEATURE_BYTES = 64;
+
+    private volatile boolean isBuildFaceEnd = false;
+    public volatile boolean isSyncFace = false;
+    private long lastBuildTime = 0;
+
+    /** 普通 Gson,用于解析人脸资料 */
+    private static final Gson PLAIN_GSON = new Gson();
+    /** 解析人脸特征,faceFeature 字段需要特殊处理,见 {@link FaceFeatureDeserializer} */
+    private static final Gson FACE_FEATURE_GSON = new GsonBuilder()
+            .registerTypeAdapter(FaceFeature.class, new FaceFeatureDeserializer())
+            .create();
+
+    SyncFaceToolFeature() {
+
+    }
+
+    @WorkerThread
+    public void doWork(boolean isInit) {
+        if (ThreadUtils.isMainThread()) {
+            LogUtils.e("该方法必须在子线程调用");
+            return;
+        }
+        Activity topActivity = ActivityUtils.getTopActivity();
+        if (topActivity instanceof ChoiceAuthActivity) {
+            LogUtils.d("人脸识别中,不去同步人脸!");
+            return;
+        }
+        if (topActivity instanceof FaceListActivity) {
+            LogUtils.d("正在查阅底库,不去同步人脸!");
+            return;
+        }
+        if (isSyncFace) {
+            LogUtils.d("正在同步人脸");
+            return;
+        }
+        // 初始化
+        isSyncFace = true;
+        // 复位:faceList 是成员变量,若不复位,本轮 HTTP 失败时会拿上一轮的残留列表去删人脸
+        faceList = null;
+        // 复位:isBuildFaceEnd 在上一轮建模完成时被置 true,若不复位,本轮会直接跳过等待建模
+        isBuildFaceEnd = false;
+        lastBuildTime = 0;
+        try {
+            // 同步人脸
+            FaceUtils.getInstance().init(Utils.getApp());
+            FaceConfig faceConfig = FaceUtils.getInstance().getFaceConfig();
+            LogUtils.json("底库配置", faceConfig);
+            FaceFeatureDao featureDao = RoomTool.getInstance().faceFeatureDao();
+            if (isInit) {
+                // 删除先前的底库
+                FaceUtils.getInstance().deleteAllFace();
+                featureDao.clear();
+            }
+            EventBus.getDefault().register(this);
+            // 1. 拉取人脸特征值(唯一的数据来源,不再单独拉人脸图片)
+            List<FaceFeature> features = fetchLabFaceFeatureList();
+            if (null == features) {
+                LogUtils.e("拉取人脸特征值失败,本次不同步");
+                return;
+            }
+            faceList = features;
+            // 2. 记录同步前的本地特征,用于判断哪些特征需要重建
+            Map<Long, FaceFeature> localFeatures = new HashMap<>();
+            for (FaceFeature local : featureDao.getAll()) {
+                localFeatures.put(local.getUserId(), local);
+            }
+            // 3. 人脸特征落库(byte[],同时也是人脸资料,界面只认这一张表)
+            syncFaceFeatures(features);
+            // 4. 筛出需要重建的特征
+            List<FaceFeature> changed = filterChangedFeatures(features, localFeatures);
+            LogUtils.d("人脸特征值 " + features.size() + " 条,需要重建 " + changed.size() + " 条");
+            // 建模是否成功,失败时底库未更新,不能执行"删除本地多余人脸"
+            boolean buildOk = true;
+            if (!changed.isEmpty()) {
+                // 5. 写成特征值文件
+                List<FaceBuildBean> faceBuildBeanList = writeFeatureFiles(changed);
+                LogUtils.json("需要变更的人脸特征", faceBuildBeanList);
+                if (!faceBuildBeanList.isEmpty()) {
+                    // 6. 人脸建模(新版 SDK 走特征值导入:FaceBuildBean.featureImportPath)
+                    // 先打时间戳:SDK 可能在调用返回前就回调进度事件
+                    lastBuildTime = System.currentTimeMillis();
+                    long buildStart = lastBuildTime;
+                    int buildRet = FaceUtils.getInstance().faceFeatureImport(faceBuildBeanList);
+                    if (buildRet != 0) {
+                        // 1000=空列表 1015=SDK 未初始化 1201=未绑定人脸服务
+                        LogUtils.e("特征值导入失败, 错误码 = " + buildRet);
+                        buildOk = false;
+                    } else {
+                        // 等待人脸建模完成(由 onReceive 回调置位 isBuildFaceEnd)
+                        while (!isBuildFaceEnd) {
+                            Thread.sleep(10);
+                            long now = System.currentTimeMillis();
+                            if (now - lastBuildTime > BUILD_TIMEOUT) {
+                                // 2 秒没有任何建模事件,认为超时
+                                LogUtils.e("等待人脸建模超时");
+                                buildOk = false;
+                                break;
+                            }
+                            if (now - buildStart > BUILD_MAX_DURATION) {
+                                LogUtils.e("等待人脸建模超时(超过最大时长)");
+                                buildOk = false;
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+            LogUtils.json(RoomTool.getInstance().faceFeatureDao().getAll());
+            // 只有建模成功、底库确实更新了,才允许删除本地多余的人脸
+            if (buildOk) {
+                delRedundantFace();
+                LogUtils.d("底库", FaceUtils.getInstance().getAllFaceId());
+            }
+        } catch (Exception e) {
+            LogUtils.e(Log.getStackTraceString(e));
+        } finally {
+            try {
+                // 销毁
+                EventBus.getDefault().unregister(this);
+                FaceUtils.getInstance().destroy();
+            } catch (Exception e) {
+                LogUtils.e(Log.getStackTraceString(e));
+            }
+            isSyncFace = false;
+        }
+    }
+
+    /**
+     * 拉取服务端下发的全量人脸特征值。
+     *
+     * @return null 表示请求失败
+     */
+    private List<FaceFeature> fetchLabFaceFeatureList() {
+        try {
+            Response response = HttpTool.getLabFaceFeatureList();
+            if (null == response || !response.isSuccessful()) {
+                LogUtils.e("拉取人脸特征值失败");
+                return null;
+            }
+            String json = response.body().string();
+            JSONObject jsonObject = new JSONObject(json);
+            int code = jsonObject.getInt("code");
+            if (200 != code) {
+                LogUtils.e("拉取人脸特征值失败, code = " + code);
+                return null;
+            }
+            JSONArray data = jsonObject.optJSONArray("data");
+            if (null == data || data.length() == 0) {
+                LogUtils.d("服务端未下发人脸特征值");
+                return new ArrayList<>();
+            }
+            Type featureType = new TypeToken<List<FaceFeature>>() {
+            }.getType();
+            List<FaceFeature> features = FACE_FEATURE_GSON.fromJson(data.toString(), featureType);
+            return null == features ? new ArrayList<>() : features;
+        } catch (Exception e) {
+            LogUtils.e(Log.getStackTraceString(e));
+            return null;
+        }
+    }
+
+    /**
+     * 人脸特征值落库。
+     *
+     * <p>这张表同时也是人脸资料表:userId、姓名、类型、页签等都在里面,
+     * 界面的姓名映射、底库列表都直接读它。
+     */
+    private void syncFaceFeatures(List<FaceFeature> features) {
+        if (null == features || features.isEmpty()) {
+            return;
+        }
+        RoomTool.getInstance().faceFeatureDao().insertAll(features.toArray(new FaceFeature[0]));
+    }
+
+    /**
+     * 筛出需要重建的特征。
+     *
+     * <p>判定条件:底库里没有这个人,或者特征值跟本地不一样。
+     * 特征值用内容比较而不是只看 lastUpdated —— 特征接口未必带 lastUpdated,
+     * 那样的话就永远判定成"没变化",人物换了照片也不会重新导入。
+     */
+    private List<FaceFeature> filterChangedFeatures(List<FaceFeature> features,
+                                                     Map<Long, FaceFeature> localFeatures) {
+        List<String> allFaceIdList = FaceUtils.getInstance().getAllFaceId();
+        Set<String> inDb = new HashSet<>();
+        if (null != allFaceIdList) {
+            inDb.addAll(allFaceIdList);
+        }
+        List<FaceFeature> changed = new ArrayList<>();
+        if (null == features) {
+            return changed;
+        }
+        for (FaceFeature feature : features) {
+            String userId = String.valueOf(feature.getUserId());
+            FaceFeature local = localFeatures.get(feature.getUserId());
+            boolean contentChanged = null == local
+                    || !Arrays.equals(feature.getFaceFeature(), local.getFaceFeature());
+            if (inDb.contains(userId) && !contentChanged) {
+                // 底库里已有且特征值没有变化,跳过
+                continue;
+            }
+            if (null == feature.getFaceFeature() || feature.getFaceFeature().length == 0) {
+                LogUtils.e("缺少人脸特征值, 已跳过", userId);
+                continue;
+            }
+            changed.add(feature);
+        }
+        return changed;
+    }
+
+    /**
+     * 把特征值写成文件,人脸 SDK 需要的是本地文件路径({@code featureImportPath})。
+     */
+    private List<FaceBuildBean> writeFeatureFiles(List<FaceFeature> features) {
+        List<FaceBuildBean> beans = new ArrayList<>();
+        File dir = new File(FEATURE_DIR);
+        if (!dir.exists() && !dir.mkdirs()) {
+            LogUtils.e("创建特征值目录失败", FEATURE_DIR);
+            return beans;
+        }
+        File[] olds = dir.listFiles();
+        if (null != olds) {
+            for (File old : olds) {
+                //noinspection ResultOfMethodCallIgnored
+                old.delete();
+            }
+        }
+        for (FaceFeature feature : features) {
+            byte[] data = feature.getFaceFeature();
+            if (null == data || data.length == 0) {
+                LogUtils.e("特征值为空, 已跳过", feature.getUserId());
+                continue;
+            }
+            File file = new File(dir, feature.getUserId() + FEATURE_FILE_EXTENSION);
+            try (FileOutputStream fos = new FileOutputStream(file)) {
+                fos.write(data);
+            } catch (IOException e) {
+                LogUtils.e("写入特征值文件失败", file.getAbsolutePath(), Log.getStackTraceString(e));
+                continue;
+            }
+            // 人脸服务是独立进程,需要保证它能读到这个特征值文件
+            //noinspection ResultOfMethodCallIgnored
+            file.setReadable(true, false);
+            FaceBuildBean bean = new FaceBuildBean();
+            bean.setFaceUuid(String.valueOf(feature.getUserId()));
+            bean.setFeatureImportPath(file.getAbsolutePath());
+            beans.add(bean);
+        }
+        return beans;
+    }
+
+    @Subscribe(threadMode = ThreadMode.ASYNC)
+    public void onReceive(BuildModelEvent buildModelEvent) {
+        if (buildModelEvent.isDone()) {
+            List<FaceBuildBean> list = FaceUtils.getInstance().getFaceResult();
+            if (list != null && !list.isEmpty()) {
+                for (FaceBuildBean faceBuildBean : list) {
+                    // 判断建模是否成功 (errCode 为 0 表示成功)
+                    if (faceBuildBean.getErrCode() != 0) {
+                        LogUtils.e("建模失败", faceBuildBean.getFaceUuid(), faceBuildBean.getErrCode());
+                    }
+                }
+            }
+            isBuildFaceEnd = true;
+        }
+        lastBuildTime = System.currentTimeMillis();
+    }
+
+    /**
+     * 删除本地多余的人脸。
+     *
+     * <p>人脸名单来自人脸特征值接口:服务端没下发特征值的人,不应该留在底库里。
+     */
+    private void delRedundantFace() {
+        List<String> allFaceIdList = FaceUtils.getInstance().getAllFaceId();
+        FaceFeatureDao featureDao = RoomTool.getInstance().faceFeatureDao();
+        if (faceList != null && allFaceIdList != null && !allFaceIdList.isEmpty()) {
+            if (faceList.isEmpty()) {
+                FaceUtils.getInstance().deleteAllFace();
+                featureDao.clear();
+            } else {
+                Set<Long> rosterIds = new HashSet<>();
+                for (FaceFeature feature : faceList) {
+                    rosterIds.add(feature.getUserId());
+                }
+                for (int i = 0; i < allFaceIdList.size(); i++) {
+                    String uuid = allFaceIdList.get(i);
+                    long userId;
+                    try {
+                        userId = Long.parseLong(uuid);
+                    } catch (NumberFormatException e) {
+                        LogUtils.e("底库UUID非法, 已跳过", uuid);
+                        continue;
+                    }
+                    if (!rosterIds.contains(userId)) {
+                        FaceUtils.getInstance().deleteFace(uuid);
+                        featureDao.delete(userId);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 人脸特征解析器。
+     *
+     * <p>{@code faceFeature} 字段的服务端形态有两种可能:
+     * <ul>
+     *     <li>Base64 字符串 —— 服务端以 byte[]/BLOB 存库,经 Jackson 序列化后的结果;</li>
+     *     <li>原始特征值字符串 —— 与 {@code terminal/sys/faceFeature} 返回的格式一致。</li>
+     * </ul>
+     * 统一解析成 byte[]:严格合法的 Base64 且解码后长度达标就按 Base64 解码,
+     * 否则取原始字符串的 UTF-8 字节。后一种情况会打印日志,便于现场确认服务端实际编码方式。
+     */
+    private static class FaceFeatureDeserializer implements JsonDeserializer<FaceFeature> {
+        @Override
+        public FaceFeature deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) {
+            if (!json.isJsonObject()) {
+                return null;
+            }
+            JsonObject copy = json.getAsJsonObject().deepCopy();
+            JsonElement raw = copy.remove("faceFeature");
+            FaceFeature feature = PLAIN_GSON.fromJson(copy, FaceFeature.class);
+            if (null != feature) {
+                feature.setFaceFeature(decodeFeature(raw));
+            }
+            return feature;
+        }
+    }
+
+    /**
+     * 特征值字符串转 byte[]。
+     */
+    private static byte[] decodeFeature(JsonElement raw) {
+        if (null == raw || raw.isJsonNull() || !raw.isJsonPrimitive()) {
+            return null;
+        }
+        String value = raw.getAsString();
+        if (null == value || value.isEmpty()) {
+            return null;
+        }
+        byte[] decoded = decodeBase64(value);
+        if (null != decoded) {
+            return decoded;
+        }
+        // 这里刻意用 android.util.Log 而不是 LogUtils:解析属于数据入口,
+        // 日志组件不可用时不能影响解析,LogUtils 的静态初始化在部分环境(如单元测试)会抛异常
+        Log.w(TAG, "faceFeature 不是 Base64,按原始字符串字节处理, 长度 = " + value.length());
+        return value.getBytes(StandardCharsets.UTF_8);
+    }
+
+    /**
+     * 严格 Base64 解码:字符集合法、长度为 4 的倍数、解码后长度达标才算特征值。
+     */
+    private static byte[] decodeBase64(String value) {
+        if (value.length() % 4 != 0 || !value.matches("[A-Za-z0-9+/]+={0,2}")) {
+            return null;
+        }
+        try {
+            byte[] decoded = Base64.getDecoder().decode(value);
+            return decoded.length >= MIN_FEATURE_BYTES ? decoded : null;
+        } catch (IllegalArgumentException e) {
+            return null;
+        }
+    }
+}

+ 0 - 1
app/src/main/java/xn/xxp/home/auth/ChoiceAuthActivity.java

@@ -18,7 +18,6 @@ import http.vo.response.UserVo;
 import xn.xxp.HomeActivity;
 import xn.xxp.R;
 import xn.xxp.app.LabApp;
-import xn.xxp.app.SyncFaceTool;
 import xn.xxp.databinding.ActivityAuthChoiceBinding;
 import xn.xxp.home.AccessVerify;
 import xn.xxp.home.auth.fragment.CardAuthFragment;

+ 4 - 4
app/src/main/java/xn/xxp/home/auth/fragment/LzFaceAuthFragment.java

@@ -44,7 +44,7 @@ import xn.xxp.databinding.FragmentAuthLzFaceBinding;
 import xn.xxp.home.auth.AuthType;
 import xn.xxp.home.auth.ChoiceAuthActivity;
 import xn.xxp.room.RoomTool;
-import xn.xxp.room.bean.Face;
+import xn.xxp.room.bean.FaceFeature;
 import xn.xxp.room.bean.LabConfig;
 
 /**
@@ -54,7 +54,7 @@ public class LzFaceAuthFragment extends RcBaseFragment<FragmentAuthLzFaceBinding
     private FragmentAuthLzFaceBinding binding;
     private SurfaceHolder surfaceHolder;
     private volatile boolean checking = false;
-    private List<Face> faceList;
+    private List<FaceFeature> faceList;
     private LabConfig labConfig;
 
     @NonNull
@@ -72,7 +72,7 @@ public class LzFaceAuthFragment extends RcBaseFragment<FragmentAuthLzFaceBinding
             surfaceHolder = binding.faceSV.getHolder();
             surfaceHolder.addCallback(this);
             binding.faceSV.getViewTreeObserver().addOnGlobalLayoutListener(this);
-            faceList = RoomTool.getInstance().faceDao().getAll();
+            faceList = RoomTool.getInstance().faceFeatureDao().getAll();
             labConfig = RoomTool.getInstance().labConfigDao().getLabConfig();
         } catch (Exception e) {
             LogUtils.e(Log.getStackTraceString(e));
@@ -194,7 +194,7 @@ public class LzFaceAuthFragment extends RcBaseFragment<FragmentAuthLzFaceBinding
                         if (null == faceId || faceId.isEmpty() || null == faceList) {
                             return null;
                         }
-                        for (Face face : faceList) {
+                        for (FaceFeature face : faceList) {
                             if (faceId.startsWith(String.valueOf(face.getUserId()))) {
                                 UserVo userVo = new UserVo();
                                 userVo.userId = String.valueOf(face.getUserId());

+ 17 - 12
app/src/main/java/xn/xxp/home/setting/FaceAdapter.java

@@ -6,15 +6,11 @@ import android.view.View;
 import android.view.ViewGroup;
 import android.widget.BaseAdapter;
 
-import com.bumptech.glide.Glide;
-import com.njlz.face.FaceUtils;
-
 import java.util.List;
 
-import http.client.HttpTool;
 import xn.xxp.databinding.ItemFaceBinding;
 import xn.xxp.room.RoomTool;
-import xn.xxp.room.bean.Face;
+import xn.xxp.room.bean.FaceFeature;
 
 public class FaceAdapter extends BaseAdapter {
     private final List<String> faceIdList;
@@ -42,7 +38,7 @@ public class FaceAdapter extends BaseAdapter {
     public View getView(int position, View convertView, ViewGroup parent) {
         ViewHolder viewHolder;
         if (convertView == null) {
-            ItemFaceBinding binding = ItemFaceBinding.inflate(LayoutInflater.from(parent.getContext()));
+            ItemFaceBinding binding = ItemFaceBinding.inflate(LayoutInflater.from(parent.getContext()), parent, false);
             convertView = binding.getRoot();
             viewHolder = new ViewHolder(binding);
             convertView.setTag(viewHolder);
@@ -51,10 +47,11 @@ public class FaceAdapter extends BaseAdapter {
         }
         String faceId = getItem(position);
         if (null != faceId) {
-            Face face = RoomTool.getInstance().faceDao().getById(Long.parseLong(faceId));
-            if (null != face) {
-                Glide.with(viewHolder.binding.iv).load(HttpTool.checkUrl(face.getFaceUrl())).into(viewHolder.binding.iv);
-                viewHolder.binding.name.setText(TextUtils.isEmpty(face.getUserName()) ? "" : face.getUserName());
+            // 现在只同步人脸特征值,服务端不再下发人脸图片,没有头像可显示
+            viewHolder.binding.iv.setVisibility(View.GONE);
+            FaceFeature faceFeature = RoomTool.getInstance().faceFeatureDao().getById(parseUserId(faceId));
+            if (null != faceFeature) {
+                viewHolder.binding.name.setText(TextUtils.isEmpty(faceFeature.getUserName()) ? "" : faceFeature.getUserName());
             }
             viewHolder.binding.faceId.setText(TextUtils.isEmpty(faceId) ? "" : faceId);
         }
@@ -62,10 +59,18 @@ public class FaceAdapter extends BaseAdapter {
         return convertView;
     }
 
+    private long parseUserId(String faceId) {
+        try {
+            return Long.parseLong(faceId);
+        } catch (NumberFormatException e) {
+            return -1L;
+        }
+    }
+
     static class ViewHolder {
-        private final ItemFaceBinding binding;
+        final ItemFaceBinding binding;
 
-        public ViewHolder(ItemFaceBinding binding) {
+        ViewHolder(ItemFaceBinding binding) {
             this.binding = binding;
         }
     }

+ 3 - 3
app/src/main/java/xn/xxp/receiver/TimeTickReceiver.java

@@ -7,7 +7,7 @@ import android.content.Intent;
 import com.blankj.utilcode.util.LogUtils;
 import com.blankj.utilcode.util.ThreadUtils;
 
-import xn.xxp.app.SyncFaceTool;
+import xn.xxp.app.SyncFaceToolFeature;
 import xn.xxp.room.RoomTool;
 import xn.xxp.utils.Tool;
 
@@ -22,13 +22,13 @@ public class TimeTickReceiver extends BroadcastReceiver {
         ThreadUtils.executeByCached(new ThreadUtils.SimpleTask<Object>() {
             @Override
             public Object doInBackground() throws Throwable {
-                SyncFaceTool.INSTANCE.doWork(false);
+                SyncFaceToolFeature.INSTANCE.doWork(false);
                 return null;
             }
 
             @Override
             public void onSuccess(Object result) {
-                LogUtils.json(RoomTool.getInstance().faceDao().getAll());
+                LogUtils.json(RoomTool.getInstance().faceFeatureDao().getAll());
             }
         });
     }

+ 31 - 6
app/src/main/java/xn/xxp/room/RoomTool.java

@@ -1,37 +1,62 @@
 package xn.xxp.room;
 
-import androidx.room.AutoMigration;
 import androidx.room.Database;
 import androidx.room.Room;
 import androidx.room.RoomDatabase;
+import androidx.room.migration.Migration;
+import androidx.sqlite.db.SupportSQLiteDatabase;
 
 import com.blankj.utilcode.util.Utils;
 
 import xn.xxp.room.bean.DeviceConfig;
-import xn.xxp.room.bean.Face;
+import xn.xxp.room.bean.FaceFeature;
 import xn.xxp.room.bean.LabConfig;
 import xn.xxp.room.bean.NoticeSummary;
 import xn.xxp.room.dao.DeviceConfigDao;
-import xn.xxp.room.dao.FaceDao;
+import xn.xxp.room.dao.FaceFeatureDao;
 import xn.xxp.room.dao.LabConfigDao;
 import xn.xxp.room.dao.NoticeSummaryDao;
 
-@Database(version = 1, entities = {Face.class, DeviceConfig.class, LabConfig.class, NoticeSummary.class})
+@Database(version = 3, entities = {FaceFeature.class, DeviceConfig.class, LabConfig.class, NoticeSummary.class})
 public abstract class RoomTool extends RoomDatabase {
     private static RoomTool INSTANCE;
 
+    /**
+     * v1 -> v2:新增人脸特征值表,存放服务端下发的特征值二进制。
+     * 建表语句与 Room 生成的 schema(app/schemas/xn.xxp.room.RoomTool/2.json)保持完全一致。
+     */
+    private static final Migration MIGRATION_1_2 = new Migration(1, 2) {
+        @Override
+        public void migrate(SupportSQLiteDatabase db) {
+            db.execSQL("CREATE TABLE IF NOT EXISTS `face_feature` (`userId` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, `faceFeature` BLOB, `userName` TEXT, `isWhite` TEXT, `userType` TEXT, `pageType` TEXT, `isDutyUser` TEXT, `lastUpdated` INTEGER NOT NULL)");
+        }
+    };
+
+    /**
+     * v2 -> v3:人脸资料统一到 face_feature 表,删除旧的 face 表。
+     */
+    private static final Migration MIGRATION_2_3 = new Migration(2, 3) {
+        @Override
+        public void migrate(SupportSQLiteDatabase db) {
+            db.execSQL("DROP TABLE IF EXISTS `face`");
+        }
+    };
+
     public static RoomTool getInstance() {
         if (INSTANCE == null) {
             synchronized (RoomTool.class) {
                 if (INSTANCE == null) {
-                    INSTANCE = Room.databaseBuilder(Utils.getApp(), RoomTool.class, "room_db").allowMainThreadQueries().build();
+                    INSTANCE = Room.databaseBuilder(Utils.getApp(), RoomTool.class, "room_db")
+                            .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
+                            .allowMainThreadQueries()
+                            .build();
                 }
             }
         }
         return INSTANCE;
     }
 
-    public abstract FaceDao faceDao();
+    public abstract FaceFeatureDao faceFeatureDao();
 
     public abstract DeviceConfigDao deviceConfigDao();
 

+ 29 - 9
app/src/main/java/xn/xxp/room/bean/Face.java

@@ -3,11 +3,24 @@ package xn.xxp.room.bean;
 import androidx.room.Entity;
 import androidx.room.PrimaryKey;
 
-@Entity
-public class Face {
+import java.util.Arrays;
+
+/**
+ * 人脸特征值。
+ *
+ * <p>服务端 {@code terminal/sys/face/data/subFeature} 下发的数据落在这张表里:
+ * {@code faceFeature} 是特征值二进制(byte[]),其余字段是人员资料
+ * (姓名、类型、页签、是否白名单等),界面直接读这张表。
+ *
+ * <p>服务端若以 byte[]/BLOB 存库,序列化后是 Base64 字符串,
+ * Gson 可直接映射到本类的 {@code byte[]} 字段。
+ */
+@Entity(tableName = "face_feature")
+public class FaceFeature {
     @PrimaryKey(autoGenerate = true)
     private long userId;
-    private String faceUrl = "";
+    /** 人脸特征值二进制数据 */
+    private byte[] faceFeature;
     private String userName = "";
     private String isWhite = "";
     private String userType = "";
@@ -23,12 +36,12 @@ public class Face {
         this.userId = userId;
     }
 
-    public String getFaceUrl() {
-        return faceUrl;
+    public byte[] getFaceFeature() {
+        return faceFeature;
     }
 
-    public void setFaceUrl(String faceUrl) {
-        this.faceUrl = faceUrl;
+    public void setFaceFeature(byte[] faceFeature) {
+        this.faceFeature = faceFeature;
     }
 
     public String getUserName() {
@@ -81,9 +94,9 @@ public class Face {
 
     @Override
     public String toString() {
-        return "Face{" +
+        return "FaceFeature{" +
                 "userId=" + userId +
-                ", faceUrl='" + faceUrl + '\'' +
+                ", faceFeature=" + (null == faceFeature ? "null" : faceFeature.length + " bytes") +
                 ", userName='" + userName + '\'' +
                 ", isWhite='" + isWhite + '\'' +
                 ", userType='" + userType + '\'' +
@@ -92,4 +105,11 @@ public class Face {
                 ", lastUpdated=" + lastUpdated +
                 '}';
     }
+
+    /**
+     * 便于日志查看特征值内容(正式日志请走 LogUtils,不要直接打印)。
+     */
+    public String featureToString() {
+        return null == faceFeature ? "" : Arrays.toString(faceFeature);
+    }
 }

+ 0 - 33
app/src/main/java/xn/xxp/room/dao/FaceDao.java

@@ -1,33 +0,0 @@
-package xn.xxp.room.dao;
-
-import androidx.room.Dao;
-import androidx.room.Delete;
-import androidx.room.Insert;
-import androidx.room.OnConflictStrategy;
-import androidx.room.Query;
-
-import java.util.List;
-
-import xn.xxp.room.bean.Face;
-
-
-@Dao
-public interface FaceDao {
-    @Query("SELECT * FROM face")
-    List<Face> getAll();
-
-    @Query("SELECT * FROM face WHERE userId = :userId")
-    Face getById(long userId);
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    void insertAll(Face... users);
-
-    @Delete
-    void delete(Face user);
-
-    @Query("DELETE FROM face WHERE userId=:userId")
-    void delete(long userId);
-
-    @Query("DELETE FROM face")
-    void clear();
-}

+ 33 - 0
app/src/main/java/xn/xxp/room/dao/FaceFeatureDao.java

@@ -0,0 +1,33 @@
+package xn.xxp.room.dao;
+
+import androidx.room.Dao;
+import androidx.room.Delete;
+import androidx.room.Insert;
+import androidx.room.OnConflictStrategy;
+import androidx.room.Query;
+
+import java.util.List;
+
+import xn.xxp.room.bean.FaceFeature;
+
+
+@Dao
+public interface FaceFeatureDao {
+    @Query("SELECT * FROM face_feature")
+    List<FaceFeature> getAll();
+
+    @Query("SELECT * FROM face_feature WHERE userId = :userId")
+    FaceFeature getById(long userId);
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    void insertAll(FaceFeature... features);
+
+    @Delete
+    void delete(FaceFeature feature);
+
+    @Query("DELETE FROM face_feature WHERE userId=:userId")
+    void delete(long userId);
+
+    @Query("DELETE FROM face_feature")
+    void clear();
+}

+ 115 - 0
app/src/test/java/xn/xxp/CardLibraryPatchTest.java

@@ -0,0 +1,115 @@
+package xn.xxp;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+import com.njlz.face.FaceUtils;
+import com.njlz.smartdata.FaceBuildBean;
+
+import org.junit.Test;
+
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 校验打补丁后的 cardlibrary-release.aar 是否与新版 face_sdk 对齐。
+ *
+ * <p>背景:厂商 AAR 的 classes.jar 是针对旧版 face_sdk 编译的,
+ * 其 {@code com.njlz.smartdata.FaceBuildBean} 缺少新版 SDK 的 {@code featureImportPath} 字段,
+ * {@code com.njlz.face.FaceUtils} 也没有暴露 {@code faceFeatureImport}。
+ * 补丁通过 javac 重新编译这两个类后塞回 AAR(见 tools/cardlibrary-patch)。
+ */
+public class CardLibraryPatchTest {
+
+    /**
+     * 卡库 bean 必须带上新版 SDK 的 featureImportPath 字段,否则特征值文件路径会在桥接时丢失。
+     */
+    @Test
+    public void cardFaceBuildBeanCarriesFeatureImportPath() throws Exception {
+        FaceBuildBean bean = new FaceBuildBean();
+        bean.setFaceUuid("1001");
+        bean.setFeatureImportPath("/sdcard/Download/faceFeature/1001.dat");
+
+        assertEquals("1001", bean.getFaceUuid());
+        assertEquals("/sdcard/Download/faceFeature/1001.dat", bean.getFeatureImportPath());
+
+        // 反射确认方法签名存在(编译期类型来自 AAR,运行时才看真实实现)
+        Method getter = FaceBuildBean.class.getMethod("getFeatureImportPath");
+        Method setter = FaceBuildBean.class.getMethod("setFeatureImportPath", String.class);
+        assertNotNull(getter);
+        assertNotNull(setter);
+    }
+
+    /**
+     * 核心回归:卡库内部用 Gson 做 card bean -> JSON -> sdk bean 的桥接,
+     * featureImportPath 必须能穿过这层桥接到达 SDK bean。
+     */
+    @Test
+    @SuppressWarnings("unchecked")
+    public void featureImportPathSurvivesGsonBridgeToSdkBean() {
+        FaceBuildBean cardBean = new FaceBuildBean();
+        cardBean.setFaceUuid("1001");
+        cardBean.setPicPath("/sdcard/face/1001.jpg");
+        cardBean.setFeatureImportPath("/sdcard/Download/faceFeature/1001.dat");
+
+        List<FaceBuildBean> cardList = new ArrayList<>();
+        cardList.add(cardBean);
+
+        Gson gson = new Gson();
+        String json = gson.toJson(cardList);
+        assertTrue("JSON 必须包含 featureImportPath,实际: " + json,
+                json.contains("featureImportPath"));
+
+        // 与 FaceUtils$1 相同的 TypeToken(sdk 侧 bean)
+        List<com.hikvision.smarteyes.facelib.FaceBuildBean> sdkList =
+                gson.fromJson(json, new TypeToken<List<com.hikvision.smarteyes.facelib.FaceBuildBean>>() {
+                }.getType());
+
+        assertEquals(1, sdkList.size());
+        com.hikvision.smarteyes.facelib.FaceBuildBean sdkBean = sdkList.get(0);
+        assertEquals("1001", sdkBean.getFaceUuid());
+        assertEquals("/sdcard/face/1001.jpg", sdkBean.getPicPath());
+        assertEquals("/sdcard/Download/faceFeature/1001.dat", sdkBean.getFeatureImportPath());
+    }
+
+    /**
+     * FaceUtils 必须暴露特征值导入入口,且签名是卡库自己的 bean 类型。
+     */
+    @Test
+    public void faceUtilsExposesFeatureImportEntry() throws Exception {
+        Method m = FaceUtils.class.getMethod("faceFeatureImport", List.class);
+        assertEquals(int.class, m.getReturnType());
+        assertNotNull(FaceUtils.getInstance());
+    }
+
+    /**
+     * 原有能力不能因为重编译而丢失。
+     */
+    @Test
+    public void originalFaceUtilsApiIsPreserved() throws Exception {
+        assertNotNull(FaceUtils.class.getMethod("faceBuild", List.class));
+        assertNotNull(FaceUtils.class.getMethod("getFaceResult"));
+        assertNotNull(FaceUtils.class.getMethod("getAllFaceId"));
+        assertNotNull(FaceUtils.class.getMethod("deleteFace", String.class));
+        assertNotNull(FaceUtils.class.getMethod("deleteAllFace"));
+        assertNotNull(FaceUtils.class.getMethod("getFaceConfig"));
+        assertNotNull(FaceUtils.class.getMethod("init", android.content.Context.class));
+        assertNotNull(FaceUtils.class.getMethod("destroy"));
+    }
+
+    /**
+     * toString 格式必须与厂商原版一致(改编译可能悄悄改变日志输出)。
+     */
+    @Test
+    public void toStringFormatIsUnchanged() {
+        FaceBuildBean bean = new FaceBuildBean();
+        bean.setPicPath("/a.jpg");
+        bean.setFaceUuid("1001");
+        bean.setErrCode(0);
+        assertEquals("FaceBuildBean{picPath='/a.jpg', faceUuid='1001', errCode=0}", bean.toString());
+    }
+}

+ 137 - 0
app/src/test/java/xn/xxp/FaceFeatureParseTest.java

@@ -0,0 +1,137 @@
+package xn.xxp;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Type;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.List;
+
+import xn.xxp.app.SyncFaceToolFeature;
+import xn.xxp.room.bean.FaceFeature;
+
+/**
+ * 校验人脸特征值的解析逻辑。
+ *
+ * <p>服务端 {@code terminal/sys/face/data/sub} 的 {@code faceFeature} 字段有两种可能形态:
+ * Base64 字符串(byte[]/BLOB 列经 Jackson 序列化)或原始特征值字符串。
+ * 两种都要能正确落到 {@link FaceFeature#getFaceFeature()} 的 byte[] 上。
+ */
+public class FaceFeatureParseTest {
+
+    /**
+     * 取生产代码里的 Gson 实例(特征值解析用的是带自定义适配器的那个)。
+     */
+    private static Gson faceFeatureGson() throws Exception {
+        Field field = SyncFaceToolFeature.class.getDeclaredField("FACE_FEATURE_GSON");
+        field.setAccessible(true);
+        return (Gson) field.get(null);
+    }
+
+    @SuppressWarnings("unchecked")
+    private static List<FaceFeature> parse(String dataJson) throws Exception {
+        Gson gson = faceFeatureGson();
+        Type type = new TypeToken<List<FaceFeature>>() {
+        }.getType();
+        return gson.fromJson(dataJson, type);
+    }
+
+    /**
+     * 服务端返回 Base64 时,必须还原成原始二进制。
+     */
+    @Test
+    public void base64FeatureIsDecodedToRawBytes() throws Exception {
+        byte[] origin = new byte[1024];
+        for (int i = 0; i < origin.length; i++) {
+            origin[i] = (byte) (i % 251);
+        }
+        String base64 = Base64.getEncoder().encodeToString(origin);
+
+        String json = "[{\"userId\":1001,\"userName\":\"张三\",\"userType\":\"1\","
+                + "\"pageType\":\"2\",\"isWhite\":\"0\",\"isDutyUser\":\"1\",\"lastUpdated\":1700000000,"
+                + "\"faceFeature\":\"" + base64 + "\"}]";
+
+        List<FaceFeature> list = parse(json);
+        assertEquals(1, list.size());
+        FaceFeature feature = list.get(0);
+        assertEquals(1001L, feature.getUserId());
+        assertEquals("张三", feature.getUserName());
+        assertEquals("1", feature.getUserType());
+        assertEquals("2", feature.getPageType());
+        assertEquals("0", feature.getIsWhite());
+        assertEquals("1", feature.getIsDutyUser());
+        assertEquals(1700000000L, feature.getLastUpdated());
+        assertNotNull(feature.getFaceFeature());
+        assertArrayEquals(origin, feature.getFaceFeature());
+    }
+
+    /**
+     * 服务端直接下发原始特征值字符串时,按原始字符串的 UTF-8 字节处理,不能报错也不能丢数据。
+     */
+    @Test
+    public void rawStringFeatureFallsBackToUtf8Bytes() throws Exception {
+        // 长度不是 4 的倍数,且含有非 Base64 字符 -> 一定不是 Base64
+        String raw = "raw-feature-value-这不是base64";
+
+        String json = "[{\"userId\":1002,\"userName\":\"李四\",\"lastUpdated\":1700000001,"
+                + "\"faceFeature\":\"" + raw + "\"}]";
+
+        List<FaceFeature> list = parse(json);
+        assertEquals(1, list.size());
+        FaceFeature feature = list.get(0);
+        assertEquals(1002L, feature.getUserId());
+        assertNotNull(feature.getFaceFeature());
+        assertArrayEquals(raw.getBytes(StandardCharsets.UTF_8), feature.getFaceFeature());
+    }
+
+    /**
+     * 服务端没下发特征值时,字段为 null,不能抛异常。
+     */
+    @Test
+    public void missingFeatureIsNull() throws Exception {
+        String json = "[{\"userId\":1003,\"userName\":\"王五\",\"lastUpdated\":1700000002}]";
+
+        List<FaceFeature> list = parse(json);
+        assertEquals(1, list.size());
+        assertNull(list.get(0).getFaceFeature());
+        assertEquals("王五", list.get(0).getUserName());
+    }
+
+    /**
+     * 空字符串的特征值按空处理。
+     */
+    @Test
+    public void emptyFeatureIsNull() throws Exception {
+        String json = "[{\"userId\":1004,\"faceFeature\":\"\"}]";
+
+        List<FaceFeature> list = parse(json);
+        assertEquals(1, list.size());
+        assertNull(list.get(0).getFaceFeature());
+    }
+
+    /**
+     * 实体本身要能正常承载 byte[],toString 不能把二进制全量打印出来。
+     */
+    @Test
+    public void entityToStringDoesNotDumpBinary() {
+        FaceFeature feature = new FaceFeature();
+        feature.setUserId(1005);
+        feature.setUserName("赵六");
+        feature.setFaceFeature(new byte[]{1, 2, 3, 4});
+
+        String text = feature.toString();
+        assertTrue(text.contains("4 bytes"));
+        assertTrue(text.contains("赵六"));
+        assertTrue(text.contains("1005"));
+    }
+}

+ 118 - 0
tools/cardlibrary-patch/README.md

@@ -0,0 +1,118 @@
+# cardlibrary 补丁工具
+
+给厂商 AAR `app/libs/cardlibrary-release.aar` 打补丁,让卡库(览众 `com.njlz.*`)跟上新版
+海康 `face_sdk`(`com.hikvision.smarteyes.*`)的能力。
+
+## 为什么需要补丁
+
+厂商的 `cardlibrary-release.aar` 里,`classes.jar` 是针对**旧版** face_sdk 编译的:
+
+| | 厂商原版 | 新版 face_sdk |
+|---|---|---|
+| `com.njlz.smartdata.FaceBuildBean` | picPath / faceUuid / errCode | 多了 **`featureImportPath`**(特征值导入用的本地文件路径) |
+| `com.njlz.face.FaceUtils` | 只有 `faceBuild()`(按图片建模) | 多了 **`FaceSdk.faceFeatureImport()`**(按特征值建模) |
+
+卡库内部靠 Gson 做一层 JSON 桥接来适配两套 bean:
+
+```
+faceBuild(List<com.njlz…FaceBuildBean>)
+    -> Gson.toJson(卡库 bean)
+    -> Gson.fromJson(json, TypeToken<List<com.hikvision…FaceBuildBean>>)
+    -> FaceSdk.faceBuild(...)
+```
+
+因为卡库镜像 bean 里没有 `featureImportPath` 字段,**特征值文件路径会在桥接那一步被静默丢弃**,
+按特征值建模退化成"按图片建模"(而 `picPath` 又是空的),最终建模失败。
+
+## 补丁内容
+
+只改 `classes.jar` 里的 2 个类(其余 22 个条目逐字节不变):
+
+1. **`com/njlz/smartdata/FaceBuildBean`** —— 补上 `featureImportPath` 字段 + getter/setter,
+   字段名必须与 SDK 侧完全一致(Gson 按字段名匹配)。`toString()` 格式保持与厂商原版一致。
+2. **`com/njlz/face/FaceUtils`** —— 新增 `faceFeatureImport(List<FaceBuildBean>)`,
+   走 `FaceSdk.faceFeatureImport()`;其余 22 个方法按厂商原版逐方法还原,
+   `@Subscribe` 注解、`FaceUtils$1/$2` 两个 `TypeToken` 匿名类的编号与泛型均保持不变。
+
+> AAR 内除 `classes.jar` 外的 26 个条目(jni 的 .so、libs/face_sdk.jar、AndroidManifest.xml 等)
+> 全部逐字节保持不变。
+
+## 用法
+
+```powershell
+powershell -ExecutionPolicy Bypass -File tools/cardlibrary-patch/patch.ps1
+```
+
+默认行为:
+
+- 输入 = 输出 = `app/libs/cardlibrary-release.aar`,**就地打补丁**
+- 厂商原版 AAR 直接放到 `app/libs/cardlibrary-release.aar` 即可,脚本会就地替换
+
+也支持自定义:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File tools/cardlibrary-patch/patch.ps1 `
+    -InputAar  D:\downloads\cardlibrary-release.aar `
+    -OutputAar D:\downloads\cardlibrary-release-patched.aar
+```
+
+脚本做的事:
+
+1. 用 JDK 17(`javac`)编译 `src/` 下的两个类,classpath = 卡库 `classes.jar` +
+   `libs/face_sdk.jar` + gson + eventbus + `android.jar`(按 `local.properties` 的 SDK 与
+   `gradle/libs.versions.toml` 的版本自动定位)
+2. 校验 `face_sdk.jar` 里确实有 `FaceSdk.faceFeatureImport`——没有就直接报错退出
+3. 把编译产物替换回 `classes.jar`,再重新打包成 AAR
+
+> **幂等**:补丁永远由 `src/` 下的源码重新编译生成,对已打过补丁的 AAR 重跑结果一致。
+> 仓库里只保留 `app/libs/` 下的一份 AAR,不重复存放厂商原版;
+> 需要留档的话请放在仓库外(例如 `D:\downloads\`)。
+
+## 目录
+
+```
+tools/cardlibrary-patch/
+├── patch.ps1                                  补丁脚本
+├── src/com/njlz/smartdata/FaceBuildBean.java  重写的卡库 bean
+├── src/com/njlz/face/FaceUtils.java           重写的卡库门面
+├── verify/VerifyPatch.java                    独立 JVM 验证器
+└── build/                                     临时产物(已 gitignore)
+```
+
+## 验证
+
+### 1. Gradle 单测(推荐)
+
+`app/src/test/java/xn/xxp/CardLibraryPatchTest.java` 覆盖:
+
+- 卡库 bean 带上了 `featureImportPath`
+- `featureImportPath` 能穿过 Gson 桥接到达 SDK bean
+- `FaceUtils.faceFeatureImport(List)` 存在
+- 原有 8 个方法与 `toString()` 格式未被破坏
+
+```powershell
+gradlew.bat :app:testDebugUnitTest
+```
+
+### 2. 独立 JVM 验证器(不依赖 Gradle)
+
+```powershell
+java -cp "app\libs\cardlibrary-release.aar\classes.jar;..." VerifyPatch
+```
+
+`verify/VerifyPatch.java` 直接对打好补丁的 `classes.jar` 做校验,输出逐条 PASS/FAIL。
+classpath 需要:补丁后的 `classes.jar` + `libs/face_sdk.jar` + gson + eventbus + `android.jar`。
+
+### 3. 完整构建
+
+```powershell
+gradlew.bat :app:checkDebugDuplicateClasses :app:assembleDebug
+```
+
+## 注意
+
+- **`app/libs` 下不要再单独放 `face_sdk.jar`**:AAR 里已经内嵌了一份,重复放置会产生
+  `Duplicate class` 编译错误。
+- 特征值导入依赖设备端人脸服务进程;RK3566 自建人脸(ThirdArm)通路只认 `picPath`,
+  不支持 `featureImportPath`。
+- 设备端的人脸服务 APK 也必须是支持 `featureImportPath` 的版本,否则该字段不生效。

+ 229 - 0
tools/cardlibrary-patch/patch.ps1

@@ -0,0 +1,229 @@
+<#
+.SYNOPSIS
+    给 cardlibrary-release.aar 打补丁:把卡库的人脸建模 bean 与 FaceUtils 升级到新版 face_sdk。
+
+.DESCRIPTION
+    厂商 AAR 里的 classes.jar 是针对旧版 face_sdk 编译的:
+      - com.njlz.smartdata.FaceBuildBean 缺少新版 SDK 的 featureImportPath 字段;
+      - com.njlz.face.FaceUtils 没有暴露 FaceSdk.faceFeatureImport(特征值导入)。
+
+    本脚本用 javac 把 tools/cardlibrary-patch/src 下的两个类重新编译,
+    替换回 AAR 内的 classes.jar,再重新打包成 AAR。
+    除这两个类外,AAR 内所有内容逐字节保持不变。
+
+.PARAMETER InputAar
+    要打补丁的 AAR。默认就是 app/libs/cardlibrary-release.aar —— 厂商原版直接放这里,脚本就地打补丁。
+
+.PARAMETER OutputAar
+    补丁后的 AAR 输出路径。默认与 InputAar 相同(就地替换)。
+
+.EXAMPLE
+    powershell -ExecutionPolicy Bypass -File tools/cardlibrary-patch/patch.ps1
+#>
+[CmdletBinding()]
+param(
+    [string]$InputAar = '',
+    [string]$OutputAar = ''
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+Add-Type -AssemblyName System.IO.Compression
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+
+$toolRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = Split-Path -Parent (Split-Path -Parent $toolRoot)
+$srcRoot = Join-Path $toolRoot 'src'
+$workDir = Join-Path $toolRoot 'build'
+
+if ([string]::IsNullOrWhiteSpace($InputAar)) {
+    $InputAar = Join-Path $repoRoot 'app\libs\cardlibrary-release.aar'
+}
+if ([string]::IsNullOrWhiteSpace($OutputAar)) {
+    $OutputAar = $InputAar
+}
+
+function Write-Step($msg) { Write-Host "==> $msg" -ForegroundColor Cyan }
+
+# ---------- 依赖定位 ----------
+function Resolve-Jdk {
+    $candidates = @('F:\java17\jdk-17.0.7', $env:JAVA_HOME, 'C:\Program Files\Java\jdk-17') |
+        Where-Object { $_ -and (Test-Path (Join-Path $_ 'bin\javac.exe')) }
+    foreach ($c in $candidates) {
+        # 直接读 JDK 的 release 文件,避免执行 javac -version 往 stderr 写导致 PowerShell 误判为错误
+        $rel = Join-Path $c 'release'
+        if (-not (Test-Path $rel)) { continue }
+        $txt = Get-Content $rel -Raw
+        if ($txt -match 'JAVA_VERSION="(\d+)') {
+            if ($Matches[1] -eq '17') { return $c }
+        }
+    }
+    throw '找不到 JDK 17(需要 javac 17)。请设置 JAVA_HOME。'
+}
+
+function Resolve-AndroidJar {
+    $props = Join-Path $repoRoot 'local.properties'
+    if (-not (Test-Path $props)) { throw "缺少 local.properties,无法定位 Android SDK" }
+    $sdkDir = (Select-String -Path $props -Pattern '^sdk\.dir=(.+)$').Matches[0].Groups[1].Value.Trim()
+    $sdkDir = $sdkDir -replace '\\:', ':' -replace '\\\\', '\'
+    $compileSdk = (Select-String -Path (Join-Path $repoRoot 'app\build.gradle') -Pattern 'compileSdk\s+(\d+)').Matches[0].Groups[1].Value
+    $jar = Join-Path $sdkDir "platforms\android-$compileSdk\android.jar"
+    if (-not (Test-Path $jar)) { throw "找不到 android.jar: $jar" }
+    return $jar
+}
+
+function Resolve-CacheJar($group, $name, $version = '', $ext = 'jar') {
+    $root = Join-Path $env:USERPROFILE ".gradle\caches\modules-2\files-2.1\$group\$name"
+    if (-not (Test-Path $root)) { throw "Gradle 缓存里找不到 ${group}:${name}" }
+    $pattern = if ($version) { "$name-$version.$ext" } else { "$name-*.$ext" }
+    $hit = Get-ChildItem $root -Recurse -Filter $pattern -File |
+        Sort-Object FullName -Descending | Select-Object -First 1
+    if (-not $hit) { throw "Gradle 缓存里找不到 ${group}:${name} 的 .$ext($version)" }
+    return $hit.FullName
+}
+
+# 原生命令执行:把 stderr 也当普通输出,避免 PowerShell 把 javac 的 warning 升级成终止错误
+function Invoke-Native([string]$exe, [string[]]$argv, [string[]]$filter = @()) {
+    $prev = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        & $exe @argv 2>&1 | ForEach-Object {
+            $line = $_.ToString()
+            if (-not ($filter | Where-Object { $line -match $_ })) { Write-Host $line }
+        }
+        return $LASTEXITCODE
+    } finally { $ErrorActionPreference = $prev }
+}
+
+# ---------- zip 工具 ----------
+function Read-ZipEntries([string]$path) {
+    $result = [ordered]@{}
+    $zip = [System.IO.Compression.ZipFile]::OpenRead($path)
+    try {
+        foreach ($entry in $zip.Entries) {
+            $ms = New-Object System.IO.MemoryStream
+            $s = $entry.Open()
+            $s.CopyTo($ms)
+            $s.Close()
+            $result[$entry.FullName] = $ms.ToArray()
+            $ms.Dispose()
+        }
+    } finally { $zip.Dispose() }
+    return , $result
+}
+
+function Write-ZipEntries([string]$path, $entries) {
+    $fs = [System.IO.File]::Create($path)
+    try {
+        $zip = New-Object System.IO.Compression.ZipArchive($fs, [System.IO.Compression.ZipArchiveMode]::Create)
+        try {
+            foreach ($name in $entries.Keys) {
+                $entry = $zip.CreateEntry($name, [System.IO.Compression.CompressionLevel]::Optimal)
+                $bytes = $entries[$name]
+                $s = $entry.Open()
+                $s.Write($bytes, 0, $bytes.Length)
+                $s.Close()
+            }
+        } finally { $zip.Dispose() }
+    } finally { $fs.Dispose() }
+}
+
+# ---------- 主流程 ----------
+Write-Step "JDK: $(Resolve-Jdk)"
+$jdkHome = Resolve-Jdk
+$javac = Join-Path $jdkHome 'bin\javac.exe'
+$androidJar = Resolve-AndroidJar
+$toml = Join-Path $repoRoot 'gradle\libs.versions.toml'
+$tomlText = Get-Content $toml -Raw
+$gsonVer = ([regex]::Match($tomlText, '(?m)^gson\s*=\s*"([^"]+)"')).Groups[1].Value
+$eventBusVer = ([regex]::Match($tomlText, '(?m)^eventbus\s*=\s*"([^"]+)"')).Groups[1].Value
+$gsonJar = Resolve-CacheJar 'com.google.code.gson' 'gson' $gsonVer
+$eventBusJar = Resolve-CacheJar 'org.greenrobot' 'eventbus-java' $eventBusVer
+Write-Step "android.jar : $androidJar"
+Write-Step "gson        : $gsonJar"
+Write-Step "eventbus    : $eventBusJar"
+
+if (-not (Test-Path $InputAar)) { throw "找不到输入 AAR: $InputAar" }
+Write-Step "输入 AAR   : $InputAar"
+Write-Step '提示: 脚本就地覆盖该文件;厂商原版请自行在仓库外留档(仓库里只保留一份,避免重复二进制)'
+
+if (Test-Path $workDir) { Remove-Item -Recurse -Force $workDir }
+New-Item -ItemType Directory -Path $workDir -Force | Out-Null
+
+# 1) 解包 AAR
+$aarDir = Join-Path $workDir 'aar'
+[System.IO.Compression.ZipFile]::ExtractToDirectory($InputAar, $aarDir)
+$classesJar = Join-Path $aarDir 'classes.jar'
+$faceSdkJar = Join-Path $aarDir 'libs\face_sdk.jar'
+if (-not (Test-Path $classesJar)) { throw 'AAR 内没有 classes.jar' }
+if (-not (Test-Path $faceSdkJar)) { throw 'AAR 内没有 libs/face_sdk.jar' }
+
+# 2) 校验 face_sdk 是否支持 faceFeatureImport
+$fsBytes = [System.IO.File]::ReadAllBytes($faceSdkJar)
+$fsEntries = Read-ZipEntries $faceSdkJar
+$faceSdkClass = $fsEntries['com/hikvision/smarteyes/smartdev/FaceSdk.class']
+if ($null -eq $faceSdkClass) { throw 'face_sdk.jar 内找不到 FaceSdk.class' }
+$faceSdkText = [System.Text.Encoding]::ASCII.GetString($faceSdkClass)
+if ($faceSdkText -notmatch 'faceFeatureImport') {
+    throw '当前 face_sdk.jar 不含 FaceSdk.faceFeatureImport,无法应用本补丁(请先升级 face_sdk)'
+}
+Write-Step 'face_sdk 已确认支持 FaceSdk.faceFeatureImport'
+
+# 3) 编译补丁类
+$outClasses = Join-Path $workDir 'classes'
+New-Item -ItemType Directory -Path $outClasses -Force | Out-Null
+$cp = @($classesJar, $faceSdkJar, $gsonJar, $eventBusJar, $androidJar) -join ';'
+$srcFiles = @(
+    (Join-Path $srcRoot 'com\njlz\smartdata\FaceBuildBean.java'),
+    (Join-Path $srcRoot 'com\njlz\face\FaceUtils.java')
+)
+foreach ($f in $srcFiles) { if (-not (Test-Path $f)) { throw "缺少源码: $f" } }
+
+Write-Step 'javac 编译补丁类...'
+$code = Invoke-Native $javac (@('-encoding', 'UTF-8', '--release', '7', '-nowarn', '-proc:none',
+        '-d', $outClasses, '-cp', $cp) + $srcFiles) @('source value 7 is obsolete', 'bootstrap class path')
+if ($code -ne 0) {
+    Write-Step "javac --release 7 失败(exit=$code),回退到 --release 8"
+    $code = Invoke-Native $javac (@('-encoding', 'UTF-8', '--release', '8', '-nowarn', '-proc:none',
+            '-d', $outClasses, '-cp', $cp) + $srcFiles) @('bootstrap class path')
+    if ($code -ne 0) { throw "javac 编译失败(exit=$code)" }
+}
+
+# 4) 替换 classes.jar 中的类
+$replaceMap = @{
+    'com/njlz/smartdata/FaceBuildBean.class' = 'com\njlz\smartdata\FaceBuildBean.class'
+    'com/njlz/face/FaceUtils.class'         = 'com\njlz\face\FaceUtils.class'
+    'com/njlz/face/FaceUtils$1.class'        = 'com\njlz\face\FaceUtils$1.class'
+    'com/njlz/face/FaceUtils$2.class'        = 'com\njlz\face\FaceUtils$2.class'
+    'com/njlz/face/FaceUtils$3.class'        = 'com\njlz\face\FaceUtils$3.class'
+}
+$classEntries = Read-ZipEntries $classesJar
+if ($classEntries.Contains('com/njlz/face/FaceUtils$3.class')) {
+    Write-Step '  提示: 该 AAR 已打过补丁,重跑是幂等的'
+}
+foreach ($key in $replaceMap.Keys) {
+    $newFile = Join-Path $outClasses $replaceMap[$key]
+    if (-not (Test-Path $newFile)) {
+        if ($key -eq 'com/njlz/face/FaceUtils$3.class') {
+            Write-Step "  跳过 $key(编译产物中没有该匿名类)"
+            continue
+        }
+        throw "编译产物缺少: $newFile"
+    }
+    $classEntries[$key] = [System.IO.File]::ReadAllBytes($newFile)
+    Write-Step "  替换 $key"
+}
+$patchedClassesJar = Join-Path $workDir 'classes.patched.jar'
+Write-ZipEntries $patchedClassesJar $classEntries
+
+# 5) 重新打包 AAR
+$aarEntries = Read-ZipEntries $InputAar
+$aarEntries['classes.jar'] = [System.IO.File]::ReadAllBytes($patchedClassesJar)
+$outDir = Split-Path -Parent $OutputAar
+if (-not (Test-Path $outDir)) { New-Item -ItemType Directory -Path $outDir -Force | Out-Null }
+$tmpOut = Join-Path $workDir 'cardlibrary-release.patched.aar'
+Write-ZipEntries $tmpOut $aarEntries
+Copy-Item $tmpOut $OutputAar -Force
+
+Write-Step "完成 -> $OutputAar"
+Write-Step ("大小: {0:N0} 字节" -f (Get-Item $OutputAar).Length)

+ 184 - 0
tools/cardlibrary-patch/src/com/njlz/face/FaceUtils.java

@@ -0,0 +1,184 @@
+package com.njlz.face;
+
+import android.content.Context;
+import android.graphics.Bitmap;
+import android.view.SurfaceView;
+import android.view.TextureView;
+
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+import com.hikvision.smarteyes.smartdev.FaceSdk;
+import com.njlz.smartdata.FaceBuildBean;
+import com.njlz.smartdata.FaceConfig;
+import com.njlz.smartdata.FaceIdentifyData;
+import com.njlz.smartdata.FaceLocationData;
+
+import org.greenrobot.eventbus.EventBus;
+import org.greenrobot.eventbus.Subscribe;
+
+import java.util.List;
+
+/**
+ * 卡库人脸能力门面。
+ *
+ * <p>本类按厂商原版逐方法还原,新增一个 {@link #faceFeatureImport(List)} 方法,
+ * 用于对接新版 face_sdk 的特征值导入能力({@code FaceSdk.faceFeatureImport})。
+ *
+ * <p>注意:类中三个 {@code new TypeToken&lt;...&gt;() {}} 匿名类的出现顺序决定了它们在
+ * class 文件中的编号({@code FaceUtils$1} / {@code FaceUtils$2} / {@code FaceUtils$3})。
+ * 修改方法顺序会改变编号,请勿调整 {@code faceBuild} 与 {@code getFaceResult} 的先后位置。
+ */
+public class FaceUtils {
+
+    private static volatile FaceUtils Instance;
+
+    @SuppressWarnings("unused")
+    private FaceUtils faceUtils;
+
+    private FaceUtils() {
+    }
+
+    public static FaceUtils getInstance() {
+        if (Instance == null) {
+            synchronized (FaceUtils.class) {
+                if (Instance == null) {
+                    Instance = new FaceUtils();
+                }
+            }
+        }
+        return Instance;
+    }
+
+    @Subscribe
+    public void onEvent(com.hikvision.smarteyes.smartdev.data.SmartDataEvent event) {
+        Gson gson = new Gson();
+        String json = gson.toJson(event);
+        com.njlz.event.SmartDataEvent smartDataEvent = gson.fromJson(json, com.njlz.event.SmartDataEvent.class);
+        EventBus.getDefault().post(smartDataEvent);
+    }
+
+    @Subscribe
+    public void onReceive(com.hikvision.smarteyes.smartdev.data.BuildModelEvent event) {
+        Gson gson = new Gson();
+        String json = gson.toJson(event);
+        com.njlz.event.BuildModelEvent buildModelEvent = gson.fromJson(json, com.njlz.event.BuildModelEvent.class);
+        EventBus.getDefault().post(buildModelEvent);
+    }
+
+    public void init(Context context) {
+        EventBus.getDefault().register(this);
+        FaceSdk.get().init(context);
+    }
+
+    public void destroy() {
+        EventBus.getDefault().unregister(this);
+        FaceSdk.get().destroy();
+    }
+
+    /**
+     * 按图片建模(老能力,保持不变)。
+     */
+    public int faceBuild(List<FaceBuildBean> list) {
+        Gson gson = new Gson();
+        String json = gson.toJson(list);
+        List sdkList = gson.fromJson(json, new TypeToken<List<com.hikvision.smarteyes.facelib.FaceBuildBean>>() {
+        }.getType());
+        return FaceSdk.get().faceBuild(sdkList);
+    }
+
+    public List<FaceBuildBean> getFaceResult() {
+        List result = FaceSdk.get().getFaceBuildResult();
+        if (result == null) {
+            return null;
+        }
+        Gson gson = new Gson();
+        String json = gson.toJson(result);
+        return gson.fromJson(json, new TypeToken<List<FaceBuildBean>>() {
+        }.getType());
+    }
+
+    /**
+     * 按特征值文件建模(新能力,新版 face_sdk 提供)。
+     *
+     * <p>与 {@link #faceBuild(List)} 的区别:走 {@code FaceSdk.faceFeatureImport},
+     * 建模素材为本地特征值文件({@link FaceBuildBean#getFeatureImportPath()}),
+     * 而不是人脸图片({@link FaceBuildBean#getPicPath()})。
+     *
+     * <p>注意:该能力依赖设备端人脸服务进程,不支持 RK3566 自建人脸(ThirdArm)通路。
+     *
+     * @return 0 表示成功,其余为错误码
+     */
+    public int faceFeatureImport(List<FaceBuildBean> list) {
+        Gson gson = new Gson();
+        String json = gson.toJson(list);
+        List sdkList = gson.fromJson(json, new TypeToken<List<com.hikvision.smarteyes.facelib.FaceBuildBean>>() {
+        }.getType());
+        return FaceSdk.get().faceFeatureImport(sdkList);
+    }
+
+    public List<String> getAllFaceId() {
+        return FaceSdk.get().getAllFaceUuid();
+    }
+
+    public int deleteFace(String faceUuid) {
+        return FaceSdk.get().deleteFace(faceUuid);
+    }
+
+    public int deleteAllFace() {
+        return FaceSdk.get().deleteAllFace();
+    }
+
+    public Bitmap getFacePic(String faceUuid) {
+        return FaceSdk.get().getFacePic(faceUuid);
+    }
+
+    public int startFaceRecog() {
+        return FaceSdk.get().startFaceRecog();
+    }
+
+    public FaceIdentifyData[] getIdentifyResultDatas() {
+        com.hikvision.smarteyes.smartdev.data.FaceIdentifyData[] datas = FaceSdk.get().getIdentifyResultDatas();
+        if (datas == null) {
+            return null;
+        }
+        Gson gson = new Gson();
+        String json = gson.toJson(datas);
+        return gson.fromJson(json, FaceIdentifyData[].class);
+    }
+
+    public int startPreview(SurfaceView surfaceView) {
+        return FaceSdk.get().startPreview(surfaceView);
+    }
+
+    public int startPreview(TextureView textureView) {
+        return FaceSdk.get().startPreview(textureView);
+    }
+
+    public int stopPreview() {
+        return FaceSdk.get().stopPreview();
+    }
+
+    public int stopFaceTask() {
+        return FaceSdk.get().stopFaceTask();
+    }
+
+    public FaceLocationData[] getFaceLocationDatas() {
+        com.hikvision.smarteyes.smartdev.data.FaceLocationData[] datas = FaceSdk.get().getFaceLocationDatas();
+        if (datas == null) {
+            return null;
+        }
+        Gson gson = new Gson();
+        String json = gson.toJson(datas);
+        return gson.fromJson(json, FaceLocationData[].class);
+    }
+
+    public FaceConfig getFaceConfig() {
+        com.hikvision.smarteyes.smartdev.data.FaceConfig config = FaceSdk.get().getFaceConfig();
+        if (config == null) {
+            return null;
+        }
+        Gson gson = new Gson();
+        String json = gson.toJson(config);
+        return gson.fromJson(json, FaceConfig.class);
+    }
+}

+ 63 - 0
tools/cardlibrary-patch/src/com/njlz/smartdata/FaceBuildBean.java

@@ -0,0 +1,63 @@
+package com.njlz.smartdata;
+
+/**
+ * 卡库(览众)人脸建模参数。
+ *
+ * <p>本类是对海康 face_sdk 中 {@code com.hikvision.smarteyes.facelib.FaceBuildBean} 的镜像副本。
+ * 新版 face_sdk 为该 bean 增加了 {@code featureImportPath} 字段(特征值导入用的本地文件路径),
+ * 本类同步补齐该字段,使卡库与新版 SDK 的字段映射保持一致。
+ *
+ * <p>字段名必须与 SDK 侧完全一致 —— 卡库内部通过 Gson 做 JSON 桥接
+ * (card bean -> JSON -> sdk bean),Gson 按字段名匹配。
+ */
+public class FaceBuildBean {
+    private String picPath;
+    private String faceUuid;
+    private int errCode;
+    /** 新版 face_sdk 字段:本地特征值文件路径(.dat 等),用于特征值导入建模。 */
+    private String featureImportPath;
+
+    public FaceBuildBean() {
+    }
+
+    @Override
+    public String toString() {
+        return "FaceBuildBean{"
+                + "picPath='" + picPath + '\''
+                + ", faceUuid='" + faceUuid + '\''
+                + ", errCode=" + errCode
+                + '}';
+    }
+
+    public int getErrCode() {
+        return errCode;
+    }
+
+    public void setErrCode(int errCode) {
+        this.errCode = errCode;
+    }
+
+    public String getPicPath() {
+        return picPath;
+    }
+
+    public void setPicPath(String picPath) {
+        this.picPath = picPath;
+    }
+
+    public String getFaceUuid() {
+        return faceUuid;
+    }
+
+    public void setFaceUuid(String faceUuid) {
+        this.faceUuid = faceUuid;
+    }
+
+    public String getFeatureImportPath() {
+        return featureImportPath;
+    }
+
+    public void setFeatureImportPath(String featureImportPath) {
+        this.featureImportPath = featureImportPath;
+    }
+}

+ 84 - 0
tools/cardlibrary-patch/verify/VerifyPatch.java

@@ -0,0 +1,84 @@
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+import com.njlz.face.FaceUtils;
+import com.njlz.smartdata.FaceBuildBean;
+
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 独立验证器:不依赖 Gradle,直接对打好补丁的 classes.jar 做 JVM 级校验。
+ *
+ * <p>用法:
+ * <pre>
+ * java -cp "&lt;classes.jar&gt;;&lt;face_sdk.jar&gt;;&lt;gson.jar&gt;;&lt;eventbus.jar&gt;" VerifyPatch
+ * </pre>
+ */
+public class VerifyPatch {
+
+    private static int failures = 0;
+
+    public static void main(String[] args) throws Exception {
+        // 1) 卡库 bean 必须带上新版 SDK 的 featureImportPath
+        FaceBuildBean cardBean = new FaceBuildBean();
+        cardBean.setFaceUuid("1001");
+        cardBean.setPicPath("/sdcard/face/1001.jpg");
+        cardBean.setFeatureImportPath("/sdcard/Download/faceFeature/1001.dat");
+        check("card bean 读取 featureImportPath",
+                "/sdcard/Download/faceFeature/1001.dat".equals(cardBean.getFeatureImportPath()));
+
+        // 2) 关键回归:字段必须能穿过卡库内部的 Gson 桥接到达 SDK bean
+        List<FaceBuildBean> cardList = new ArrayList<>();
+        cardList.add(cardBean);
+        Gson gson = new Gson();
+        String json = gson.toJson(cardList);
+        check("JSON 含 featureImportPath", json.contains("featureImportPath"));
+        System.out.println("    bridge json = " + json);
+
+        List<com.hikvision.smarteyes.facelib.FaceBuildBean> sdkList =
+                gson.fromJson(json, new TypeToken<List<com.hikvision.smarteyes.facelib.FaceBuildBean>>() {
+                }.getType());
+        check("桥接后列表长度 == 1", sdkList.size() == 1);
+        check("桥接后 faceUuid 保持", "1001".equals(sdkList.get(0).getFaceUuid()));
+        check("桥接后 picPath 保持", "/sdcard/face/1001.jpg".equals(sdkList.get(0).getPicPath()));
+        check("桥接后 featureImportPath 保持",
+                "/sdcard/Download/faceFeature/1001.dat".equals(sdkList.get(0).getFeatureImportPath()));
+
+        // 3) FaceUtils 必须暴露特征值导入入口
+        Method m = FaceUtils.class.getMethod("faceFeatureImport", List.class);
+        check("FaceUtils.faceFeatureImport 存在且返回 int", m.getReturnType() == int.class);
+
+        // 4) 原有能力不能丢
+        check("faceBuild 保留", FaceUtils.class.getMethod("faceBuild", List.class) != null);
+        check("getFaceResult 保留", FaceUtils.class.getMethod("getFaceResult") != null);
+        check("getAllFaceId 保留", FaceUtils.class.getMethod("getAllFaceId") != null);
+        check("deleteFace 保留", FaceUtils.class.getMethod("deleteFace", String.class) != null);
+        check("deleteAllFace 保留", FaceUtils.class.getMethod("deleteAllFace") != null);
+        check("getFaceConfig 保留", FaceUtils.class.getMethod("getFaceConfig") != null);
+        check("单例可用", FaceUtils.getInstance() != null);
+
+        // 5) toString 格式与厂商原版一致
+        FaceBuildBean t = new FaceBuildBean();
+        t.setPicPath("/a.jpg");
+        t.setFaceUuid("1001");
+        t.setErrCode(0);
+        check("toString 格式未变",
+                "FaceBuildBean{picPath='/a.jpg', faceUuid='1001', errCode=0}".equals(t.toString()));
+
+        System.out.println();
+        if (failures == 0) {
+            System.out.println("ALL CHECKS PASSED");
+        } else {
+            System.out.println(failures + " CHECK(S) FAILED");
+            System.exit(1);
+        }
+    }
+
+    private static void check(String name, boolean ok) {
+        System.out.println((ok ? "[PASS] " : "[FAIL] ") + name);
+        if (!ok) {
+            failures++;
+        }
+    }
+}