Dựng Zalo Mini App bán hàng có CRM quản trị

00Bản đồ hệ thống — bốn khối chạy, đừng trộn

Đọc xong mục này là biết mỗi lệnh sau đây gõ ở thư mục nào.

Nét liền: gọi trực tiếp. Nét đứt: sự kiện qua hàng đợi, có thể trễ.

01Giấy tờ và tài khoản phải có trước

Khâu này không viết được dòng mã nào mà vẫn tốn 1–3 tuần. Làm song song với mục 02.

1. Official Account đã xác thực doanh nghiệp Mini App bắt buộc gắn một OA. Xác thực cần giấy phép kinh doanh khớp tên chủ tài khoản. Chưa xác thực thì không xin được quyền lấy số điện thoại, không gửi được tin ZBS.
2. Zalo App → lấy App ID và Secret Key Tạo tại Zalo for Developers. ZALO_APP_SECRET dùng để giải mã token số điện thoại (xem mục 13.4 — có cái bẫy IP ở đây).
3. Mini App → lấy Mini App ID ID này nằm công khai trong URL app (zalo.me/s/<appId>), khai vào app-config.json và ZALO_MINI_APP_ID của Worker.
4. Khai ngay trong lần đầu vào Portal Tên · mô tả · icon · ảnh bìa · danh mục · chính sách quyền riêng tư · điều khoản sử dụng (hai trang này phải có URL thật — xem docs/dieu-khoan-su-dung.html) · phạm vi quyền xin của app.
5. Pancake POS → Shop ID + API Key Đây là nguồn sự thật về sản phẩm, tồn kho, đơn hàng. Lấy luôn danh sách kho để chọn DEFAULT_WAREHOUSE_ID (mục 02 bước 6).
6. Cloudflare Worker + D1 + Pages + một Durable Object. Gói Free chạy đủ, nhưng Durable Object phải khai kiểu new_sqlite_classes mới dùng được ở gói Free.
7. Cổng thanh toán Zalo Checkout SDK (bắt buộc, xem mục 05) + SePay để đối soát chuyển khoản. SePay nên cấp một tài khoản định danh (VA) riêng cho Mini App để webhook không lẫn với web.
8. Hạ tầng phụ trên IP Việt Nam Một chỗ chạy PHP trên hosting Việt Nam (ở đây là enzara.vn) để làm proxy giải mã số điện thoại. Cloudflare bị Zalo trả -501 khi giải mã từ IP ngoài VN.
9. Nếu dùng Messenger Facebook App + Page Access Token + App Secret. Không dùng thì bỏ qua, hệ thống không gãy.

02Backend — Worker + D1, dựng trước tất cả

Mini App và CRM đều chỉ là mặt tiền. Dựng backend xong thì hai cái kia chỉ còn là giao diện.

1. Cài và đăng nhập

   cd backend
   npm install
   npx wrangler login

2. Tạo D1 và dán database_id

   npm run db:create     # in ra database_id → dán vào wrangler.toml
   npm run db:schema:local
   npm run db:schema:remote

3. Chạy toàn bộ migration — bằng vòng lặp, không gõ tay 33 lần

   Tên script có dấu hai chấm, mà zsh hiểu :r là ký hiệu cắt đuôi tệp nên npm run db:migrate$n:remote gọi sai script mà không báo lỗi rõ. Phải dựng tên trước:

   for n in {2..34}; do
     M=$(printf 'db:migrate%s:remote' "$n")
     npm run "$M" || echo "DỪNG ở $n"
   done

   Thứ tự là bắt buộc: bảng sau tham chiếu bảng trước. Danh mục từng migration ở Phụ lục B.

4. Nạp khoá bí mật

   Dev local: backend/.dev.vars (đã gitignore). Bản thật: npx wrangler secret put <TÊN>. Bảng đầy đủ ở Phụ lục A — cái nào bắt buộc, cái nào thiếu thì tính năng nào tắt.

   Bắt buộc tối thiểu để bán được hàng: PANCAKE_API_KEY, PANCAKE_SHOP_ID, ADMIN_JWT_SECRET, ZALO_CHECKOUT_PRIVATE_KEY.

5. Khai biến công khai trong wrangler.toml

   PANCAKE_BASE_URL · ALLOWED_ORIGINS · DEFAULT_WAREHOUSE_ID · SEPAY_ACCOUNT/SEPAY_BANK · PHONE_PROXY_URL · ZALO_MINI_APP_ID · BOT_BASE_URL · MESSENGER_GRAPH_VERSION.

6. Chọn kho mặc định — không được bỏ trống

   curl "http://localhost:8787/api/_pancake/ping?token=<DIAG_TOKEN>"
   curl "http://localhost:8787/api/_pancake/warehouses?token=<DIAG_TOKEN>"

   Lấy id của kho muốn bán và đặt vào DEFAULT_WAREHOUSE_ID.

7. Khai Durable Object cho hộp thư

   HOP_THU → lớp HopThuHub, migration tag hop-thu-v1 với new_sqlite_classes. Đây là trạm WebSocket duy nhất giữ kết nối của gateway và các tab hộp thư.

8. Khai hai cron — đọc kỹ giờ UTC

   crons = ["0 23 * * *", "*/10 0-16,23 * * *"]

   0 23 * * * = 6h sáng giờ VN (đồng bộ bài viết từ website). */10 0-16,23 * * * = 10 phút/lần, 6h–24h giờ VN (lưới an toàn hàng đợi CRM; ban đêm nghỉ, sự kiện vẫn nằm trong bảng chờ sáng gom). Viết 0 6 * * * là 13h chiều VN.

9. Gắn tên miền và deploy

   npx wrangler deploy      # route custom_domain: zalo-app.enzara.vn

   Chờ ~1 phút rồi mới kết luận có lỗi: node biên cần thời gian lan bản mới.

03CRM quản trị — làm trước Mini App

Lý do đảo thứ tự: có CRM thì nhập được sản phẩm, khuyến mãi, quà, hạng — Mini App mới có gì để hiện.

1. Tạo tài khoản chủ đầu tiên (chạy một lần)

   curl -X POST "https://zalo-app.enzara.vn/admin/seed" \
     -H "Authorization: Bearer <ADMIN_JWT_SECRET>" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"<mật-khẩu-mạnh>"}'

   Mật khẩu lưu dạng băm PBKDF2. Đổi mật khẩu = chạy lại lệnh này, hoặc dùng mục Đổi mật khẩu trong trang.

2. Build và deploy

   cd admin
   VITE_API_BASE="https://zalo-app.enzara.vn" npm run build
   npx wrangler pages deploy dist --project-name enzara-admin

   Rồi gắn tên miền cho project Pages.

3. Thêm người dùng và chia vai

   Thiết lập → Người dùng. Vai nhan_vien chỉ dùng trang; mọi giá trị vai khác đều là CHỦ (cố ý: tài khoản cũ mang role='admin' không bị bản cập nhật cướp quyền). Hệ thống chặn tự khoá mình ra ngoài: luôn còn ít nhất một chủ, không tự xoá tài khoản đang đăng nhập.

4. Cài như ứng dụng

   iPhone: Chia sẻ → Thêm vào MH chính. Android: ⋮ → Cài đặt ứng dụng. Máy tính: biểu tượng cài ở thanh địa chỉ. Service worker chỉ cache vỏ app — mọi lời gọi API luôn đi thẳng ra mạng, số liệu không bao giờ cũ.

16 mục — mỗi mục để làm gì

04Mini App — giao diện khách

Bốn sửa đổi bắt buộc trong vite.config.mts

Thiếu bất cứ cái nào thì preview trên điện thoại ra màn hình trắng, không báo lỗi:

Quy trình deploy — bắt buộc 3 bước

zmp build
zmp sync-config www/index.html     <-- thiếu bước này = MÀN HÌNH TRẮNG
zmp deploy -p -e -m "mô tả"        # thêm -t nếu cần bản TESTING

Kiểm nhanh sau khi build:

node -e "const c=require('./app-config.json'),fs=require('fs');
console.log([...c.listCSS,...c.listSyncJS.filter(x=>x.startsWith('./'))]
  .every(f=>fs.existsSync('www/'+f.replace('./',''))) ? 'KHỚP' : 'LỆCH')"

Hạn mức deploy — đừng đốt bản TESTING

Lệnh không có -t đi vào DEVELOPMENT, không phải production: Mini App không có đường deploy thẳng ra khách, mọi bản phát hành phải gửi duyệt trên Portal. zmp deploy chỉ in mã QR, link có dạng https://zalo.me/s/<appId>/?env=TESTING&version=<n>.

Test trên điện thoại thật

zmp start -Z                          # Android: qua adb reverse
zmp start -Z -ios -iosH <IP-LAN>      # iPhone: qua Wi-Fi
adb shell screencap -p /sdcard/a.png  # chụp màn hình khi không có console

Trang /chan-doan là bộ đo trên máy khách: nó gọi lần lượt các API zmp-sdk, đo bộ nhớ ba tầng, báo cầu nối native sống hay chết, rồi gửi kết quả về /api/client-log. Đây là thứ duy nhất cho biết máy khách hỏng ở đâu khi không có DevTools.

05Thanh toán — phần dễ bị trả về nhất

Zalo yêu cầu mọi giao dịch trực tuyến phải đi qua Checkout SDK. COD không tính là trực tuyến.

Bốn công thức chữ ký, khác nhau hoàn toàn

Đây là chỗ mất thời gian nhất. Chép sai một dấu & là Zalo báo “sai mac” mà không nói sai ở đâu.

So sánh chữ ký luôn dùng timingSafeEqual, không dùng ===.

06Khách hàng, điểm, hạng và các cần bán

Tất cả nằm trên D1, chỉnh được từ CRM, Mini App chỉ đọc — không chép hằng số xuống app.

07Vận chuyển và theo dõi đơn

08Tin nhắn ra khách — ZBS thay ZNS

Khách quan tâm OA được cộng điểm một lần trọn đời (/api/points/claim-oa-follow) — đây là cách đổi lượt quan tâm OA thành thứ khách thấy đáng.

09Trợ lý tự động — ba kênh

Bot im lặng là hành vi đúng trong ba trường hợp: khách đang được người thật trả lời, câu hỏi vượt phạm vi đã khai, và ngoài khung giờ cho phép. Khi bot câm ngoài ba cái đó, tra theo thứ tự: khoá mô hình → kênh đã bật chưa → nhật ký hội thoại trong tab Trợ lý.

10Hộp thư Zalo cá nhân — khối thứ tư

Đây là phần mới nhất của bản 2, và là phần duy nhất không chạy được trên Cloudflare.

Bốn sự thật phải thiết kế quanh nó

• Zalo không cho lấy lại lịch sử. zca-js chỉ phát lại tin cũ đúng lúc kết nối. Nên tin tới phải ghi xuống đĩa trước (data/hang-doi.ndjson) rồi mới gửi lô lên Worker — không được phép chỉ nằm trong RAM.
• Một số Zalo chỉ giữ được một phiên web. Mở Zalo Web của số đó là gateway bị đá (mã 3000/3003) — và khi đó gateway không tự giành lại, phải gọi /ket-noi-lai.
• Cổng 18930 chỉ một tiến trình. Bật bản mới khi bản cũ còn sống thì chết ngay vì EADDRINUSE. Tìm tiến trình bằng ps -Ao pid,command | grep index.ts — pgrep -f ".../src/index.ts" KHÔNG khớp vì dòng lệnh thật là node src/index.ts.
• “Đã gửi lệnh” ≠ “khách đã nhận”. Số đang mất phiên thì gateway nhận lệnh rồi mới từ chối. Nên Worker kiểm hop_thu_tai_khoan.trang_thai = 'dang_ket_noi' trước khi ghi nhật ký thành công.

Chữ ký giữa gateway và Worker: X-Gw-Signature = hex(HMAC-SHA256("<X-Gw-Timestamp>.<thân>", GATEWAY_SECRET)). Chưa nạp GATEWAY_SECRET thì /gw/* trả 503 (đóng hẳn); nạp rồi mà ký sai thì 401. Nhịp tim 30s/lần; quá 3 phút không thấy thì Hộp thư báo “Gateway im lặng”.

11CRM ngoài — hai chiều

• Chưa đặt CRM_API_KEY → toàn bộ /crm/* trả 503. Không có khoá thì không mở cửa.
• Chưa khai nơi nhận → chiều đẩy tắt (sự kiện vẫn được ghi, cron dọn ngay), chiều kéo vẫn chạy.
• Không đặt CRM_WEBHOOK_SECRET → sự kiện gửi đi không có chữ ký; chỉ chấp nhận khi CRM nằm trong mạng nội bộ.
• Đường đi chính là bắn thẳng ngay sau khi Worker trả lời xong lượt sinh ra sự kiện (trễ mili-giây). Cron 10 phút chỉ nhặt hai loại sót: lần gửi trước thất bại, và sự kiện sinh ra ban đêm.
• CRM phải tự chống nhận trùng theo id sự kiện.
• Không có ở đây: chi tiết đơn hàng. /crm/customers chỉ trả tổng hợp; đơn gốc nằm ở Pancake.

12Đặt hàng ngoài Mini App

Ba ràng buộc thiết kế của trang này, không được vi phạm khi sửa:

1. Tự chứa hoàn toàn Không CDN ngoài, không font ngoài, không thư viện. Khách đang ở đây vì app đã hỏng — không được để họ vấp thêm lần nữa.
2. Cùng gốc với API Gọi /api/... bằng đường dẫn tương đối: không CORS, không preflight.
3. Không tin giá ở client Trang chỉ hiện tạm tính; tổng tiền thật do POST /api/orders tính lại từ Pancake. Khách sửa HTML cũng không ăn gian được.

13Mười cái bẫy đã trả giá

Mỗi dòng dưới đây từng làm mất nửa ngày đến hai ngày. Đọc trước sẽ rẻ hơn gặp lại.

14Nghiệm thu và phát hành

Thứ tự nghiệm thu

1. Máy tính, trình duyệt npm start + wrangler dev: đủ luồng mua từ trang chủ tới đơn.
2. Điện thoại Android zmp start -Z: kiểm cầu nối native, quyền, SĐT.
3. Điện thoại iPhone zmp start -Z -ios -iosH <IP> + /chan-doan: kiểm ba tầng bộ nhớ và cầu nối. Coi iOS là máy chạy không trạng thái.
4. Bản DEVELOPMENT Đặt thử một đơn COD và một đơn chuyển khoản thật (số tiền nhỏ), xác nhận tiền về và trạng thái đổi.
5. Bản TESTING Chỉ khi cần người khác test. 60 lượt, dùng dè.
6. Gửi duyệt Kèm tài khoản test, video luồng mua, trang điều khoản + chính sách.

Checklist trước khi gửi duyệt

• Mọi giao dịch trực tuyến đi qua Checkout SDK (COD được để ngoài).
• Không còn màn hình trống, không còn dữ liệu mẫu sót lại.
• Trang chính sách quyền riêng tư + điều khoản có URL sống.
• Chỉ xin đúng những quyền app thật sự dùng, và có giải thích trong app trước khi xin.
• Đơn thật đã chạy trọn vòng: app → Worker → Pancake → SePay/Checkout → tin báo khách.

Ngay sau khi lên sóng

• Bật npx wrangler tail theo dõi ngày đầu; xem /api/client-log để biết máy khách hỏng ở đâu.
• Kiểm gateway còn sống (nhịp tim < 3 phút) và cron có chạy đúng giờ VN.
• Theo dõi hạn mức: ZBS (trần tự đặt), gọi mô hình của bot, và số lượt deploy còn lại.

APhụ lục — biến và khoá bí mật

Khoá bí mật nạp bằng npx wrangler secret put <TÊN>; biến công khai khai trong [vars] của wrangler.toml. Dev local: backend/.dev.vars.

Phía Mini App

VITE_API_URL (chỉ dev; bản thật đọc apiUrl trong app-config.json) · VITE_UI_V2 (đặt 0 để build ra giao diện cũ) · ZMP_TOKEN trong .env (đã gitignore).

Phía gateway

WORKER_URL · GATEWAY_SECRET trong gateway/.env. Phiên Zalo lưu ở gateway/data/sessions/<ownId>.json (quyền 0600) — đây là dữ liệu đăng nhập thật, không commit, không sao lưu lên chỗ chung.

BPhụ lục — 33 migration, chạy đúng thứ tự

db/schema.sql chạy trước (có sẵn admin_users), rồi 002 → 034.

CPhụ lục — bản đồ endpoint