Fotokio — Sổ tay KTV vận hành

Kiosk in ảnh tự phục vụ: khách quét QR trên kiosk, chọn khung và chỉnh ảnh trên điện thoại, bấm Print thì kiosk in ngay một bản; muốn thêm bản thì chạm ảnh của mình ở kiosk. Tài liệu này chỉ cho KTV tại sự kiện: setup, vận hành, theo dõi để xử lý sớm, sự cố.

Bản 1.2: không còn mã in 4 số, kiosk không còn bước chạm khung. Ảnh minh họa dưới đây chụp trước 1.2 nên màn kiosk và điện thoại có thể khác chi tiết; sẽ chụp lại sau khi bản 1.2 lên demo. Lời văn bên cạnh là đúng.

1. Việc của KTV và thứ cần có

Kiosk — PC Windows màn cảm ứng, Chrome kiosk mode. Luôn hiện màn chính với QR cỡ lớn; khách quét QR, không phải chạm gì. Cũng là nơi khách chạm ảnh để in thêm.

Điện thoại khách — trang s.fotokio.com, không cài app. Mở bằng QR hoặc gõ mã 3 ký tự; chọn khung, chỉnh ảnh, Tải về, Print.

Print-agent — chạy ngầm trên PC kiosk, nhận lệnh in, in ra máy in, báo máy in và giấy mỗi 60 giây.

Console — app.fotokio.com (mở được trên điện thoại). Sự kiện, khung ảnh, màn hình kiosk và trang chào điện thoại, kiosk, báo cáo, sức khỏe.

Môi trường thử (demo) có tiền tố demo-; dùng để tập, không tính vào báo cáo sự kiện thật.

Thứ cần có	Lấy ở đâu
Tài khoản Console	Đăng nhập bằng nút "Đăng nhập Google" với đúng email được cấp. Báo "Email này chưa được cấp quyền": liên hệ Owner để cấp email.
PIN cá nhân (4–8 số)	Tự đặt ở Console → Tài khoản của tôi (mục 2.1). Chưa đặt PIN thì không được gán kiosk.
Điện thoại đăng nhập sẵn Console	Để quét QR mở khóa nhân viên tại kiosk (mục 4.1).
Mã kiosk (ví dụ K001)	Tự tạo ở Console → Kiosk. Khóa kiosk không bao giờ hiện cho người; chỉ có mã cài đặt một lần.
Gói print-agent	GitHub Actions → lần chạy CI gần nhất trên `main` → artifact `print-agent-<sha>`. Chưa có thì liên hệ Owner.
Việc KTV tự làm được	Tạo sự kiện, chọn Client, khung ảnh, 4 màn hình kiosk, tạo kiosk, mã cài đặt, máy in, PIN cá nhân.
Việc phải liên hệ Owner	Cấp email, "Xoay khóa" kiosk, hạn mức dịch vụ, gán sự kiện cho người khác.

2. Setup

2.1 Tài khoản và PIN cá nhân

Mở app.fotokio.com → Đăng nhập Google bằng email được cấp.
Menu Tài khoản → nhập PIN 4–8 chữ số → Lưu PIN. PIN chỉ của bạn, không chia sẻ.
Quên PIN: đặt PIN mới ở cùng chỗ.
Nhập sai PIN 5 lần liên tiếp tại một kiosk thì riêng bạn bị khóa ở kiosk đó 2 phút (lần sau gấp đôi, tối đa 15 phút). KTV khác vẫn dùng bình thường.

2.2 Tạo sự kiện và chọn Client

Console → Sự kiện → tạo sự kiện: tên, giờ bắt đầu / kết thúc, trạng thái live.
Chọn Client đặt dịch vụ trong ô Client của sự kiện, rồi Lưu. Không thấy Client cần chọn: liên hệ Owner.
Ô Số bản tối đa mỗi ảnh (mặc định 2): gồm cả bản kiosk tự in khi khách bấm Print, nên 2 nghĩa là khách in thêm được 1 bản. Đặt 1 để tắt in thêm tại kiosk (chỉ còn bản tự động). Áp cho mọi kiosk của sự kiện; đổi xong kiosk và điện thoại cập nhật trong 30 giây.
Tab Kiosk của sự kiện: gán đúng mã kiosk sẽ dùng.

**Tổng quan sự kiện.** KPI và thẻ "Kiểm tra trước sự kiện".

2.3 Khung ảnh

Mỗi khung có nền PNG và các ô ảnh. Mở từng khung trong trình sửa.
Không còn cảnh báo, rồi bấm Lưu.
Thử khung với ảnh thật trước khi chốt.

2.4 Bốn màn hình: màn chính, trang chào điện thoại, hàng chờ, hoàn thành

Tùy biến theo sự kiện ở Console: màn chính kiosk (QR cỡ lớn + câu chào, nền, logo, màu), trang chào trên điện thoại (ảnh nền, logo, màu, tên chương trình; có nút Bắt đầu), hàng chờ và hoàn thành. Xem trước cả kiosk và điện thoại bên phải. Nhớ bấm Lưu: kiosk chỉ nhận thay đổi sau khi lưu (cập nhật trong 30 giây), điện thoại thấy ở phiên mới.

Hiện "Tương phản thấp" ở ô màu nhấn: đổi màu khác, nếu không nút trên kiosk khó thấy.

2.5 Tạo kiosk và mã cài đặt

Console → Kiosk → tạo kiosk (mã K001, K002...). Chọn máy in, khổ giấy 4x6, thời gian chờ (mặc định 3 phút). In tự động luôn bật; số bản cho mỗi ảnh đặt theo sự kiện (mục 2.2), không đặt ở kiosk.
Bấm Tạo mã cài đặt: mã 8 ký tự, dùng một lần, hết hạn sau 15 phút. Tạo ngay trước khi cài, đừng tạo từ hôm trước.
Gán kiosk vào sự kiện ở tab Kiosk của sự kiện.

Quản trị kiosk — **Console → Kiosk.** Khóa kiosk không hiện ở đây.

**Tab Kiosk của sự kiện.** Cột trạng thái: kiosk, print-agent, máy in, giấy.

2.6 Cài PC kiosk bằng install.ps1

Cài Node.js 22 trở lên và driver máy in (DNP / Canon). In thử một trang từ Windows.
Giải nén gói print-agent (có dist\, scripts\, node_modules\).
Tạo mã cài đặt mới (mục 2.5).
Mở PowerShell quyền Administrator trong thư mục gói và chạy:

powershell -ExecutionPolicy Bypass -File install.ps1 -KioskCode K001 -Env prod -AgentDir .\print-agent -PrinterName "DS-RX1"

Script hỏi mã cài đặt (hoặc thêm -InstallCode <mã>), tự ghi khóa vào print-agent.env, cài print-agent vào C:\Fotokio\print-agent, tạo tác vụ "Fotokio Print Agent", đặt Chrome kiosk tự mở, tắt ngủ / tắt màn hình. Bạn không bao giờ thấy hay dán khóa kiosk.

Báo lỗi	Làm
"Ma da dung hoac het han"	Mã đã dùng hoặc quá 15 phút. Tạo mã mới.
"Sai ma kiosk"	Sai `-KioskCode`, sai `-Env` (`demo` / `prod`) hoặc gõ sai mã cài đặt.

Thứ tự: chạy script trước, mở trang kiosk sau. Chrome kiosk tự lấy mã và khóa từ print-agent trên cùng máy trong cửa sổ ghép khóa 10 phút đầu sau khi agent chạy, chỉ một lần. Quá 10 phút: khởi động lại tác vụ "Fotokio Print Agent" rồi mở lại trang. Không nhập mã cài đặt khác ở màn "Cài đặt kiosk" sau khi script đã đổi mã: mỗi lần đổi mã cấp khóa mới và print-agent mất khóa.

Khởi động lại PC (hoặc đăng xuất / đăng nhập). Chrome tự vào màn chào.
Nếu hiện màn Cài đặt kiosk: nhập mã kiosk và một mã cài đặt mới, bấm Cài đặt.

**Cài đặt kiosk** (chỉ khi không tự lấy được khóa).

Vào được màn chính (QR cỡ lớn và câu chào) là kiosk đã kết nối đúng. Quét thử bằng điện thoại để chắc.

2.7 Máy in

Tên máy in trong -PrinterName đúng như Windows → Printers. Không thấy máy in thì script cảnh báo và bật máy in ảo (ảnh ra file ở C:\Fotokio\prints): chỉ để thử, không in thật.
Đủ giấy và ribbon, khổ 4x6, không kẹt, cáp USB chắc.
PRINT_DRY_RUN=0 trong print-agent.env khi in thật.
In thử một vòng đầy đủ (mục 5.1) trước giờ mở.

3. Vận hành

3.1 Luồng khách 8 bước (dưới 3 phút, không cần KTV)

Kiosk: màn chính. Luôn hiện QR cỡ lớn, mã 3 ký tự dự phòng và câu chào. Không có bước chạm.
Khách A quét QR. Điện thoại vừa mở link là kiosk đổi sang QR mới cho khách kế tiếp (dưới 1 giây). Không ai quét thì sau 2 phút QR tự đổi. QR và mã chỉ dùng một lần.
Điện thoại: trang chào theo bộ nhận diện sự kiện, nút Bắt đầu. Không bấm Bắt đầu trong 2 phút thì phiên hủy, khách quét lại QR.
Chọn khung (lưới khung của sự kiện; sự kiện chỉ có một khung thì bỏ qua bước này) → chạm từng ô chọn ảnh → xoay, phóng, kéo căn.
Xong (bật khi đủ ảnh) → điện thoại hiện thành phẩm với Tải về (file đúng độ phân giải in) và Print. Chưa Print thì vẫn chỉnh lại được.
Print → kiosk tự in một bản (xếp hàng nếu máy đang in), kiosk hiện "Đang in ảnh của bạn". Nút Print khóa, điện thoại hiện "Cần thêm bản? Đến kiosk chạm ảnh của bạn".
In thêm: khách mở hàng chờ trên kiosk (chỉ ảnh đã Print, mới nhất trước), chạm ảnh mình → "Đây là ảnh của bạn?" → In. Không cần mã hay xác thực. Mỗi ảnh tối đa N bản (mục 2.2); hết thì kiosk hiện "Nhờ nhân viên".
Hoàn thành 10 giây rồi về màn chính; hàng chờ 3 phút không chạm cũng về màn chính.

Khung trống — **Điện thoại: khung với ô trống.** Chạm ô, chọn ảnh. (Ảnh chụp trước 1.2.)

Chỉnh ảnh — **Chỉnh trong ô:** xoay, phóng, kéo căn.

Hàng chờ — **Kiosk: hàng chờ.** Ảnh hiện trong 1 giây sau khi khách bấm Print.

**Đang in → Hoàn thành.** Về màn chính sau 10 giây.

3.2 Việc của KTV trong giờ chạy

Đứng gần kiosk 15 phút đầu, chỉ khách quét QR và Bắt đầu trên điện thoại; nhắc khách "Print" sẽ tự in một bản.
Theo dõi giấy / ribbon; đổi khi máy in báo.
Mở Console trên điện thoại: tab Kiosk, Tổng quan, Sức khỏe (mục 5).
Không tắt Chrome, không tắt PC. Cần thao tác Windows thì thoát kiosk bằng PIN (mục 6.10).
Khách cần giúp: mục 4.

4. Hỗ trợ khách

Khách nói	KTV làm
"Không quét được QR"	Bảo khách mở `s.fotokio.com` và gõ mã 3 ký tự dưới QR (không phân biệt hoa thường). Mã chỉ dùng `3479ACDEFHJKMNPQRTWXY`; cùng vòng đời với QR đang hiện. Gõ sai nhiều lần liên tục trên cả sự kiện thì tạm chỉ nhận QR.
"QR đổi mất rồi" / "Mã này đã được dùng"	QR và mã chỉ dùng một lần và đổi ngay khi có người quét hoặc sau 2 phút. Bảo khách quét QR đang hiện trên kiosk. Ảnh chụp QR gửi cho người khác không vào được.
"Chưa bấm Bắt đầu kịp, giờ báo hủy"	Quá 2 phút không bấm Bắt đầu thì phiên hủy. Bảo khách quét lại QR trên kiosk, không mất gì.
"Nút Xong bị mờ"	Còn ô bắt buộc chưa có ảnh. Dòng "Còn N ô chưa có ảnh" ngay trên nút. Chạm ô trống thêm ảnh.
"Muốn lưu ảnh về máy"	Bấm Tải về ở màn thành phẩm, dùng được cả trước và sau Print (trong 30 ngày). Không tải được thì bấm lại để lấy link mới.
"Print rồi mà chưa ra ảnh"	Nhìn màn kiosk: có "Đang in ảnh của bạn" là đang xếp hàng. Nếu kiosk mất mạng hoặc print-agent tắt, lệnh được giữ tối đa 15 phút rồi in khi kiosk nối lại; quá 15 phút lệnh hết hạn, điện thoại báo "Đến kiosk nhờ nhân viên in". KTV: Nhân viên → in lại (mục 4.1). Máy in lỗi: mục 6.3.
"Muốn in thêm"	Khách mở hàng chờ trên kiosk, chạm ảnh mình → In. Mỗi ảnh tối đa N bản (gồm bản tự in). Hết lượt thì kiosk báo "Nhờ nhân viên": KTV in qua Nhân viên (không giới hạn).
"Không thấy ảnh mình trong hàng chờ"	Hàng chờ chỉ có ảnh đã Print. Ảnh mới Xong mà chưa Print thì chưa hiện: bảo khách bấm Print trên điện thoại. Xem thêm mục 6.6.
"Muốn sửa ảnh sau khi Print"	Chưa Print: bấm Chỉnh lại. Đã Print: không chỉnh được; làm phiên mới (quét QR lại). Ảnh cũ vẫn Tải về được.
"Link báo phiên hết hạn"	Phiên chỉ sống trong trình duyệt đã quét QR. Đổi trình duyệt / điện thoại thì quét QR mới trên kiosk.
"Có người in nhầm ảnh của tôi"	Chạm ảnh trong hàng chờ không cần xác thực nên có thể in nhầm. KTV mở khóa Nhân viên và xóa ảnh khỏi hàng chờ nếu cần. Sự kiện hay bị: đặt N = 1 ở Console (mục 2.2) để tắt in thêm tại kiosk. Lệnh in của khách ghi trong nhật ký kèm mã kiosk.

Ô thiếu — **Nút mờ** vì còn ô thiếu ảnh.

Nhân viên chọn số bản — **Nhân viên → số bản → In.**

4.1 Nhân viên mở khóa: QR Google hoặc PIN cá nhân

Chạm ảnh trong hàng chờ → Nhân viên → chọn một cách:

Cách	Làm	Ghi chú
Mở khóa bằng QR	Quét QR trên kiosk (sống 2 phút) bằng điện thoại đã đăng nhập Console → xác nhận trên điện thoại.	Cần mạng. Kiosk vào chế độ nhân viên 10 phút và hiện email của bạn; trong 10 phút in không giới hạn số bản, in lại, xóa ảnh khỏi hàng chờ mà không phải nhập thêm.
Dùng PIN	Chọn tên mình trong danh sách → nhập PIN cá nhân → Xác nhận.	Làm được cả khi mất mạng. Danh sách chỉ có người được gán kiosk này.

Mọi lần in của nhân viên ghi email người làm và số bản vào nhật ký, lịch sử in, báo cáo Excel. Không thấy tên mình trong danh sách PIN: kiosk chưa tải cấu hình, thử "Tải lại cấu hình" (mục 6.10) hoặc liên hệ Owner.

5. Theo dõi tình trạng để xử lý sớm

Mục tiêu: thấy dấu hiệu trước khi khách thấy. Làm theo thứ tự: kiểm tra trước sự kiện, biết các dấu hiệu sớm, kiểm tra định kỳ.

5.1 Checklist trước sự kiện

Console → sự kiện → Tổng quan → Kiểm tra ngay. Hệ thống tự chạy 24 giờ và 2 giờ trước giờ mở; mục đỏ báo qua Telegram. Kết quả hiện "Đạt hết" hoặc "N mục chưa đạt" kèm ✓ / ✗ từng mục. Chạy tay lại sau khi sửa.

Mục	Nghĩa là	Khi ✗ làm gì
Kiosk <mã> trực tuyến	Kiosk gửi nhịp tim trong 2 phút gần nhất	Kiểm tra PC bật, Chrome kiosk mở, mạng. Mục 6.2.
Print-agent <mã> trực tuyến	Print-agent trên PC báo nhịp tim (60 giây một lần)	Khởi động tác vụ "Fotokio Print Agent". Mục 6.4.
Máy in <mã> có giấy	Máy in báo còn giấy / ribbon	Nạp giấy, gỡ kẹt, bật máy in; đợi 60 giây rồi chạy lại.
Render thử "<tên khung>"	Hệ thống dựng thử một ảnh thành phẩm từ từng khung của sự kiện	Mở khung trong trình sửa, sửa cảnh báo, Lưu. Còn ✗: liên hệ Owner.
Hạn mức đủ cho sự kiện	Dịch vụ miễn phí còn đủ cho sự kiện	Liên hệ Owner ngay.
Cơ sở dữ liệu (Supabase thức)	Truy cập được cơ sở dữ liệu	Chạy lại sau 1 phút; vẫn ✗ thì liên hệ Owner.
Lưu trữ ảnh R2 đã cấu hình	Truy cập được kho ảnh	Chạy lại sau 1 phút; vẫn ✗ thì liên hệ Owner.
Có kiosk được gán	Sự kiện có ít nhất một kiosk	Tab Kiosk → gán kiosk theo mã (mục 2.5).
Có template	Sự kiện có ít nhất một khung ảnh	Tab Khung ảnh → tạo hoặc sao chép khung (mục 2.3).

Ngoài Kiểm tra ngay, chạy thử trọn một vòng bằng điện thoại của bạn: quét QR trên kiosk, Bắt đầu, chọn khung, đủ ảnh các ô, Xong, Tải về, Print (kiosk tự in một bản), rồi chạm ảnh trong hàng chờ để in thêm một bản. Cuối cùng thử PIN cá nhân một lần ở Nhân viên.

Kiểm tra ngay: mọi mục ✓
Giấy và ribbon đủ cho cả sự kiện, có cuộn dự phòng
Một vòng thử khách chạy được (Print ra 1 bản, in thêm được), ảnh in đúng khổ, không viền trắng lạ
Số bản tối đa mỗi ảnh (N) đúng ý khách hàng
PIN cá nhân thử được tại kiosk
Kiosk về màn chính, QR quét được từ 1,5 m, lau màn hình, cất bàn phím / chuột

5.2 Dấu hiệu sớm → ý nghĩa → việc làm ngay

Nơi xem	Dấu hiệu sớm	Ý nghĩa	Làm ngay
Console → sự kiện → tab Kiosk	Kiosk offline	Mất 2 nhịp tim (hơn 2 phút không báo). PC tắt, Chrome đóng hoặc mất mạng.	Nhờ người tại site nhìn màn kiosk. Mục 6.2.
Tab Kiosk	Print-agent offline	Khách bấm In sẽ lỗi.	Mục 6.4, làm ngay khi chưa có khách xếp hàng.
Tab Kiosk	Giấy báo không OK (hoặc hiện trạng thái máy in)	Sắp hoặc đã hết giấy / ribbon / kẹt.	Nạp giấy, gỡ kẹt trước khi khách bấm In. Mục 6.3.
Tab Kiosk / trang Sức khỏe	"Lần cuối" (heartbeat) cũ hơn 60 giây	Nhịp tim gửi 60 giây một lần; quá 2 nhịp là mất kết nối.	Làm mới trang; nếu vẫn cũ thì xử lý như offline.
Console → Sức khỏe, thanh hạn mức	Vàng (60–85%) / đỏ (trên 85%, kèm ngày dự báo hết)	Dịch vụ miễn phí sắp hết.	Báo Owner. Vẫn vận hành bình thường.
Trang Sức khỏe	Dải "giảm tải" (mức 1 hoặc 2)	Hệ thống tạm tắt thumbnail thư viện (mức 1), thêm xuất báo cáo và in lại từ xa (mức 2). Upload, render, in vẫn chạy.	Báo Owner; hoãn việc xuất báo cáo / in lại từ xa.
Trang Sức khỏe	Cảnh báo đang mở (vàng / đỏ, kèm dòng hành động "→")	Hệ thống phát hiện sự cố.	Đọc dòng hành động và làm theo; báo Owner đóng cảnh báo.
Trên kiosk	Dải đỏ "Mất kết nối mạng"	PC mất mạng hoặc API không tới.	Mục 6.2.
Trên kiosk	Cảnh báo "Máy in lỗi N lần liên tiếp" (từ lần thứ 2)	Máy in hoặc print-agent đang hỏng.	Mục 6.3.
Điện thoại / Telegram	Tin cảnh báo (nhãn `demo` / `prod`, mức vàng / đỏ, một dòng hành động)	Hệ thống tự báo: kiểm tra trước sự kiện, in thất bại 2 lần, render quá 10 giây, lỗi upload, trễ kết nối.	Làm theo dòng hành động. Chưa nhận được Telegram thì hỏi Owner.
PC kiosk: `http://127.0.0.1:17877/status`	Không mở được, hoặc `paperOk` là `false`	Không mở được: print-agent không chạy. `paperOk:false`: máy in báo hết giấy / lỗi.	Mục 6.4 hoặc 6.3.
PC kiosk: `C:\Fotokio\print-log.jsonl`	Nhiều dòng `ok:false`, hoặc có `offline:true`	Mỗi dòng một lệnh in. `ok:false` là in lỗi; `offline:true` là in lúc mất mạng.	Đối chiếu giờ, tìm nguyên nhân (giấy, mạng). Dùng đối chiếu số bản với báo cáo.

**Trang Sức khỏe.** Hạn mức, kiosk, cảnh báo.

Dải mất mạng — **Dải "Mất kết nối mạng"** trên kiosk.

5.3 Kiểm tra định kỳ trong sự kiện (mỗi 30–60 phút)

Giấy: nhìn máy in thật; ước lượng số tờ còn so với số khách đang xếp hàng. Mỗi khách Print tốn ít nhất 1 tờ, tối đa N tờ.
Hàng chờ: kiosk có hiện ảnh vừa Print không; ảnh nằm lâu không ai in thêm là bình thường.
Số bản in khớp: số bản trong Tổng quan (Console) ≈ số tờ đã ra khỏi máy in ≈ số dòng ok:true trong print-log.jsonl. Lệch nhiều thì kiểm tra giấy kẹt hoặc in lỗi.
Tab Kiosk: kiosk và print-agent đều online, "lần cuối" dưới 2 phút.
Sức khỏe: có cảnh báo mới đang mở không (kể cả cảnh báo "nhiều lệnh in của khách" nếu có người in liên tục), thanh hạn mức có đổi màu không.
Kiosk không báo lỗi lạ, màn hình không tối.

6. Xử lý sự cố

Thứ tự ưu tiên: 1) khách vẫn in được (chuyển sang in qua Nhân viên nếu cần); 2) tìm đúng thông báo trên màn hình; 3) làm theo mục dưới; 4) quá 5 phút chưa hết thì giữ khách in qua Nhân viên và báo Owner kèm ảnh chụp màn hình, mã kiosk, giờ xảy ra.

Triệu chứng	Mục
Màn "Cài đặt kiosk" / "Khóa kiosk đã được thay"	6.1
Mất kết nối mạng	6.2
Máy in lỗi	6.3
Print-agent offline	6.4
Đã in đủ N bản / "Nhờ nhân viên"	6.5
Khách Print mà kiosk không thấy ảnh	6.6
Đổi màn hình mà kiosk không đổi	6.7
Kiosk tự về màn chính	6.8
Khách thấy "Mã này đã được dùng" / "quét lại QR" / "Phiên hết hạn" / "Đến kiosk nhờ nhân viên"	6.9
Thoát kiosk thao tác Windows	6.10
Sức khỏe vàng / đỏ	6.11
Gọi Owner	6.12

Kiosk 6.1 Hiện "Cài đặt kiosk", "Sai mã kiosk hoặc mã cài đặt" hoặc "Khóa kiosk đã được thay"

Dấu hiệu: thay vì màn chào, kiosk hỏi mã kiosk và mã cài đặt.

Xử lý: Console → Kiosk → Tạo mã cài đặt. Nếu print-agent cũng báo mất khóa (6.4): chạy lại install.ps1 -KioskCode ... -InstallCode <mã> rồi mở lại trang kiosk. Chỉ khi print-agent không chạy mới nhập mã ở màn "Cài đặt kiosk". Mỗi mã dùng một lần, đừng dùng hai mã cho một lần cài. "Mã đã dùng hoặc hết hạn": tạo mã mới. "Sai mã": kiểm tra mã kiosk trong URL. "Khóa kiosk đã được thay" (khóa bị đổi khi PC đang tắt): xử lý như trên.

Kiosk 6.2 Dải đỏ "Mất kết nối mạng"

Dấu hiệu: dải trên cùng; màn chính báo tạm không nhận khách mới (không tạo được QR mới); ảnh trong hàng chờ đã tải vẫn hiện.

Xử lý: (1) Cắm lại dây / Wi-Fi của PC. (2) Trong lúc mất mạng khách vẫn in thêm được ảnh đã tải trong hàng chờ, trong giới hạn N (kiosk đếm tại máy, nên nếu nhiều kiosk của một sự kiện cùng mất mạng có thể vượt N một chút). KTV in qua: chạm ảnh → Nhân viên → Dùng PIN → chọn tên, nhập PIN cá nhân → In; print-agent in từ ảnh đã tải sẵn và tự gửi số lần in lên hệ thống khi có mạng lại. (3) Khách bấm Print trên điện thoại lúc kiosk mất mạng: điện thoại báo "kiosk đang mất mạng, sẽ in khi nối lại"; lệnh được giữ tối đa 15 phút, quá thì hết hạn và khách phải nhờ nhân viên. (4) Ảnh báo "chưa được tải về máy kiosk" là ảnh Print sau khi mất mạng: phải có mạng mới in được. (5) Có mạng lại, dải tự ẩn, QR mới tự hiện, không cần tải lại. Mở khóa bằng QR không dùng được khi mất mạng. Báo "Kiosk chưa có PIN dự phòng khi mất mạng": chỉ còn cách khôi phục mạng.

Kiosk 6.3 "Máy in chưa phản hồi" / "Máy in báo lỗi" / "Máy in lỗi N lần liên tiếp"

Dấu hiệu: bản in tự động hoặc nút In thêm báo lỗi "nhờ nhân viên"; sau 2 lần lỗi liên tiếp kiosk hiện dải cảnh báo (chạm để ẩn).

Nguyên nhân theo thứ tự: hết giấy / ribbon, kẹt giấy, máy in tắt hoặc tuột USB, driver treo, print-agent không chạy (6.4), mạng.

Xử lý: (1) Nhìn đèn / màn máy in, nạp giấy, gỡ kẹt, bật lại. (2) Tab Kiosk xem cột máy in / giấy (cập nhật 60 giây). (3) Chạm ảnh → Nhân viên → In lại; lệnh lỗi không tính vào báo cáo. (4) Vẫn lỗi: Windows → Printers, xóa hàng đợi in, in thử một trang. (5) Driver treo: khởi động lại PC; kiosk và print-agent tự mở lại. Lệnh Print của khách đang treo được gửi lại trong 15 phút, không in trùng; quá 15 phút lệnh hết hạn (không tính vào số bản của ảnh) và khách phải nhờ nhân viên in lại.

Print-agent 6.4 Print-agent offline, hoặc kiosk in lỗi dù máy in bình thường

Dấu hiệu: tab Kiosk không thấy nhịp tim agent; Kiểm tra ngay ✗ print-agent.

Xử lý trên PC kiosk (thoát kiosk, mục 6.10):

Task Scheduler → tác vụ Fotokio Print Agent: không chạy thì chuột phải → Run.
Mở http://127.0.0.1:17877/status: phải ra JSON có tên máy in và paperOk.
Xem C:\Fotokio\print-agent\print-agent.env (quyền Administrator): API_BASE_URL đúng môi trường, KIOSK_CODE đúng, KIOSK_SECRET không trống (không sửa tay), PRINTER_NAME đúng, PRINT_DRY_RUN=0.
Chạy tay xem lỗi: trong C:\Fotokio\print-agent chạy node --env-file=print-agent.env dist\index.js. "Đã kết nối API" là tốt; "mất kết nối API, đang thử lại" là mạng; "khóa kiosk không còn hợp lệ ... chạy lại install.ps1 với mã cài đặt mới" là phải cài lại bằng mã mới (6.1).
Nhật ký in: C:\Fotokio\print-log.jsonl.
Chrome kiosk hiện "Cài đặt kiosk" dù agent chạy: quá cửa sổ ghép khóa 10 phút. Khởi động lại tác vụ agent rồi mở lại trang, hoặc nhập mã cài đặt mới.

Kiosk 6.5 "Đã in đủ N bản", "Nhờ nhân viên"

Mỗi ảnh in tối đa N bản (mặc định 2), tính cả bản kiosk tự in khi Print. Đủ N thì ảnh trong hàng chờ mờ đi và kiosk báo nhờ nhân viên. Lệnh in lỗi hoặc hết hạn không chiếm suất. Hai người cùng bấm In thêm một lúc ở lượt cuối: chỉ một người được in, người kia nhận thông báo hết lượt.

Xử lý: KTV mở khóa Nhân viên (mục 4.1), chạm ảnh, chọn số bản, In: không giới hạn. Muốn khách tự in nhiều bản hơn: tăng "Số bản tối đa mỗi ảnh" của sự kiện ở Console (mục 2.2), kiosk cập nhật trong 30 giây.

Kiosk 6.6 Khách đã bấm Print nhưng ảnh không hiện trong hàng chờ

Kiểm tra: (1) Hàng chờ chỉ có ảnh đã Print. Khách mới Xong mà chưa bấm Print thì chưa hiện: bảo khách bấm Print (khi đó kiosk cũng tự in một bản). (2) Điện thoại khách có báo "Đang in tại kiosk" chưa? Chưa thì Print chưa thành công, bảo khách bấm lại (bấm hai lần chỉ ra một bản). (3) Có dải mất mạng không (6.2). (4) Hàng chờ là của cả sự kiện nên in được ở kiosk nào của sự kiện đó; khác sự kiện thì không. (5) Ảnh có thể đã bị nhân viên xóa khỏi hàng chờ. (6) Giữ góc trên trái 3 giây → PIN cá nhân → Tải lại cấu hình.

Kiosk 6.7 Đổi màn hình / khung trên Console nhưng kiosk không đổi

Bình thường cập nhật trong 30 giây. Không đổi: kiểm tra đã bấm Lưu, đúng sự kiện, kiosk không mất mạng (6.2); rồi Tải lại cấu hình (6.10).

Kiosk 6.8 Kiosk tự về màn chính giữa chừng

Màn hoàn thành tự về màn chính sau 10 giây; hàng chờ 3 phút không chạm (mặc định, KTV chỉnh trong cấu hình kiosk) cũng về màn chính. Ảnh khách vẫn ở hàng chờ: bấm "In thêm" ở màn chính là thấy lại. QR ở màn chính không bao giờ tắt.

Điện thoại 6.9 Khách thấy "Mã này đã được dùng", "quét lại QR", "Phiên hết hạn" hoặc "Đến kiosk nhờ nhân viên in"

"Mã này đã được dùng, hãy quét QR mới trên kiosk": QR / mã 3 ký tự chỉ dùng một lần và đã đổi; quét QR đang hiện. "Hãy quét lại QR trên kiosk" (không bấm Bắt đầu trong 2 phút, phiên bị hủy) hoặc "Phiên hết hạn", hoặc mở bằng trình duyệt khác: quét QR mới. Báo "Đến kiosk nhờ nhân viên in": lệnh Print không in được trong 15 phút (kiosk mất mạng hoặc print-agent tắt), hoặc ảnh đã đủ N bản; nút Print vẫn khóa, KTV in qua Nhân viên (mục 4.1). Khách đã Print vẫn Tải về được ảnh.

Mã không đúng — Mã gõ sai hoặc hết hạn (ảnh trước 1.2).

Kiosk 6.10 Thoát kiosk thao tác Windows, tải lại cấu hình

Giữ góc trên trái 3 giây → chọn tên, nhập PIN cá nhân → bảng quản trị: Tải lại cấu hình · Gỡ cài đặt kiosk này · Đóng. Ra Windows: cắm bàn phím, bấm Alt+F4. Xong thì đăng xuất / đăng nhập lại Windows: Chrome kiosk và print-agent tự mở. Không bấm "Gỡ cài đặt kiosk này" trừ khi Owner yêu cầu (phải cài lại bằng mã mới).

Console 6.11 Trang Sức khỏe báo vàng / đỏ, hoặc dải giảm tải

Xanh dưới 60%, vàng 60–85%, đỏ trên 85%. Hệ thống tự giảm tải và báo Telegram. KTV không xử lý tại chỗ: báo Owner, tiếp tục vận hành.

Khác 6.12 Gọi Owner ngay

Cần cấp email, "Xoay khóa" kiosk, đổi hạn mức, gán người khác vào sự kiện: chỉ Owner làm.
Kiểm tra ngay ✗ ở cơ sở dữ liệu, lưu trữ, hạn mức hoặc render thử mà chạy lại không hết.
Cả sự kiện không tạo được QR dù mạng tốt: kèm giờ và mã kiosk.
Quên PIN thì tự đặt lại (mục 2.1); bị khóa thì chờ hết thời gian khóa.

7. Cuối sự kiện

Console → sự kiện → Báo cáo in: tổng bản in theo kiosk / giờ; Xuất Excel.
Đối chiếu với C:\Fotokio\print-log.jsonl nếu số bản có tranh cãi; lần in lúc mất mạng có "offline": true và đã được cộng vào báo cáo khi có mạng lại.
Thư viện ảnh: tải thành phẩm, in lại từ xa nếu khách quay lại.
Đưa kiosk về màn chào, tắt máy in trước, rồi tắt PC bình thường (không gỡ cài đặt kiosk).
Thời hạn: ảnh gốc của khách tự xóa sau 24 giờ; ảnh thành phẩm giữ 30 ngày.
Ghi lại sự cố đã gặp (giờ, mã kiosk, cách xử lý) và báo Owner.

8. Rủi ro đã chấp nhận của in thêm tại kiosk

In thêm bằng cách chạm ảnh trong hàng chờ không xác thực (không mã in), để khách không phải nhớ gì. Các rủi ro đã được chấp nhận:

Việc KTV có thể làm: xóa ảnh khỏi hàng chờ (mở khóa Nhân viên); đặt N = 1 ở Console để tắt in thêm; xem nhật ký lệnh in của khách kèm mã kiosk; để ý cảnh báo "nhiều lệnh in của khách" (hơn 10 lệnh một phút trên một kiosk) ở trang Sức khỏe. Khách chỉ in được ảnh đã Print, và kiosk luôn hỏi "Đây là ảnh của bạn?" trước khi in.