From 12d21b0d23f4dfef699f425d2b31bc3e7bef9176 Mon Sep 17 00:00:00 2001 From: Fam Zheng Date: Thu, 9 Apr 2026 09:50:20 +0100 Subject: [PATCH] doc: rewrite README with architecture overview and module docs --- README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 964ef2d..55f4548 100644 --- a/README.md +++ b/README.md @@ -1 +1,140 @@ -# themblem.com project \ No newline at end of file +# 徵象 Themblem + +**AI 驱动的智能防伪溯源平台** + +徵象基于"无复制性原理"，利用二维码在印刷过程中形成的微观差异作为不可复制的"图像指纹"，结合深度学习模型实现高精度真伪鉴别。消费者仅需通过微信小程序扫码，即可在 1-2 秒内完成防伪验证。 + +## 架构总览 + +``` +┌──────────────────────┐ ┌────────────────────┐ +│ 微信小程序 (scanner) │ │ 管理后台 (web) │ +│ · 扫码采集 │ │ · Vue 3 + CoreUI │ +│ · WASM QR 检测 │ │ · 产品/批次管理 │ +│ · 实时验证 │ │ · 扫描数据分析 │ +└──────────┬───────────┘ └──────────┬─────────┘ + │ │ + ▼ ▼ +┌──────────────────────────────────────────────────┐ +│ Django API (api) │ +│ · REST API (Tastypie) · 多租户隔离 │ +│ · AI 对话 (DeepSeek) · 阿里云 OSS 存储 │ +│ · 设备摄像头适配 · PostgreSQL │ +└──────────────────────┬───────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ alg (C++) │ │ emblem5 (AI)│ │ Kubernetes │ +│ · libqr │ │ · ResNet18 │ │ · K3s │ +│ · WASM 编译 │ │ · 训练/推理 │ │ · Traefik │ +│ · 特征提取 │ │ · wandb │ │ · Nginx │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +## 项目结构 + +``` +├── alg/ QR 码检测与特征提取 (C++/WASM) +├── api/ Django REST API 后端 +├── web/ Vue 3 管理后台 +├── scanner/ 微信小程序 +├── emblem5/ AI 训练与推理流水线 (PyTorch) +├── deploy/ Kubernetes 部署配置 +├── scripts/ 部署脚本与 CLI 工具 +├── dataset/ 训练数据集样本 +├── doc/ 产品与技术文档 +├── Makefile 构建、训练、部署一站式入口 +└── .gitlab-ci.yml CI/CD 流水线 +``` + +## 核心模块 + +### QR 检测引擎 (`alg/`) + +基于 OpenCV 构建的 QR 码检测与特征提取库，核心用 C++ 编写，编译产出： + +- **qrtool** — CLI 工具，用于离线处理 +- **qrtool.web.wasm** — 浏览器端 WebAssembly +- **qrtool.wx.wasm** — 微信小程序 WebAssembly + +关键算法包括 QR 码定位、透视矫正、微观特征提取和相似度比对（CellWeight / FuzzyPixelCmp）。 + +### AI 训练流水线 (`emblem5/`) + +基于 PyTorch ResNet18 的迁移学习方案，完整覆盖数据采集到模型部署全流程： + +```bash +make fetch # 从 API 拉取扫描数据 +make sbs # 生成 side-by-side 训练图对 +make train # 训练模型 (30 epochs) +make check-accuracy MODEL=... # 评估模型准确率 +``` + +训练方法：将扫描帧与标准图像分别切割为 3×3 网格，逐块对比学习微观特征差异，最终通过投票机制判定真伪。当前最佳模型准确率达 **98.94%** (正样本) / **96.13%** (负样本)。 + +### API 后端 (`api/`) + +Django + Tastypie REST API，核心功能： + +- 多租户隔离与权限管理 +- 二维码批次生成与生命周期管理 +- 扫描数据采集与验证结果分析 +- AI 客服对话 (DeepSeek + RAG) +- 设备摄像头参数动态适配 (覆盖 1500+ 机型) + +### 管理后台 (`web/`) + +Vue 3 + CoreUI 构建的 SPA 管理面板，提供产品管理、批次操作、扫描数据分析、AI 对话配置、模型管理等功能。 + +### 微信小程序 (`scanner/`) + +消费者端扫码验证入口。内置 WebAssembly QR 检测引擎，通过 Worker 线程实现非阻塞实时检测，支持自动亮度感应、设备特定参数适配等优化。 + +## 快速开始 + +### 环境要求 + +- Python 3.10+, Node.js 16+ +- PostgreSQL +- Docker (构建镜像) + +### 本地开发 + +```bash +# API 后端 +cd api && pip install -r ../requirements.txt +./manage.py migrate && ./manage.py runserver + +# Web 前端 +cd web && npm install && npm run serve + +# AI 训练 (需 GPU) +make fetch && make sbs && make train +``` + +### 构建与部署 + +```bash +make web # 构建前端 +make docker-build # 构建 Docker 镜像 +make docker-push # 推送至镜像仓库 +make deploy-api-dev # 部署到开发环境 +make deploy-api-prod # 部署到生产环境 +``` + +## 技术栈 + +| 层级 | 技术 | +|------|------| +| 前端 | Vue 3, CoreUI, Chart.js | +| 后端 | Django, Tastypie, Gunicorn, Nginx | +| AI/ML | PyTorch, ResNet18, Kornia, wandb | +| 计算机视觉 | OpenCV, C++, WebAssembly (Emscripten) | +| 存储 | PostgreSQL, 阿里云 OSS | +| 部署 | Docker, Kubernetes (K3s), Traefik | +| 小程序 | 微信原生 + WASM Worker | + +## 许可证 + +Proprietary — 广州市诚投科技有限公司 © 2024