← Hướng dẫn sử dụng · tài liệu kỹ thuật, không chính thức; thông tin cá nhân đã được ẩn

9698 Photobooth v3.5.0 — Khảo sát giao diện, chức năng, API và kiến trúc

Nguồn: thao tác trực tiếp trên app đang chạy + đọc mã đã bundle trong app.asar (chỉ đọc) + log trong %APPDATA%\9698-photobooth.

1. Công nghệ

• Electron (main / preload / renderer), React 18 + react-router, antd 5, lucide-react, đóng gói bằng electron-vite, cài bằng Inno/NSIS, tự cập nhật qua electron-updater (provider generic, https://app.9698media.com/app/, kênh latest).
• Máy ảnh: webcam (getUserMedia) hoặc Canon EDSDK (napi-canon-cameras, native). Cổng serial (serialport) cho thiết bị ngoài.
• AI: OpenAI gpt-image-2 (key của khách, gọi trực tiếp từ máy), MediaPipe tasks-vision + onnxruntime-node (xử lý ảnh cục bộ, ảnh thẻ/tách nền), mp4-muxer (video/timelapse), qrcode.
• In: webContents.print + getPrintersAsync của Electron (máy in chính/phụ, ICC, in ngang).
• Dữ liệu cục bộ: JSON trong %APPDATA%\9698-photobooth\data, ảnh trong Documents\PhotoboothPhotos, hàng đợi upload upload-queue.json, log dongbo-log.txt, luong-log.txt, canon-runtime-log.txt. 192 kênh IPC (ipcMain.handle, ví dụ config:get, config:set, session:list).

2. Giao diện đã chụp (kiểm tra thực tế)

3. Kết quả test

Test bổ sung: đã tạo mẫu khung (1 ô "Ảnh từ booth") ở Thêm khung, lưu thành công ("Đã lưu mẫu", tự lưu sau mỗi thay đổi). Chạy kiosk → Chọn khung ảnh hiện khung mới (có ảnh minh hoạ) → Tiếp tục → màn chụp báo "Không mở được camera" (webcam Logitech C922 đã cài driver nhưng đang không cắm, máy không có camera khác). Nút Thử lại vẫn lỗi như cũ; nút Thoát/Quay lại hoạt động. Vì vậy đếm ngược, chụp, chọn bộ lọc, màn chia sẻ/QR, in và thanh toán vẫn chưa test được; cần cắm webcam. Máy in có sẵn: EPSON WF-C5290BA, EPSON L8050, Microsoft Print to PDF.

Lưu ý nhỏ: nút "Chạy" ở dock Hồ sơ cần bấm 2 lần mới vào (lần đầu chỉ hiện tooltip) — có thể là lỗi UX do hộp thoại "Ảnh thẻ" vừa đóng.

3.1 Test đầy đủ với Canon EOS 70D + DNP DS-RX1 (đã chạy thật)

Cấu trúc file một phiên: <Sự kiện>\<mã>.jpg (ảnh in), _web\…-3600.jpg, _thumb\, _don\ (ảnh đơn), _tl\ (timelapse), may-anh-goc\ (RAW/JPG gốc từ Canon). Mã phiên 8 ký tự (vd <mã>) là khoá chung cho QR, f/<mã>/… và p/<mã> trên R2.

Nhật ký luồng cho thấy các trạng thái: TAM-VE → CHUP-XONG → DOI-ANH → VAO-SUA → DOI-LOC → GHEP-IN → IN → DON-LUOT (đáng dùng khi thiết kế máy trạng thái).

3.2 Test thu tiền, voucher, Smartbooth, QR (không in thêm)

Đã khôi phục: tắt thu tiền, tắt Smartbooth, loại sự kiện về Đám cưới. Còn lại: 10 voucher thử chưa dùng (mỗi mã 1 tờ) trong cài đặt thanh toán, mã booth "1t" trên server, phiên Bản quán 8 ảnh trong thư mục dữ liệu.

Chưa test: quét QR bằng điện thoại thật, chuyển khoản/SePay, Smartbooth từ điện thoại, Ảnh thẻ và Ảnh AI (khoá theo gói).

3.3 Màn hình/chức năng bổ sung (rà soát lần 2)

Danh sách màn trong mã nguồn (20 chunk) đều đã được xem, trừ các màn khoá theo gói: AnhTheSettings, ManAnhThe, AiSettings, ManPhotoboothAi, và DangNhap (đăng nhập, không test vì đang đăng nhập). Đã xem thêm: hộp thoại Tạo sự kiện mới (5 bước: tên + loại, ảnh bìa, frame, 300/600 dpi, giới hạn lượt in), Sửa ảnh đại diện, trang Xem lại ảnh (xoá từng ảnh, mở thư mục), trang Chọn sự kiện, cài đặt PIN quản trị / PIN doanh thu / Tên booth / Yêu cầu mật khẩu khi thu nhỏ, và web event.9698media.com ("Tạo sự kiện & khung ảnh", cổng web đồng bộ với app, cần đăng nhập, chưa test).

Không có file hướng dẫn chính thức; đã lập huong-dan-su-dung.md.

3.4 Web quản lý event.9698media.com ("9698 Event — Tạo sự kiện & khung ảnh")

Web dạng SPA mobile-first (thanh dưới 4 tab, nút tròn "+"), đã đăng nhập bằng [email tài khoản]. Kiểm tra bằng thao tác xem và mở form; không lưu dữ liệu nào (thử bấm Lưu gói chụp thì hệ thống chặn thao tác ghi lên dữ liệu dùng chung, tôi không làm cách khác để vượt qua).

Test ghi dữ liệu (được bạn cho phép, đã dọn sạch):

Còn lại chưa test: nút "+ Tạo sự kiện" gắn đơn, upload khung, tạo/xuất voucher trên web, "Đặt tên" máy, "+ Thêm mẫu" ảnh AI.

Hai màn bổ sung chỉ hiện ở menu bản desktop (bản mobile không có nút, truy cập qua /may và /prompt):

• Danh sách máy (/may): liệt kê máy đã đăng nhập (Máy 1 · mã XXXX-XXXX-XXXX · [tên máy]), nút Đặt tên để đặt tên dễ nhớ; tên hiện ở chỗ chọn máy khi tạo sự kiện.
• Mẫu Ảnh AI (/prompt, 22 mẫu): thư viện prompt cho Photobooth AI (vd "Báo Phú Quốc", "Võ Thuật Cute", "áo dài truyền thống Việt Nam"); mẫu chung của 9698 chỉ admin sửa/xoá; "+ Thêm mẫu" để thêm mẫu riêng. Tương ứng /api/prompt của app (đã tải "22 mẫu AI" khi đồng bộ).

API của web (cùng Bearer/cookie đăng nhập): POST /api/dang-nhap, GET /api/me, /api/may, /api/su-kien, /api/anh-khung?key=, /api/dat-lich?thang=&tim=, /api/goi-chup, /api/voucher; POST /cdn-cgi/rum là đo hiệu năng của Cloudflare. Web và app dùng chung backend event.9698media.com (mục 4.2).

3.5 Màn hình và link chưa vào được / chưa kiểm tra (rà soát lần 3)

4. API gọi lên server

Ba host chính, đều HTTPS, Bearer token (Authorization: Bearer <the>), JSON; helper goi() timeout 12 s mặc định, trả về {ma: httpStatus, ...body}.

4.1 tk.9698media.com — tài khoản, giấy phép, in từ xa (qua Cloudflare)

Giấy phép là chuỗi đã ký, app kiểm tra bằng crypto.subtle.verify với khoá công khai (nên chạy offline được trong thời hạn); mã máy (maMay) sinh theo phần cứng (dạng XXXX-XXXX-XXXX).

4.2 event.9698media.com — web sự kiện, đồng bộ đa máy

4.3 Dịch vụ khác

• anh.9698media.com (trỏ vào R2 qua Cloudflare): /f/<mã>/anh.jpg, /goc.jpg, video; /e/<eventId> là album cả tiệc; trang khách dò ảnh bằng HEAD + ?v=<timestamp> để né cache 404 của Cloudflare (3 phút).
• anh.9698.vn: tên miền ngắn cho QR.
• my.sepay.vn/userapi/transactions/list: SePay, app tự đối soát chuyển khoản theo token của khách.
• api.openai.com/v1: sinh ảnh AI bằng key của khách (mô hình gpt-image-2).
• app.9698media.com/app/: kênh cập nhật.
• Cục bộ 127.0.0.1:<cổng>: HTTP nội bộ phục vụ /khung-nho/…, /anh-uom/… cho renderer.

5. Kiến trúc để triển khai app tương tự

┌──────────────── Máy booth (Electron) ───────────────┐
│ Renderer (React): Admin / Kiosk / Designer          │
│   │ contextBridge (preload) — 192 kênh IPC          │
│ Main: config, license, sync, upload queue, in ấn,   │
│       Canon SDK, SePay poll, OpenAI, local HTTP     │
│ Lưu: JSON + file ảnh + upload-queue.json            │
└───────┬───────────────┬────────────────┬────────────┘
        │               │                │
   tk.* (Auth/License   event.* (Sync    anh.* (R2 CDN)
   /Billing/Print)      sự kiện, voucher)   ▲
        │               │                │
        └── Cloudflare Workers + D1/KV ──── R2 ◄── trang khách (/e/…, /f/…)

Nguyên tắc thiết kế nên giữ:

1. Offline-first: mọi thứ chạy từ dữ liệu cục bộ; server chỉ để tài khoản, giấy phép, đồng bộ, chia sẻ ảnh. Giấy phép ký bất đối xứng (Ed25519/ECDSA), máy tự xác minh, có hạn dùng thử.

2. Hàng đợi upload bền vững (upload-queue.json: jobs, sessions, albums, mã ảnh) với retry; ảnh đẩy lên qua /api/tai-anh vào R2, khách xem bằng mã ngắn (QR).

3. Đồng bộ theo mốc thời gian (tu=<ts>): kéo và đẩy delta, server trả số mới/cập nhật; ảnh khung đồng bộ riêng, hỏi "ảnh thiếu" trước khi đẩy.

4. Tách host theo vai trò (tài khoản/giấy phép, sự kiện, ảnh) để mở rộng và cache độc lập.

5. Tích hợp bên thứ ba bằng key của khách (OpenAI, SePay) để không gánh chi phí.

6. Smartbooth: máy booth poll /api/in/hang-doi, khách chụp bằng điện thoại và tải ảnh lên, booth tải về và in, báo /api/in/xong.

Stack đề xuất để dựng lại: Electron + electron-vite + React; backend Cloudflare Workers + D1 (tài khoản, đơn, sự kiện) + R2 (ảnh) + KV (voucher, hàng đợi in); thanh toán chuyển khoản VietQR + webhook/poll SePay; cập nhật bằng electron-updater trỏ vào thư mục tĩnh.

6. Việc chưa xác nhận

• Chưa bắt traffic thật (proxy/Fiddler); danh sách endpoint lấy từ mã nguồn bundle nên có thể thiếu endpoint gọi động.
• Chưa test chụp/in/thanh toán/voucher/Smartbooth/Canon do thiếu khung, thiết bị và gói mua.
• Schema chi tiết của request/response chưa đọc hết.