🔵 Zalo Mini App — BOM Gift Integration Plan

Mô hình hoạt động — 3 lớp

┌─────────────────────────────────────────────────────────────┐
│                    ZALO SUPER APP                           │
│  ┌───────────────────────────────────┐                      │
│  │         ZALO MINI APP             │                      │
│  │  (React + ZaUI Components)        │                      │
│  │                                   │                      │
│  │  1. authorize() → Zalo User ID    │                      │
│  │  2. getAccessToken() → token      │                      │
│  │  3. getPhoneNumber() → SĐT       │                      │
│  │  4. getLocation() → GPS           │                      │
│  │                                   │                      │
│  │  Gọi BOM Gift API với token       │                      │
│  └──────────────┬────────────────────┘                      │
│                 │ HTTPS                                      │
└─────────────────┼───────────────────────────────────────────┘
                  │
     ┌────────────▼────────────────────────┐
     │       BOM GIFT BACKEND              │
     │    (Laravel — bom.gift)             │
     │                                     │
     │  /api/v1/zalo/*  (NEW endpoints)    │
     │                                     │
     │  ┌─ ZaloAuthMiddleware ───────────┐ │
     │  │ Nhận token từ Mini App         │ │
     │  │ → Gọi BOM.ASIA verify token   │ │
     │  │ → Nhận phone + Zalo user info  │ │
     │  │ → Resolve tenant + customer    │ │
     │  └──────────────┬────────────────┘ │
     │                 │                   │
     │  Campaign logic (existing):         │
     │  - Collect / Survey / Gift          │
     └────────────┬───────────────────────┘
                  │ sync Zalo user data
     ┌────────────▼────────────────────────┐
     │       BOM.ASIA SERVER               │
     │    (Zalo Ready — existing system)   │
     │                                     │
     │  ┌─ Zalo Integration Hub ─────────┐ │
     │  │                                │ │
     │  │  POST /api/v2/zalo/verify      │ │
     │  │  → Verify Zalo access token    │ │
     │  │  → Decode phone_token          │ │
     │  │  → Return verified user info   │ │
     │  │                                │ │
     │  │  POST /api/v2/zalo/user/sync   │ │
     │  │  → Lưu Zalo user profile       │ │
     │  │  → Map phone ↔ Zalo User ID    │ │
     │  │  → Lưu avatar, display name    │ │
     │  │                                │ │
     │  │  ZNS OTP (existing)            │ │
     │  │  ZNS Templates (existing)      │ │
     │  │  ZNS Notification (existing)   │ │
     │  └────────────────────────────────┘ │
     │                                     │
     │  Single source of truth cho:        │
     │  - Zalo user data                   │
     │  - Zalo OA connections              │
     │  - ZNS messaging                    │
     │  - App credentials (app_id/secret)  │
     └────────────────────────────────────┘

Campaign trên Mini App — Thiết kế tối ưu

Admin Setting: Toggle "Hiển thị trên Zalo Mini App"

// Quy tắc:
// - Web landing: Campaign::active()->latest()->first()
// - Zalo Mini App: Campaign::active()->where('zalo_miniapp', true)->first()
// - Nếu không có campaign nào bật zalo_miniapp → Mini App hiện "Chưa có chương trình"
// - Chỉ 1 campaign bật zalo_miniapp tại 1 thời điểm (per tenant)

// API:
GET /api/v1/zalo/campaign
// → Trả 1 campaign có zalo_miniapp=true (giống /campaigns/active nhưng filter thêm)

Lợi ích:

• Đơn giản — Mini App luôn load 1 campaign, 1 flow (survey HOẶC collect)
• Admin kiểm soát — chọn campaign nào chạy trên Mini App, không phụ thuộc "latest"
• Không cần Campaign Selector — UX gọn, user vào thẳng flow
• Có thể khác Web — web chạy campaign A, Mini App chạy campaign B (cùng tenant)
• Switch dễ — tắt campaign cũ, bật campaign mới trên Mini App mà không ảnh hưởng web

Ví dụ tenant Star:
┌──────────────────────────────────────────────────┐
│ Campaign "Trưng bày POSM" (collect)              │
│   status: active                                 │
│   zalo_miniapp: ✅ true   ← hiển thị trên Mini App│
│   web landing: ✅ (latest) ← hiển thị trên web   │
│                                                  │
│ Campaign "Khảo sát Q2" (survey)                  │
│   status: active                                 │
│   zalo_miniapp: ❌ false  ← không show Mini App  │
│   web landing: ❌ (không phải latest)             │
└──────────────────────────────────────────────────┘

So sánh Web SPA vs Zalo Mini App

Flow xác thực (thay thế OTP)

Frontend (Zalo Mini App - React)

// Step 1-3: Trong Zalo Mini App
import { authorize, getAccessToken, getPhoneNumber } from 'zmp-sdk';

const auth = await authorize();
const { accessToken } = await getAccessToken();
const { token: phoneToken } = await getPhoneNumber();

// Step 4: Gửi lên backend
const res = await fetch('https://tenant.bom.gift/api/v1/zalo/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        access_token: accessToken,
        phone_token: phoneToken,
    })
});
const { app_token, customer } = await res.json();
// Dùng app_token cho mọi API call sau đó

Backend (Laravel — NEW)

// POST /api/v1/zalo/auth
// 1. Nhận access_token + phone_token từ Mini App
// 2. Gọi Zalo API verify: GET graph.zalo.me/v2.0/me?access_token=...
// 3. Decode phone_token → lấy SĐT thật
// 4. Find/Create Customer by phone + tenant
// 5. Lưu zalo_user_id vào customer
// 6. Trả JWT app_token (dùng cho các API sau)

return response()->json([
    'app_token'  => $jwt,
    'customer'   => ['id', 'full_name', 'phone', ...],
    'campaign'   => [...], // active campaign data
]);

Vai trò BOM.ASIA trong hệ thống

BOM.ASIA (https://bom.asia/api/v2) là Zalo Hub trung tâm — đã có sẵn hệ thống Zalo (ZNS, OA, templates). Thông tin Zalo user sẽ lưu về bom.asia, BOM Gift chỉ lưu mapping reference.

BOM.ASIA APIs đã có sẵn (từ api-information.html)

BOM.ASIA đã có đầy đủ Zalo Mini App module — không cần tạo mới!

API A: POST /api/miniapp/auth/decode-phone

ĐÃ CÓ Decode phone token từ Zalo SDK → SĐT thật

POST https://bom.asia/api/miniapp/auth/decode-phone
{
    "phone_token": "token_from_getPhoneNumber()"
}
// → Returns: decoded phone number

API B: POST /api/miniapp/auth/check-phone

ĐÃ CÓ Verify phone + lưu Mini App user IDs

POST https://bom.asia/api/miniapp/auth/check-phone
{
    "phone": "0938123456",
    "mini_app_user_id": "zalo_mini_app_uid",
    "oa_user_id": "zalo_oa_uid",
    "zalo_app_id": "app_id",
    "name": "Nguyễn Văn A",
    "avatar": "https://..."
}
// → Lưu/Update user trên bom.asia + trả user info

API C: POST /api/miniapp/auth/login

ĐÃ CÓ Login via Zalo token hoặc phone → Sanctum token

POST https://bom.asia/api/miniapp/auth/login
{
    "access_token": "zalo_access_token",
    // hoặc phone-based login
}
// → Returns: Bearer token cho các API sau

API D: POST /api/miniapp/checkin/decode-location-token

ĐÃ CÓ Decode location token → GPS coordinates

Các API khác đã sẵn sàng:

Auth Flow (dùng BOM.ASIA APIs đã có)

Code Backend (BOM Gift side)

// POST /api/v1/zalo/auth — ZaloController
public function auth(Request $request)
{
    $bomApi = app(BomApiService::class);
    $tenant = $request->attributes->get('current_tenant');

    // Step 1: Decode phone token → lấy SĐT thật (BOM.ASIA đã có API)
    $decode = $bomApi->decodeZaloPhone($request->phone_token);
    if (!$decode['ok']) abort(401, 'Phone decode failed');
    $phone = $decode['data']['phone'];

    // Step 2: Sync Zalo user info lên BOM.ASIA (lưu trên bom.asia)
    $bomApi->syncZaloMiniAppUser([
        'phone'            => $phone,
        'mini_app_user_id' => $request->zalo_user_id,
        'oa_user_id'       => $request->oa_user_id,
        'zalo_app_id'      => $request->zalo_app_id,
        'name'             => $request->display_name,
        'avatar'           => $request->avatar_url,
    ]);

    // Step 3: Find/Create LOCAL customer (bom.gift chỉ lưu campaign data)
    $campaign = Campaign::active()
        ->where('tenant_id', $tenant->id)->latest()->first();

    $customer = Customer::firstOrCreate(
        ['phone' => $phone, 'tenant_id' => $tenant->id, 'campaign_id' => $campaign?->id],
        [
            'source_type'   => $campaign?->type ?? 'collect',
            'full_name'     => $request->display_name,
            'zalo_user_id'  => $request->zalo_user_id,
            'verified_at'   => now(),
        ]
    );

    // Step 4: Issue JWT cho Mini App (dùng cho các API sau)
    $jwt = JwtService::issue($customer, $tenant);
    return response()->json([
        'app_token'  => $jwt,
        'customer'   => [...],
        'campaign'   => [...],  // active campaign + form_config + programs
    ]);
}

BomApiService — Methods mới (gọi API đã có trên bom.asia)

// Thêm vào app/Services/BomApiService.php
// Base URL: /api/miniapp (KHÔNG cần JWT auth — module public)

public function decodeZaloPhone(string $phoneToken): array
{
    // Gọi API đã có: POST /api/miniapp/auth/decode-phone
    $response = Http::timeout(10)
        ->post("{$this->baseUrl}/../miniapp/auth/decode-phone", [
            'phone_token' => $phoneToken,
        ]);
    return $response->successful()
        ? ['ok' => true, 'data' => $response->json('data')]
        : ['ok' => false, 'error' => $response->json('message', 'Decode failed')];
}

public function syncZaloMiniAppUser(array $data): array
{
    // Gọi API đã có: POST /api/miniapp/auth/check-phone
    $response = Http::timeout(10)
        ->post("{$this->baseUrl}/../miniapp/auth/check-phone", $data);
    return $response->successful()
        ? ['ok' => true, 'data' => $response->json('data')]
        : ['ok' => false, 'error' => $response->json('message')];
}

Tái sử dụng HTTP client. Module /api/miniapp trên bom.asia là public (không cần JWT auth).

Vấn đề: Mỗi tenant = 1 brand = có thể có Zalo Mini App riêng

Giải pháp: 2 tầng setting

Tầng 1: Super Admin — BOM.ASIA Setting

Super Admin cấu hình Zalo credentials trên bom.asia (không phải bom.gift):

BOM.ASIA đã quản lý multi-app:

// bom.asia quản lý nhiều Zalo app:
// /api/miniapp/auth/decode-phone — tự detect app_id từ phone_token
// /api/miniapp/auth/check-phone — truyền zalo_app_id để phân biệt
// /api/v2/zalo-oa/accounts — list tất cả OA accounts
// → Mỗi tenant map với 1 zalo_app_id + 1 oa_id

Tầng 2: Tenant Admin — BOM Gift Setting

Tenant admin cấu hình tại BOM Gift, menu: /admin/branding hoặc /admin/setting

Lưu trữ: tenants.zalo_config (JSON)

// Per-tenant, không chứa secret
{
    "enabled": true,
    "app_id": "111222333",       // reference → bom.asia app
    "oa_id": "444555666",        // reference → bom.asia OA
    "auto_create": true,
    "welcome_msg": "Chào mừng bạn đến với Star!"
}

Multi-Tenant API Flow

Khi user mở Mini App của tenant Star:

// 1. Mini App gửi auth request
POST https://star.bom.gift/api/v1/zalo/auth
{
    "phone_token": "...",
    "zalo_user_id": "...",
    "zalo_app_id": "111222333"  // Mini App tự biết app_id của mình
}

// 2. BOM Gift middleware ResolveTenant
//    Domain star.bom.gift → tenant_id = 2 (Star)
//    Kiểm tra: tenants.zalo_config.enabled === true
//    Kiểm tra: tenants.zalo_config.app_id === request.zalo_app_id

// 3. BOM Gift → BOM.ASIA: decode phone
POST https://bom.asia/api/miniapp/auth/decode-phone
{ "phone_token": "..." }
// → phone: "0938123456"

// 4. BOM Gift → BOM.ASIA: sync user (truyền app_id để bom.asia biết app nào)
POST https://bom.asia/api/miniapp/auth/check-phone
{
    "phone": "0938123456",
    "zalo_app_id": "111222333",  // Star's app
    "mini_app_user_id": "...",
    "name": "Nguyễn Văn A"
}
// → bom.asia lưu user under app 111222333

// 5. BOM Gift: Create local customer
Customer::firstOrCreate(
    ['phone' => '0938123456', 'tenant_id' => 2],  // Star
    ['source_type' => 'collect', 'zalo_user_id' => '...', ...]
);

// 6. Issue JWT chứa tenant_id + customer_id
//    Mọi API sau đều scope by tenant_id trong JWT

Admin UI — Ai thấy gì

Flow tổng quan

API 1: POST /api/v1/zalo/auth

PUBLIC Xác thực Zalo user, trả app_token

Request

{
    "access_token": "zalo_access_token_from_sdk",
    "phone_token": "phone_number_token_from_getPhoneNumber"
}

Response 200

{
    "app_token": "eyJhbGci...",  // JWT, valid 24h
    "expires_at": "2026-03-19T12:00:00Z",
    "customer": {
        "id": 123,
        "full_name": "Nguyễn Văn A",  // null nếu mới
        "phone": "0938123456",
        "zalo_user_id": "8734526190",
        "is_new": true
    },
    "campaign": {
        "id": 2, "type": "collect", "name": "...",
        "form_config": {...},
        "landing_config": {...},
        "programs": [...]
    }
}

API 2: GET /api/v1/zalo/campaign

AUTH Lấy campaign active + form config + programs

Response

// Giống /campaigns/active hiện tại
// + form_config cho biết field nào active/required
// + programs với image, stock, input_type

API 3: POST /api/v1/zalo/collect/register

AUTH Đăng ký thông tin — phone tự lấy từ token, không cần nhập

Request

{
    "full_name": "Nguyễn Văn A",
    "gender": "male",          // theo form_config
    "age": 25,                  // theo form_config
    "ward_code": "27112",       // theo form_config
    "address": "120 NVL",       // theo form_config
    "pharmacy_name": "...",      // theo form_config
    "medical_rep_id": 5,         // theo form_config
    "notes": "...",              // theo form_config
    "lat": 10.776,               // từ getLocation()
    "lng": 106.700,
    "consent_health": true
}
// phone + zalo_user_id + campaign_id → tự lấy từ auth token

Response 200

{
    "customer_id": 123,
    "message": "Đăng ký thành công"
}

API 4-6: Programs, Choose, Summary

AUTH Tái sử dụng logic hiện có

GET  /api/v1/zalo/collect/programs     // → Giống /collect/programs
POST /api/v1/zalo/collect/choose       // → Giống /collect/choose
GET  /api/v1/zalo/collect/summary      // → Giống /collect/summary
GET  /api/v1/zalo/wards/provinces      // → Giống /wards/provinces
GET  /api/v1/zalo/wards?province_code= // → Giống /wards
GET  /api/v1/zalo/collect/medical-reps // → Giống /collect/medical-reps

Sự khác biệt duy nhất: middleware xác thực bằng JWT (từ Zalo auth) thay vì session.

Flow tổng quan

POST /api/v1/zalo/auth                // Xác thực (giống type 2)
POST /api/v1/zalo/customers           // Lưu thông tin KH
GET  /api/v1/zalo/survey              // Câu hỏi khảo sát
POST /api/v1/zalo/survey/submit       // Gửi đáp án → scoring
POST /api/v1/zalo/gift/generate       // Tạo gift code + QR
GET  /api/v1/zalo/gift/{code}         // Xem gift code status

Migration cần tạo

// 1. Thêm zalo_config vào tenants
Schema::table('tenants', function ($table) {
    $table->json('zalo_config')->nullable();
    // {"app_id","app_secret","oa_id","enabled"}
});

// 2. Thêm zalo fields vào customers (zalo_user_id đã có)
// customers.zalo_user_id — đã tồn tại ✓

// 3. Tạo bảng zalo_sessions (JWT tracking)
Schema::create('zalo_sessions', function ($table) {
    $table->id();
    $table->foreignId('customer_id')->constrained();
    $table->foreignId('tenant_id')->constrained();
    $table->string('zalo_user_id');
    $table->string('token_hash', 64)->unique(); // SHA256 of JWT
    $table->timestamp('expires_at');
    $table->string('ip_address', 45)->nullable();
    $table->timestamps();
});

Vị trí: /admin/setting → Section "Zalo Mini App"

Hoặc: Per-Tenant tại Branding page

Thêm tab "Zalo Mini App" tại /admin/branding — tenant admin tự cấu hình.

Phase 1: Type 2 Collect (Ưu tiên)

Phase 2: Type 1 Survey

Phase 3: Nâng cao (Tương lai)

API Route Summary

Tóm tắt quyết định kiến trúc

1. Route group riêng /api/v1/zalo/* — không ảnh hưởng API hiện tại
2. BOM.ASIA = Zalo Hub — verify token, decode phone, lưu Zalo user profile. BOM Gift KHÔNG giữ Zalo secrets
3. JWT thay session — stateless, phù hợp Mini App (không có cookie)
4. Không cần OTP — Zalo đã verify phone, tiết kiệm chi phí ZNS
5. Tái sử dụng logic — Controller mới gọi Service/Model hiện có
6. BomApiService mở rộng — thêm verifyZaloToken() + syncZaloUser(), tái sử dụng JWT auth + retry
7. Config nhẹ per Tenant — chỉ lưu enabled + miniapp_id reference, không lưu secret