# Card Scan Demo 说明

> 对照《集换社_反编译分析报告》（v3.23.15）与本仓库当前实现，说明 demo 定位、流水线与差异。

---

## 1. 背景：集换社里的「卡牌扫描」

集换社是 TCG 卡牌 **C2C 交易平台**（包名 `com.jihuanshe`），卡牌扫描只是完整业务中的一环，不是独立工具 App。

反编译报告里与扫描相关的关键结论：

| 项 | 集换社侧证据 |
|----|--------------|
| 入口 | `CardScanActivity` / `CardScanAlbumActivity` / `CaptureActivity` / `ScanActivity` |
| 相机 | CameraX（`MetadataHolderService` 等） |
| 识别 | Google ML Kit（`libmlkitcommonpipeline.so` ~8.4MB、`GraphicOverlay`、`MlKitInitProvider`） |
| 裁剪 | uCrop（`MCropActivity`）— 识别不佳时可手动纠偏后再跑 |
| 结果 | 匹配卡牌库 → `CardDetailActivity`（详情 / 价格）→ 购物车或上架 |

报告中的扫描流程可概括为：

```
相机 / 相册 → ML Kit 边框检测 →（可选）手动裁剪 → 匹配卡牌数据库 → 详情页
```

加固（爱加密）导致无法还原完整 Java/Kotlin 源码，上述链路主要来自 Manifest、Native 库与 Flutter 字符串等静态证据，**不是**可运行的源码级复刻。

本 demo **只复现「拍/选图 → 锁定卡边 → 裁剪纠偏」** 这一段视觉能力，不包含交易、匹配库、登录、支付等平台能力。

---

## 2. Demo 是什么

纯 Flutter 小应用（`carddex_demo` v2.0.0），竖屏暗色 UI。

**一句话**：拍照或相册选图 → 按 TCG 引导框裁切 → ML Kit 目标检测得到外接框 → 经典 CV 细化倾斜四边形 → 透视 / 轴对齐裁剪 → 预览结果。

**明确不做**：

- 实时预览帧上的检测（拍摄页只有引导框）
- 卡牌身份识别 / 图库检索 / 价格
- 打包自研或从 APK 抽取的 TFLite 模型（早期方案已废弃）
- 集换社业务（订单、IM、拍卖、仓储等）

---

## 3. 与集换社扫描链路的对照

| 维度 | 集换社（反编译推断） | 本 Demo |
|------|----------------------|---------|
| 形态 | 交易 App 内嵌模块（Native Activity） | 独立 Flutter Demo |
| 采集 | CameraX + 相册 Activity | `camera` + `image_picker` |
| 检测时机 | 报告描述含实时预览标注（`GraphicOverlay`） | **仅静帧**：进入预览页后跑一次 |
| 检测引擎 | Google ML Kit | 同为 Google ML Kit Object Detection |
| 边框形态 | 报告侧重 AABB + Overlay；细节不可见 | AABB → 可选倾斜四边形细化 |
| 裁剪纠偏 | uCrop 手动为主 | 自动透视 / 轴对齐裁剪（无手动 uCrop） |
| 下游 | 匹配卡库 → 详情 / 交易 | **无**：只展示锁定框与裁切图 |
| 架构上下文 | Native + Flutter Hybrid + 大量 SDK | 单应用、无后端、无加固 |

技术选型上，demo 与集换社扫描模块最接近的一点是：**都用 ML Kit 做卡牌区域定位，而不是卡牌分类识别**。定位成功后，集换社走业务匹配；demo 停在图像几何处理。

早期仓库内的 `carddex_flutter_demo_plan.md` 曾计划复刻 CardDex 的本地 `detect.tflite`；当前实现已改为 ML Kit，与集换社扫描栈更一致，也避免依赖 APK 内模型资产。

---

## 4. 工程结构

```
lib/
├── main.dart                 # 入口、竖屏、暗色主题
├── screens/
│   ├── capture_screen.dart   # 相机预览 + 引导框（无 ML）
│   └── preview_screen.dart   # 检测 / 细化 / 裁剪 / 展示
├── services/
│   ├── card_detector.dart    # ML Kit 静帧检测 + 选框 + 调用细化
│   ├── card_corner_refiner.dart  # Otsu / 连通域 / 最小外接四边形
│   └── card_cropper.dart     # 透视或轴对齐裁剪，贴合 63:88
└── widgets/
    ├── guide_overlay.dart    # 拍摄页暗角 + 白框
    └── guide_frame.dart      # 引导框几何（含 BoxFit.cover 映射）
```

依赖（与相机 / 图像相关）：

| 包 | 作用 |
|----|------|
| `camera` | 后置预览与拍照 |
| `image_picker` | 相册 |
| `google_mlkit_object_detection` | 静帧目标检测 |
| `image` | 解码、模糊输入、透视 `copyRectify`、JPEG |
| `path_provider` | 引导裁切临时文件 |

`assets/` 为空：模型由 ML Kit 插件运行时提供，不随 App 打包自定义 `.tflite`。

---

## 5. 用户流程

```mermaid
flowchart LR
  A["CaptureScreen<br/>相机 / 相册"] --> B["PreviewScreen"]
  B --> C["按引导框裁切全图"]
  C --> D["ML Kit 静帧检测"]
  D --> E["经典 CV 角点细化"]
  E --> F["透视 / AABB 裁剪"]
  F --> G["展示锁定框 + 结果图"]
  G --> H["重新拍摄 → pop"]
```

| 页面 | 职责 |
|------|------|
| **CaptureScreen** | 后置相机、`ResolutionPreset.high`、引导遮罩、快门 / 相册 / 翻转。生命周期：切后台释放、回前台重建。 |
| **PreviewScreen** | 全部视觉处理与结果 UI（绿框锁定、置信度 / 标签、裁切图、重拍）。 |

导航为一次 `Navigator.push`，无路由库、无状态管理包。

---

## 6. 处理流水线（实现细节）

### 6.1 引导框

TCG 常见比例 **63:88**。框约占视口高度 62%、宽度 78%，垂直中心约在 46%。

- 拍照：用预览视口 + `BoxFit.cover` 反算到照片像素（`GuideFrame.inCoverImage`）。
- 相册：直接在图像坐标系算引导矩形（`GuideFrame.inImage`）。

进入检测前先按引导框裁掉框外区域，减小背景干扰（隐含前提：卡已大致落在框内）。

### 6.2 ML Kit 检测（`CardDetector`）

- `DetectionMode.single`，开启分类与多目标。
- 输出 `CardBox`：AABB、置信度、标签（通用 COCO 类名，**不是**卡牌 ID）。
- `pickBest`：分数 = `0.4 * confidence + 0.6 * fillRatio`，丢弃填充比 ∉ `[0.04, 0.98]` 的框。

这是通用物体检测，不是「宝可梦 / 游戏王」专用模型；能锁边框即可，标签仅作调试信息。

### 6.3 角点细化（`CardCornerRefiner`）

在 AABB 邻域做经典视觉，把轴对齐框尽量收成倾斜四边形：

1. 顶部略抬高、ROI 外扩  
2. 灰度 → 模糊 → Otsu，保证 AABB 中心为前景  
3. 最大连通域（优先覆盖种子点）  
4. 凸包 → 最小面积矩形 → TL→TR→BR→BL  
5. 面积校验失败则退回 AABB；成功则外扩并照顾卡头区域  

### 6.4 裁剪（`CardCropper`）

| 条件 | 行为 |
|------|------|
| 有倾斜四边形 | `copyRectify` 透视变换 → 竖向校正 → 贴合 63:88 |
| 仅有 AABB | 外扩约 6% 后轴对齐裁切并贴合比例 |
| 无检测框 | 按引导框中心区域裁切（`usedDetection: false`） |

大图最长边限制约 2560；JPEG 质量约 98。

---

## 7. 能力边界（相对报告中的产品能力）

反编译报告中的集换社扫描落点是 **「识别成功 → 匹配数据库 → 交易」**。本 demo 停在几何裁切：

```
集换社:  采集 → ML Kit → (uCrop) → 匹配库 → 详情/交易
本 Demo: 采集 → 引导裁切 → ML Kit → 角点细化 → 自动裁切 → 预览
                ▲                              ▲
                多出的本地几何步骤               无业务下游
```

因此：

- 能验证「静帧 + ML Kit 锁边 + 透视纠偏」是否够用做上架 / 鉴定前处理。
- **不能**验证卡牌检索准确率、价格、多卡桌面、强反光 / 极端角度等产品级指标。
- 检测失败时仍可按引导框出图，便于继续调试 UI，但不代表识别成功。

---

## 8. 运行

```bash
export PATH="$HOME/flutter/bin:$PATH"
cd /Users/a1518/Desktop/project/card-dex-demo
flutter pub get
flutter run
```

Android `minSdk` 为 26；需相机与媒体读取权限。真机效果明显优于模拟器。

---

## 9. 相关文档

| 文档 | 说明 |
|------|------|
| [集换社_反编译分析报告.md](../../apk_analysis/recognize/202607_analysis/集换社_反编译分析报告.md) | APK 静态分析（扫描相关见 §4.8、§6.2、§9.1） |
| [carddex_flutter_demo_plan.md](../carddex_flutter_demo_plan.md) | 早期 TFLite 方案（已与当前实现不一致，仅作历史参考） |
| [README.md](../README.md) | 最短运行说明 |

---

## 10. 小结

本 demo 是对照集换社扫描模块做的 **视觉前处理实验床**：同样依赖 Google ML Kit 做区域定位，但用 Flutter 实现「引导框 → 静帧检测 → 角点细化 → 透视裁切」闭环，刻意剥离交易与图库匹配。若后续要对齐集换社产品路径，需要在裁切结果之上另接卡牌检索 / 版本匹配 API，而不是继续堆叠本仓库内的几何管线。