Hướng Dẫn Sử Dụng - T.I.M.E.S. System v4 (Multi-Tenant SaaS)

🏥 1. TỔNG QUAN HỆ THỐNG & KIẾN TRÚC SAAS V4

T.I.M.E.S System v4 (Treatment Intelligence Matrix & Equipment Scheduler) là phần mềm chuyên biệt xếp lịch thủ thuật Y học cổ truyền và Phục hồi chức năng thế hệ mới, vận hành 100% trên mạng lưới Cloudflare Edge (Workers + D1 Database).

⚡ Tốc Độ Phản Hồi 0ms

Kiến trúc nạp dữ liệu đệm đa tầng (Local Cache & IndexedDB Dexie) giúp mở bảng lịch, chấm công và danh mục tức thì, không độ trễ.

🔒 Cô Lập Dữ Liệu 100%

Toàn bộ hồ sơ bệnh nhân, danh mục và chấm công được gắn mã đơn vị riêng (Tenant Clamping), cam kết bảo mật y tế tuyệt đối.

🤖 Trí Tuệ Nhân Tạo & CP-SAT

Tự động giải bài toán phân bổ giờ làm thủ thuật không trùng bệnh nhân, không trùng kỹ thuật viên và không vượt công suất máy móc.

🔐 2. ĐĂNG NHẬP THEO MÃ ĐƠN VỊ & NHẬN DIỆN THƯƠNG HIỆU

Mỗi Bệnh viện, Phòng khám được cấp một Mã Đơn Vị duy nhất (ví dụ: bvtks_cs2, pk_anphuc, bv_hanoi...).

💡

Cách Đăng Nhập Chuẩn:

Nhập Mã Đơn Vị vào ô Mã Đơn Vị (mặc định đã được hệ thống ghi nhớ trên thiết bị của bạn).
Nhập Tên Đăng Nhập và Mật Khẩu được cấp.
Nhấn nút Đăng Nhập hoặc gõ phím Enter.

Dynamic White-Labeling: Sau khi đăng nhập thành công, toàn bộ tiêu đề thanh Banner 3 dòng, biểu trưng Logo và chân trang sẽ tự động chuyển thành thương hiệu của chính cơ sở y tế bạn.

⚙️ 3. KHỞI TẠO & QUẢN LÝ 5 DANH MỤC CỐT LÕI

Trước khi xếp lịch, đơn vị cần hoàn tất khai báo 5 danh mục nghiệp vụ tại menu bên trái:

Danh mục	Trường thông tin bắt buộc	Ý nghĩa nghiệp vụ xếp lịch
1. Máy Móc & Thiết Bị	Tên máy, Số lượng máy, Công suất đồng thời	Ngăn chặn việc xếp quá số máy vật lý đang có trong cùng một khung giờ.
2. Danh Mục Thủ Thuật	Mã TT, Tên TT, Thời lượng (phút), Máy móc yêu cầu, Định mức tiền	Quy định thời gian chiếm giường/máy và tính tiền thủ thuật cuối tháng.
3. Nhân Sự Y Tế	Họ tên, Vai trò (Bác sĩ/KTV), Kỹ năng thực hiện, Hệ số công	Thuật toán chỉ gán ca cho nhân sự có kỹ năng phù hợp.
4. Phòng & Giường Bệnh	Tên buồng phòng, Số giường, Nhóm chuyên môn	Phân bổ bệnh nhân vào đúng phòng chức năng điều trị.
5. Phác Đồ Lâm Sàng	Tên phác đồ mặt bệnh, Bộ danh sách thủ thuật mẫu	Tích chọn nhanh khi đón tiếp bệnh nhân mới mà không cần chọn từng thủ thuật lẻ.

📋 4. TIẾP NHẬN BỆNH NHÂN, GIỜ BẬN & GIỜ RA VIỆN

Tại tab Quản Lý Bệnh Nhân và tab Giờ Bận & Ra Viện:

Tiếp nhận bệnh nhân: Nhập Họ tên, Năm sinh, Phòng điều trị, sau đó tích chọn các thủ thuật theo chỉ định bác sĩ.
Khai báo Giờ bận bệnh nhân: Nếu bệnh nhân bận đi làm xét nghiệm, chụp X-quang, châm cứu hoặc bận việc riêng (ví dụ: 08:30 - 09:30), khai báo khung giờ này để thuật toán không xếp lịch vào khoảng thời gian đó.
Khai báo Giờ ra viện: Với các bệnh nhân chuẩn bị ra viện trong ngày (ví dụ: ra viện lúc 14:00), hệ thống sẽ ưu tiên làm thủ thuật trước 14:00 và tự động giải phóng giờ buổi chiều.

📅 5. PHÂN HỆ XẾP LỊCH TỰ ĐỘNG & LỊCH THỨ 7 CHUYÊN BIỆT

5.1 Xếp Lịch Hàng Ngày & Hàng Tuần

Nhấn nút 🚀 Xếp Lịch Tự Động tại tab Xếp Lịch. Bộ giải thuật CP-SAT và AI sẽ tính toán hàng nghìn khả năng trong vài giây để xuất ra bảng ma trận tối ưu nhất.

5.2 Phân Hệ Xếp Lịch Thứ 7 Chuyên Biệt

⭐

Đặc Điểm Phân Hệ Thứ 7: Vào Thứ 7, số lượng nhân sự trực giảm trong khi bệnh nhân vẫn cần làm thủ thuật. Phân hệ Thứ 7 tự động:

Lọc danh sách các nhân sự được tích chọn đi làm ngày Thứ 7.
Phân bổ cân đối số lượng ca và thời gian làm thủ thuật giữa các kỹ thuật viên trực.
Cân nhắc mức độ nặng nhẹ của từng loại thủ thuật để không ai bị quá tải.

🖨️ 6. KIỂM TRA LỖI LỊCH & IN ẤN CHUYÊN NGHIỆP

Tiện ích Kiểm tra lỗi trùng lịch: Bấm 🔍 Kiểm Tra Lịch để rà soát tự động 3 nguy cơ: Trùng bệnh nhân (1 BN làm 2 thủ thuật cùng lúc), Trùng nhân sự (1 KTV làm 2 BN cùng lúc), Quá công suất máy móc.
Tìm khung giờ rảnh: Nhập tên thủ thuật và tên BN, hệ thống sẽ đề xuất ngay các khoảng trống rảnh rỗi trong ngày để chèn ca phát sinh.
In Phiếu Điều Trị Hàng Ngày: Xuất phiếu khổ A4/A5 rõ nét, trình bày theo từng phòng và từng nhân sự, có sẵn chữ ký kỹ thuật viên.

💰 7. CHẤM CÔNG ĐIỆN TỬ & THỐNG KÊ TIỀN THỦ THUẬT

Tại tab Chấm Công và Thống Kê:

Bảng chấm công thời gian thực: Nhập ký hiệu công (+, P, O, V...) và hệ số công. Hệ thống tự động cam kết dữ liệu thời gian thực (Real-time Input Commit), không sợ mất khi chuyển tab.
Thống kê tiền thủ thuật tự động: Tổng hợp tổng số ca từng kỹ thuật viên thực hiện trong tháng, nhân với đơn giá thủ thuật và hệ số công để tính ra tiền thực lĩnh công bằng, minh bạch.

👥 8. QUẢN TRỊ TÀI KHOẢN NỘI BỘ CƠ SỞ

Tài khoản có quyền Admin Đơn Vị có thể truy cập tab Quản Trị:

Tạo tài khoản mới cho Bác sĩ, Kỹ thuật viên, Điều dưỡng trong khoa/phòng khám.
Phân quyền xem hoặc chỉnh sửa lịch, chỉ định quyền chấm công và duyệt thống kê.
Đổi mật khẩu người dùng nội bộ khi nhân viên quên mật khẩu.

📡 9. CHẾ ĐỘ NGOẠI TUYẾN (OFFLINE-FIRST)

Khi mạng bệnh viện chập chờn hoặc mất internet đột ngột, T.I.M.E.S v4 tự động kích hoạt Chế độ Ngoại tuyến:

⚡

Bạn vẫn có thể tiếp tục tiếp nhận bệnh nhân, chấm công và tra cứu lịch bình thường. Dữ liệu được lưu trữ an toàn trong IndexedDB của trình duyệt và sẽ tự động đồng bộ lên máy chủ Cloudflare ngay khi có kết nối mạng trở lại.

⌨️ 10. BẢNG PHÍM TẮT & MẸO VẬN HÀNH NHANH

Phím tắt / Thao tác	Tác dụng nghiệp vụ
`Enter`	Xác nhận nhanh form nhập liệu hoặc đăng nhập
`Ctrl + F5`	Tải lại trang và làm mới bộ đệm Cache để nhận phiên bản mới nhất
`Kéo thả ☰`	Thay đổi thứ tự ưu tiên của Bệnh nhân, Nhân sự, Máy móc
`Click nút 🌙/☀️`	Chuyển đổi chế độ Sáng / Tối giúp chống mỏi mắt khi trực đêm

🏢 1. TỔNG QUAN TRUNG TÂM ĐIỀU HÀNH SAAS CONTROL CENTER

Khi đăng nhập với vai trò SUPER_ADMIN, hệ thống tự động mở ra thanh điều hướng đặc quyền 🏢 Quản Lý Đơn Vị SaaS (#tab-tenants):

Giao diện quản lý tập trung toàn bộ các Cơ sở y tế, Phòng khám, Bệnh viện đang thuê bao hệ thống.
Hiển thị biểu đồ thống kê: Tổng số đơn vị, số đơn vị đang hoạt động (Active), số đơn vị sắp hết hạn, tổng số tài khoản y tế trong toàn hệ thống.
Cách ly hoàn toàn: Super Admin không can thiệp vào nghiệp vụ lâm sàng nội bộ của phòng khám nhưng có toàn quyền cấp phát, gia hạn và thu hồi giấy phép sử dụng.

🔐 2. ĐĂNG NHẬP & CƠ CHẾ BẢO MẬT MASTER KEY (SHA-256)

Tài khoản Super Admin hoạt động theo cơ chế xác thực kép độc lập với các đơn vị thường:

🛡️

Cơ Chế Bảo Mật Master Key:

Mật khẩu Super Admin được băm bằng thuật toán mật mã chuẩn SHA-256 và lưu an toàn tại bảng cai_dat với khóa superadmin_password_hash (đơn vị: MASTER).
Không lưu mật khẩu dạng bản rõ (plaintext) ở bất kỳ đâu trên Cloudflare D1 hay mã nguồn.
Để đổi mật khẩu Super Admin: Bấm vào 👤 superadmin ▾ trên góc phải màn hình → chọn 🔑 Đổi Mật Khẩu. Hệ thống sẽ băm mật khẩu mới tại trình duyệt trước khi gửi lên API Worker.

🏥 3. QUẢN LÝ ĐƠN VỊ KHÁCH HÀNG (TENANTS MANAGEMENT)

Quy trình khởi tạo và thiết lập thông số cho một Cơ sở Y tế / Phòng khám mới:

Thuộc tính	Quy cách & Ví dụ	Ghi chú quan trọng
Mã Đơn Vị (`unit_code`)	Chữ thường, không dấu: `pk_anphuc`, `bv_vietduc`	Khóa chính cách ly dữ liệu trong CSDL, không thể thay đổi sau khi tạo.
Tên Đơn Vị	Ví dụ: Phòng Khám Đa Khoa An Phúc	Hiển thị trên Banner trang chủ và tiêu đề in phiếu điều trị.
Logo Đơn Vị	URL ảnh hoặc tải file Logo trực tiếp	Tự động áp dụng nhận diện thương hiệu (White-Labeling).
Gói Thuê Bao (Tier)	`FREE`, `STANDARD`, `PRO`, `VIP`	Xác định quyền truy cập các tính năng nâng cao (AI, xuất Excel, sao lưu).

⏳ 4. BẢN QUYỀN, THỜI HẠN THUÊ BAO & HẠN MỨC (QUOTAS)

4.1 Quản Lý Thời Hạn Bản Quyền (`expires_at`)

Super Admin có thể đặt ngày hết hạn dịch vụ cho từng phòng khám (ví dụ: 1 tháng, 6 tháng, 1 năm). Khi đến ngày hết hạn:

Hệ thống tự động hiển thị thông báo bản quyền khi đơn vị đăng nhập.
Nút kích hoạt/tạm khóa (is_active) cho phép Super Admin tạm dừng quyền truy cập ngay lập tức nếu đơn vị vi phạm hợp đồng hoặc quá hạn thanh toán.

4.2 Kiểm Soát Hạn Mức (Quotas Enforcement)

Số nhân sự tối đa (`max_staff`): Giới hạn số lượng bác sĩ/kỹ thuật viên đơn vị được phép thêm vào danh mục.
Số bệnh nhân tối đa (`max_patients`): Giới hạn số hồ sơ bệnh nhân tiếp nhận đồng thời trong ngày. Giúp bảo đảm tài nguyên server và phân hạng gói dịch vụ thương mại.

🔑 5. CẤP TÀI KHOẢN QUẢN TRỊ CƠ SỞ & RESET MẬT KHẨU

Khi một khách hàng đăng ký mới, Super Admin thực hiện 2 thao tác bàn giao:

Khởi tạo bản ghi đơn vị mới trong bảng tenants với mã unit_code đã thống nhất.
Tạo tài khoản quản trị viên đầu tiên cho phòng khám trong bảng tai_khoan:
unit_code: [mã đơn vị], username: admin, role: ADMIN, mật khẩu mặc định an toàn.
Khi khách hàng quên mật khẩu Admin: Super Admin có quyền đặt lại mật khẩu mới cho tài khoản Admin của cơ sở đó trực tiếp từ bảng điều khiển.

🗄️ 6. QUẢN TRỊ CƠ SỞ DỮ LIỆU CLOUDFLARE D1 TẬP TRUNG

Hệ thống sử dụng cơ sở dữ liệu phân tán Cloudflare D1 Database (pmcg-db) với 15 bảng nghiệp vụ chuẩn hóa:

💾

Quy Tắc Tenant Clamping: Mọi bảng CSDL đều có cột unit_code TEXT NOT NULL. Tất cả các câu lệnh SELECT, INSERT, UPDATE, DELETE đều bắt buộc kẹp chặt điều kiện WHERE unit_code = ?, loại bỏ hoàn toàn khả năng rò rỉ dữ liệu giữa các bệnh viện.

Chiến Lược Sao Lưu 3 Cấp Độ & Khôi Phục Thảm Họa (Disaster Recovery)

Hệ thống vận hành theo mô hình một nguồn chân lý (Single Source of Truth) trên máy chủ MiniPC Master (Node >= 22.16, Engine v1.1.0) kết hợp sao lưu 3 cấp độ tự động:

Cấp 1 - Sao Lưu Tệp CSDL (.db) Lúc 23:00 Hàng Ngày:
Tác vụ Task Scheduler PMCG-Backup-DB-2300 chạy script node tools/backup-db.mjs sử dụng cơ chế snapshot nguyên tử VACUUM INTO và kiểm tra PRAGMA integrity_check. Các bản sao lưu lưu trữ tại backups/db/, tự động xoay vòng giữ 30 ngày gần nhất. Nếu đẩy lên đám mây (Google Drive / OneDrive), bắt buộc nén mã hóa 7z AES-256.
Cấp 2 - Đồng Bộ Lên Google Sheets (09:00, 12:00, 16:00):
Đẩy dữ liệu các bảng nghiệp vụ lên Google Sheets riêng tư phục vụ tra cứu nhanh và phòng chống thảm họa phần cứng.
Cấp 3 - Đẩy Bản Sao Turso Read-Replica Mỗi Giờ:
Script tools/push-to-turso.mjs tự động đồng bộ một chiều từ change_log sang cụm Turso Edge Cloud mỗi giờ để phục vụ truy vấn đọc khi cần.

Quy Trình Khôi Phục CSDL (Disaster Recovery Drill - Chuẩn N-4):

Khi cần khôi phục dữ liệu từ tệp sao lưu .db, Quản trị viên thực hiện bằng công cụ tự động an toàn:

node tools/restore-db.mjs backups/db/pmcg-YYYY-MM-DD.db

Công cụ tự động: (1) Kiểm tra an toàn tệp nguồn (hỗ trợ cờ --dry-run để kiểm tra trước các bước thực hiện), (2) Tạm dừng dịch vụ MiniPC Engine và polling tối đa 30s chờ đóng cổng 8080, (3) Thực hiện PRAGMA wal_checkpoint(TRUNCATE) và sao lưu toàn bộ .db, -wal, -shm sang bản lưu dự phòng .pre-restore, (4) Sao chép file mới, (5) Tự động chạy migration schema tools/migrate.mjs --target=minipc, (6) Khởi động lại dịch vụ an toàn trong khối try ... finally (trừ khi có cờ --no-restart).

Công Cụ Đối Chiếu & Tái Đồng Bộ Cụm Turso (Chuẩn N-5):

Sau khi khôi phục hoặc khi phát hiện lệch dữ liệu giữa MiniPC Master và Turso Replica:

Đối chiếu chênh lệch dòng: node tools/compare-dbs.mjs (hoặc node tools/resync-turso.mjs --dry-run).
Đồng bộ toàn diện sang Turso: node tools/resync-turso.mjs (hoặc node tools/resync-turso.mjs --table=benh_nhan cho từng bảng). Công cụ xóa và chèn theo lô ≤ 500 dòng trong transaction, cập nhật turso_last_id và replica_lag = 0.

Hàng Đợi Ngoại Tuyến (Offline-First), Lỗi 401 & Xử Lý Xung Đột 409 (Chuẩn N-2):

Khi mất kết nối hoặc MiniPC gián đoạn, hệ thống tự động đưa các thao tác ghi hợp lệ vào hàng đợi writeQueue trên IndexedDB của trình duyệt. Danh sách thao tác được phép xếp hàng ngoại tuyến (QUEUEABLE_ACTIONS) bao gồm: saveSchedule, saveLichTrinh, saveChamCong, saveThongKeThuThuat, bulkUpdatePatients, saveReorderedData, saveEmployees. Mỗi thao tác được gắn chặt với unitCode và userId lúc tạo.

Khi gặp phản hồi 401 (hết hạn hoặc thu hồi token): hệ thống giữ nguyên trạng thái pending, không tăng số lần thử để chống mất dữ liệu, tự động phát sự kiện AUTH_REQUIRED hiển thị hộp thoại đăng nhập lại và phát lại sau khi xác thực. Trình duyệt tự động làm mới token định kỳ mỗi 30 phút qua action refreshToken để phiên làm việc không bị gián đoạn. Nếu máy chủ báo xung đột phiên bản (409), hộp thoại giải quyết xung đột trực quan sẽ xuất hiện cho phép chọn "Giữ bản của tôi" hoặc "Lấy bản máy chủ".

⚙️ 7. GIÁM SÁT CLOUDFLARE WORKERS & CRON JOB TỰ ĐỘNG

Cloudflare Worker API: Backend Worker (pmcg-api.dpthai-ttytmk.workers.dev) đóng vai trò Gateway thông minh, xử lý xác thực JWT (với cơ chế thu hồi tức thì qua token_version), kiểm soát phiên và điều phối dữ liệu tới MiniPC Master.
Cron Trigger Tự Động Định Kỳ (02:00 Sáng VN):
Hệ thống tự động kích hoạt bảo trì CSDL định kỳ lúc 02:00 sáng hàng ngày để:
- Dọn dẹp các bản ghi thao tác đã thực thi (applied_ops) quá 30 ngày.
- Dọn dẹp lịch sử đăng nhập thất bại (login_attempts) hết hạn quá 1 ngày.
- Dọn dẹp nhật ký thay đổi (change_log) đã được đồng bộ an toàn sang Turso và Sheets quá 7 ngày.
- Tự động chốt sổ và lưu vết nhật ký vận hành an toàn.

✅ 8. CHECKLIST ONBOARDING KHÁCH HÀNG MỚI (5 BƯỚC)

Bước	Nội dung công việc	Người thực hiện	Trạng thái
Bước 1	Thu thập thông tin: Tên phòng khám, Địa chỉ, Số lượng bác sĩ/KTV, Logo	Khách hàng cung cấp	Đầu vào
Bước 2	Khởi tạo đơn vị mới trên tab `Quản Lý Đơn Vị SaaS` với `unit_code` riêng	Super Admin	Cấu hình
Bước 3	Thiết lập ngày hết hạn bản quyền và quota nhân sự / bệnh nhân theo gói cước	Super Admin	Cấp phép
Bước 4	Tạo tài khoản quản trị đầu tiên (`admin`) và bàn giao thông tin đăng nhập	Super Admin	Bàn giao
Bước 5	Gửi tài liệu Cẩm nang Hướng Dẫn Sử Dụng (Tab Cơ sở y tế) và hướng dẫn nhập 5 danh mục ban đầu	Hỗ trợ kỹ thuật	Hoàn tất

T.I.M.E.S. SYSTEM v4

Cẩm Nang Vận Hành Xếp Lịch Lâm Sàng T.I.M.E.S. v4