feat: Tích hợp Bản quyền License AES-256 (OTH.Adapter), Biên bản giao ban A4, Biểu đồ tròn và Tài liệu triển khai demo

2026-10-27 02:04:23 -07:00
parent 6d54ca20f6
commit 358cfbfde1
13 changed files with 2149 additions and 32 deletions
@@ -0,0 +1,298 @@
+# HƯỚNG DẪN CÀI ĐẶT, TRIỂN KHAI & KIỂM THỬ DEMO HỆ THỐNG WEB GIAO BAN BỆNH VIỆN (BẢN GOLANG)
+
+> **Tài liệu chuyển giao kỹ thuật & Hướng dẫn sử dụng thử nghiệm**  
+> **Dự án**: DH-HIS Quản Lý Giao Ban Y Tế  
+> **Phiên bản ứng dụng**: `v1.0.2` (Golang Engine)  
+> **Ngày cập nhật**: Tháng 10/2026  
+
+---
+
+## MỤC LỤC
+1. [Tổng Quan Hệ Thống](#1-tổng-quan-hệ-thống)
+2. [Yêu Cầu Môi Trường & Hạ Tầng](#2-yêu-cầu-môi-trường--hạ-tầng)
+3. [Cấu Trúc Thư Mục & Tệp Tin](#3-cấu-trúc-thư-mục--tệp-tin)
+4. [Hướng Dẫn Cấu Hình Kết Nối CSDL (PostgreSQL)](#4-hướng-dẫn-cấu-hình-kết-nối-csdl-postgresql)
+5. [Cơ Chế Quản Lý Bản Quyền (License Key)](#5-cơ-chế-quản-lý-bản-quyền-license-key)
+6. [Hướng Dẫn Triển Khai Chạy Ứng Dụng](#6-hướng-dẫn-triển-khai-chạy-ứng-dụng)
+   - [6.1 Triển khai trên môi trường Windows](#61-triển-khai-trên-môi-trường-windows)
+   - [6.2 Triển khai trên môi trường Linux (Systemd Service)](#62-triển-khai-trên-môi-trường-linux-systemd-service)
+7. [Kịch Bản Kiểm Thử & Hướng Dẫn Demo Khách Hàng](#7-kịch-bản-kiểm-thử--hướng-dẫn-demo-khách-hàng)
+   - [Kịch bản 1: Kiểm thử Báo cáo Ngoại trú & Phân tích Đa chu kỳ](#kịch-bản-1-kiểm-thử-báo-cáo-ngoại-trú--phân-tích-đa-chu-kỳ)
+   - [Kịch bản 2: Kiểm thử Báo cáo Nội trú, Chuyển viện & Ca nặng](#kịch-bản-2-kiểm-thử-báo-cáo-nội-trú-chuyển-viện--ca-nặng)
+   - [Kịch bản 3: Lập Biên bản Giao ban A4 & Phân quyền 3 cấp](#kịch-bản-3-lập-biên-bản-giao-ban-a4--phân-quyền-3-cấp)
+   - [Kịch bản 4: Kiểm tra Chức năng Bản quyền & Quản lý Issue](#kịch-bản-4-kiểm-tra-chức-năng-bản-quyền--quản-lý-issue)
+8. [Thông Tin CSDL Mẫu Dùng Kiểm Thử Thực Tế](#8-thông-tin-csdl-mẫu-dùng-kiểm-thử-thực-tế)
+
+---
+
+## 1. TỔNG QUAN HỆ THỐNG
+
+Phần mềm **Web Giao Ban Bệnh Viện (Bản Golang)** là giải pháp chuyển đổi số hỗ trợ Ban Lãnh đạo bệnh viện, Phòng Kế hoạch Tổng hợp và các Trưởng/Phó khoa tổ chức họp giao ban đầu giờ buổi sáng:
+- **Tốc độ vượt trội**: Viết hoàn toàn bằng ngôn ngữ Go (Golang), binary biên dịch tĩnh độc lập, khởi động tức thì, dung lượng RAM tiêu thụ chỉ khoảng 15MB - 30MB (nhẹ hơn 10 lần so với các nền tảng script).
+- **Trích xuất số liệu 24h tự động**: Đọc trực tiếp từ cơ sở dữ liệu HIS (PostgreSQL), tổng hợp số lượt khám ngoại trú (BHYT / Viện phí), bệnh nhân nội trú (cũ, mới, ra viện, chuyển viện, tử vong, hiện còn điều trị, theo dõi nặng, chăm sóc cấp I).
+- **Phân tích so sánh đa kỳ**: So sánh tức thì với kỳ liền trước, cùng kỳ tháng trước hoặc cùng kỳ năm trước.
+- **Biên bản giao ban chuẩn A4 Y tế**: Mẫu biên bản chuẩn hành chính y tế, đồng bộ dữ liệu chỉ với 1 click chuột, hỗ trợ phân quyền 3 cấp và in ấn A4 sắc nét.
+- **Bảo mật bản quyền tích hợp**: Kiểm soát kích hoạt theo mã bệnh viện (`mabvbh`), thời hạn bản quyền (`DateExpires`) và mã hóa chuẩn công nghiệp OpenSSL AES-256-CBC.
+
+---
+
+## 2. YÊU CẦU MÔI TRƯỜNG & HẠ TẦNG
+
+| Thành phần | Yêu cầu tối thiểu | Khuyến nghị |
+| :--- | :--- | :--- |
+| **Hệ điều hành** | Windows 10/11, Windows Server 2012 R2+ hoặc Linux (Ubuntu 20.04+, Debian 11+, CentOS 7+) | Windows Server 2019/2022 hoặc Ubuntu Server 22.04 LTS |
+| **Kiến trúc CPU** | x86_64 (64-bit) | 2 Cores trở lên |
+| **Bộ nhớ RAM** | 512 MB trống | 2 GB trở lên |
+| **Dung lượng đĩa** | 100 MB trống cho phần mềm | SSD 10 GB trở lên |
+| **Cơ sở dữ liệu** | PostgreSQL 9.2 đến 16+ | PostgreSQL 9.6 / 12 / 14 |
+| **Trình duyệt Web** | Google Chrome, Microsoft Edge, Cốc Cốc, Mozilla Firefox | Phiên bản hiện đại hỗ trợ ES6 |
+
+---
+
+## 3. CẤU TRÚC THƯ MỤC & TỆP TIN
+
+```
+web-giao-ban-go/
+├── web-giao-ban               # Binary thực thi trên môi trường Linux
+├── web-giao-ban.exe           # File chạy thực thi trên Windows (kèm Icon chuẩn)
+├── config.json                # Tệp cấu hình cổng mạng, CSDL và Bản quyền
+├── public/                    # Thư mục giao diện Web Frontend
+│   ├── index.html             # Trang báo cáo giao ban chính
+│   ├── app.js                 # Logic điều khiển báo cáo, biểu đồ, biên bản A4
+│   ├── admin.html             # Trang Quản trị kết nối CSDL và Kích hoạt License
+│   ├── admin.js               # Logic trang quản trị
+│   ├── favicon.ico            # Favicon nhận diện DH-HIS
+│   └── css / js / ...         # Thư viện giao diện (Tailwind, FontAwesome, Chart.js)
+├── data/                      # Lưu trữ dữ liệu hệ thống
+│   ├── issues.json            # Nhật ký báo lỗi và cải tiến (Issue tracking)
+│   └── uploads/               # Thư mục lưu tệp đính kèm chụp màn hình issue
+├── docs/                      # Tài liệu hướng dẫn triển khai
+│   └── HUONG_DAN_CAI_DAT_TRIEN_KHAI_DEMO.md
+└── build.sh                   # Script biên dịch tự động đa nền tảng
+```
+
+---
+
+## 4. HƯỚNG DẪN CẤU HÌNH KẾT NỐI CSDL (POSTGRESQL)
+
+Mở tệp `config.json` bằng Notepad, VSCode hoặc `nano`:
+
+```json
+{
+  "server": {
+    "port": 3001,
+    "cors_allowed_origins": ["*"]
+  },
+  "databases": [
+    {
+      "id": "an_omon_full_04052026",
+      "name": "BVĐK Ô Môn (33GB)",
+      "host": "localhost",
+      "port": 5432,
+      "user": "postgres",
+      "password": "ENC(U2FsdGVkX1+...)",
+      "dbname": "an_omon_full_04052026",
+      "sslmode": "disable"
+    },
+    {
+      "id": "backup_govap_20260408_010001",
+      "name": "BVĐK Gò Vấp (65GB)",
+      "host": "localhost",
+      "port": 5432,
+      "user": "postgres",
+      "password": "ENC(U2FsdGVkX1+...)",
+      "dbname": "backup_govap_20260408_010001",
+      "sslmode": "disable"
+    }
+  ],
+  "license": {
+    "crypto_key": "ENC(U2FsdGVkX18...)",
+    "active_key": "U2FsdGVkX18Zsq52FPbB7FS1QM7CwWh+t1Esi96gUMFILJD0vZXM69uQBC4sP7TjLVOiJPZt0KIq17iql+hXehLCVSbCEhwKKm+zNab+u2Swah63A52hz0KMJXddLRZ6vanmP2goLTzY7749HsFVRDq+3bdbi8fdUZCpAsSTEiqC2cRTpF5WVh0SHt1wX/i42YSQgOYPeXQtg+lRx/URk4p7lYSVQOYWXglp99kO+Va1ADoNcTgrfz3aaAxAkj0S"
+  }
+}
+```
+
+> [!NOTE]
+> - Mật khẩu CSDL (`password`) và Passphrase giải mã (`crypto_key`) được hỗ trợ lưu dạng mã hóa `ENC(...)`. Nếu nhập dạng chuỗi thông thường (Plaintext), hệ thống vẫn tự động nhận diện và kết nối an toàn.
+> - Có thể thêm bao nhiêu CSDL tùy ý vào mảng `databases`. Người dùng có thể chuyển đổi linh hoạt ngay trên dropdown của thanh công cụ Web.
+
+---
+
+## 5. CƠ CHẾ QUẢN LÝ BẢN QUYỀN (LICENSE KEY)
+
+### 5.1 Quy cách và Cấu trúc Bản quyền
+Hệ thống sử dụng cơ chế bảo mật theo tiêu chuẩn thư viện `OTH.Adapter / HisPrivateCode`:
+- **Thuật toán**: OpenSSL EVP_BytesToKey (MD5 key derivation + AES-256-CBC).
+- **Khóa dẫn xuất nội bộ**: `BAD5A05F330D5B8CDDFCA9E7ECDC840B`.
+- **Cấu trúc dữ liệu JSON sau giải mã**:
+  ```json
+  {
+    "AtRow": 3,
+    "mabvbh": "84006",
+    "DateExpires": "2027-01-30",
+    "key": "web_giao_ban",
+    "title": "Sử dụng Web giao ban",
+    "TenBV": "Trà Cú",
+    "Đối tác": "dh",
+    "Ghi chú": "Trial"
+  }
+  ```
+- **Quy tắc kiểm duyệt**:
+  1. Trường `key` phải bằng `"web_giao_ban"`.
+  2. Thời hạn `DateExpires` phải lớn hơn hoặc bằng ngày hiện tại.
+  3. Nếu chưa kích hoạt hoặc key hết hạn: Toàn bộ API báo cáo ngoại trú, nội trú và dữ liệu KCB sẽ trả về cảnh báo chặn HTTP 403; giao diện người dùng hiển thị modal hướng dẫn kích hoạt bản quyền.
+
+### 5.2 Key Bản Quyền Mẫu Dùng Thử Nghiệm (DECODE Token)
+Khi thao tác nhập trên giao diện Web Quản trị, người dùng chỉ cần copy và dán duy nhất chuỗi token DECODE bên dưới:
+
+```
+U2FsdGVkX18Zsq52FPbB7FS1QM7CwWh+t1Esi96gUMFILJD0vZXM69uQBC4sP7TjLVOiJPZt0KIq17iql+hXehLCVSbCEhwKKm+zNab+u2Swah63A52hz0KMJXddLRZ6vanmP2goLTzY7749HsFVRDq+3bdbi8fdUZCpAsSTEiqC2cRTpF5WVh0SHt1wX/i42YSQgOYPeXQtg+lRx/URk4p7lYSVQOYWXglp99kO+Va1ADoNcTgrfz3aaAxAkj0S
+```
+
+### 5.3 Cách Kích Hoạt Bản Quyền Trên Web
+1. Mở trình duyệt truy cập: `http://<IP-SERVER>:3001/admin.html`.
+2. Chọn thẻ **"Tab 4: Quản Lý Bản Quyền (License)"**.
+3. Dán chuỗi DECODE token mẫu vào ô văn bản, sau đó bấm nút **"Kích Hoạt Key Bản Quyền"**.
+4. Màn hình sẽ hiển thị thẻ thông tin màu xanh: Đơn vị sở hữu (**BV Trà Cú**), Hạn sử dụng (**30/01/2027**), Trạng thái (**Hợp lệ**).
+
+---
+
+## 6. HƯỚNG DẪN TRIỂN KHAI CHẠY ỨNG DỤNG
+
+### 6.1 Triển khai trên môi trường Windows
+
+1. **Chuẩn bị thư mục**:
+   - Giải nén toàn bộ thư mục `web-giao-ban-go` vào ổ đĩa bất kỳ (ví dụ: `D:\HIS\web-giao-ban-go\`).
+2. **Kiểm tra kết nối CSDL**:
+   - Mở tệp `config.json`, điều chỉnh `host`, `port`, `user`, `password` trỏ đến máy chủ PostgreSQL đang lưu trữ CSDL HIS.
+3. **Khởi chạy ứng dụng**:
+   - Nhấp đúp chuột vào tệp `web-giao-ban.exe` (đã được đính kèm icon nhận diện chuyên nghiệp).
+   - Một cửa sổ dòng lệnh hiển thị thông báo:
+     ```
+     [INFO] DH-HIS Web Giao Ban v1.0.2 đang lắng nghe tại cổng :3001
+     [INFO] CSDL hiện hữu: BVĐK Ô Môn, BVĐK Gò Vấp
+     [INFO] Bản quyền: BV Trà Cú - Hạn dùng đến 2027-01-30
+     ```
+4. **Cài đặt chạy ngầm tự khởi động cùng Windows (Tùy chọn)**:
+   - Sử dụng công cụ `nssm` (Non-Sucking Service Manager):
+     ```cmd
+     nssm install DHWebGiaoBan "D:\HIS\web-giao-ban-go\web-giao-ban.exe"
+     nssm set DHWebGiaoBan AppDirectory "D:\HIS\web-giao-ban-go"
+     nssm start DHWebGiaoBan
+     ```
+
+### 6.2 Triển khai trên môi trường Linux (Systemd Service)
+
+1. **Phân quyền thực thi**:
+   ```bash
+   chmod +x /home/othau/dh-coding/web-giao-ban-go/web-giao-ban
+   ```
+2. **Tạo dịch vụ quản lý Systemd**:
+   Tạo tệp cấu hình `/etc/systemd/system/web-giao-ban-go.service`:
+   ```ini
+   [Unit]
+   Description=DH-HIS Web Giao Ban Go Service
+   After=network.target postgresql.service
+
+   [Service]
+   Type=simple
+   User=othau
+   WorkingDirectory=/home/othau/dh-coding/web-giao-ban-go
+   ExecStart=/home/othau/dh-coding/web-giao-ban-go/web-giao-ban
+   Restart=always
+   RestartSec=5
+   Environment=PORT=3001
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+3. **Kích hoạt và khởi chạy dịch vụ**:
+   ```bash
+   sudo systemctl daemon-reload
+   sudo systemctl enable web-giao-ban-go
+   sudo systemctl restart web-giao-ban-go
+   sudo systemctl status web-giao-ban-go
+   ```
+
+---
+
+## 7. KỊCH BẢN KIỂM THỬ & HƯỚNG DẪN DEMO KHÁCH HÀNG
+
+### Kịch bản 1: Kiểm thử Báo cáo Ngoại trú & Phân tích Đa chu kỳ
+1. **Truy cập hệ thống**: Mở trình duyệt vào địa chỉ `http://localhost:3001/` (hoặc domain demo nội bộ).
+2. **Khóa/Mở ô chọn ngày (`ISS-20261026-001`)**:
+   - Chọn mốc nhanh: *"Hôm nay (24h)"*, *"Tháng 01/2026"*, *"Tháng 02/2026"*.  
+     *Quan sát*: Hai ô Từ ngày và Đến ngày lập tức được tô xám và có nhãn **"Cố định"**, người dùng không bị gõ nhầm ngày.
+   - Chọn mốc *"Tùy chọn khoảng ngày..."*: Hai ô ngày chuyển màu trắng, có nhãn **"Mở khóa"** để tùy biến ngày giờ.
+3. **Xem số liệu khám chữa bệnh**:
+   - Bấm nút **"Xem Báo Cáo"**: Các thẻ KPI (Tổng lượt khám, Khám BHYT, Khám Thu phí, Chuyển tuyến) hiển thị số liệu thực tế.
+4. **Chuyển đổi kiểu biểu đồ Ngoại trú (`ISS-20261026-002`)**:
+   - Bấm nút **"Cột Khoa"**: Xem số lượt khám các phòng khám đông nhất.
+   - Bấm nút **"% Tròn Khoa"**: Hiển thị biểu đồ hình tròn (Doughnut) phân tích tỷ lệ phần trăm thị phần khám của từng khoa.
+   - Bấm nút **"BHYT / Thu phí"**: Biểu đồ cột nhóm trực quan phân định rõ cơ cấu doanh thu BHYT vs Viện phí.
+   - Bấm nút **"Theo CLS"**: Biểu đồ thống kê lượt Xét nghiệm, Siêu âm, X-quang, Điện tim...
+5. **So sánh đa chu kỳ (`ISS-20261027-003` & `ISS-20261027-004`)**:
+   - Tích chọn checkbox **"Bật chế độ đối chiếu đa chu kỳ"**.
+   - Thử chọn dropdown nhanh: *"So với cùng kỳ tháng trước"*, *"So với cùng kỳ năm trước"*.
+   - Tích chọn checkbox **"Ẩn dòng không có dữ liệu (2 kỳ = 0)"**: Bảng tự động giấu các phòng khám không phát sinh lượt, giúp bản in gọn gàng.
+
+---
+
+### Kịch bản 2: Kiểm thử Báo cáo Nội trú, Chuyển viện & Ca nặng
+1. Chuyển sang **"Tab 2: Báo Cáo Giao Ban Nội Trú"**.
+2. **Kiểm tra các biểu đồ chuyên sâu Nội trú (`ISS-20261027-001`)**:
+   - Bấm **"Cột Vào Viện"**: Xem số ca nhập viện và ra viện của các khoa lâm sàng.
+   - Bấm **"% Tròn 4 Tiêu Chí"**: Biểu đồ hình tròn thể hiện rõ tương quan 4 tiêu chí toàn viện (Bệnh cũ, Mới nhập, Xuất viện, Hiện còn).
+   - Bấm **"% Hiện Còn Theo Khoa"**: Đánh giá áp lực giường bệnh và tỷ lệ điều trị của từng khoa.
+   - Bấm **"Cột Nhóm Tổng Hợp"**: Cột nhóm 4 tiêu chí song song cho từng khoa nội trú.
+3. **Bảng 3 - Bệnh nhân chuyển tuyến**:
+   - Xem danh sách chi tiết: Mã bệnh nhân, Họ tên, Chẩn đoán, Kết quả cận lâm sàng.
+   - Nhập ghi chú giao ban vào ô văn bản (ví dụ: *"Đã liên hệ BV tuyến trên tiếp nhận an toàn"*). Dữ liệu được lưu trữ tự động.
+4. **Bảng 4 - Bệnh nhân nặng theo dõi đặc biệt & Chăm sóc Cấp I**:
+   - Theo dõi số ngày điều trị, phân loại mức độ và ghi chú chỉ đạo chuyên môn của trực lãnh đạo.
+
+---
+
+### Kịch bản 3: Lập Biên bản Giao ban A4 & Phân quyền 3 cấp (`ISS-20261027-002`)
+1. Chuyển sang **"Tab 3: Biên Bản Giao Ban"**.
+2. **Kiểm tra tính năng Đồng bộ 24h tự động**:
+   - Bấm nút **"Đồng bộ số liệu 24h"**: Hệ thống tự động trích xuất các chỉ số ngoại trú, nội trú, chuyển viện điền thẳng vào Mục I của biên bản.
+3. **Kiểm tra Phân quyền 3 cấp**:
+   - **Cấp 1 (Bác sĩ / Nhân viên)**: Chọn vai trò Cấp 1 $\rightarrow$ Toàn bộ văn bản chuyển sang chế độ CHỈ XEM (Read-only), các nút Lưu, Đồng bộ và Khóa bị ẩn hoàn toàn.
+   - **Cấp 2 (Thư ký giao ban)**: Được quyền chỉnh sửa Mục I đến Mục IV, không được sửa Mục V (Chỉ đạo BGĐ) và không có quyền bấm Khóa.
+   - **Cấp 3 (Chủ trì / Ban Giám Đốc)**: Được quyền kết luận Mục V, sửa toàn bộ và bấm nút **"Khóa biên bản"**. Khi đã khóa, văn bản được niêm phong tránh sửa đổi ngoài ý muốn.
+4. **In ấn chuẩn A4**:
+   - Bấm nút **"In Biên Bản A4"**: Giao diện tự động tối ưu phông chữ, ẩn thanh công cụ, chia trang vừa vặn chuẩn văn bản y tế có sẵn đầy đủ chữ ký Thư ký và Lãnh đạo duyệt.
+
+---
+
+### Kịch bản 4: Kiểm tra Chức năng Bản quyền & Quản lý Issue
+1. **Kiểm tra Bản quyền**:
+   - Góc trên thanh tiêu đề hiển thị huy hiệu:  
+     `BV Trà Cú (web_giao_ban) - HSD: 2027-01-30`.
+   - Vào `admin.html#tab-license`: Thử kiểm tra thông tin, hoặc thử dán key không đúng định dạng để xem thông báo chặn lỗi bảo mật.
+2. **Quản lý Issue & Báo lỗi**:
+   - Chuyển sang **"Tab 4: Quản Lý Issue & Báo Lỗi"**.
+   - Bấm nút **"Tạo Báo Lỗi / Đề Xuất Mới"**: Điền nội dung, đính kèm ảnh chụp màn hình, phân loại mức độ và gửi lưu.
+   - Bấm **"Xuất Excel Danh Sách"** để tải file Excel tổng hợp các vấn đề cần xử lý.
+
+---
+
+## 8. THÔNG TIN CSDL MẪU DÙNG KIỂM THỬ THỰC TẾ
+
+Hệ thống đã nạp sẵn cấu hình kết nối tới 2 bộ cơ sở dữ liệu lớn thực tế để kiểm thử hiệu năng truy vấn:
+
+1. **Cơ sở dữ liệu Bệnh viện Đa khoa Ô Môn**:
+   - ID định danh: `an_omon_full_04052026`
+   - Dung lượng CSDL: **33 GB**
+   - Khoảng thời gian dữ liệu đầy đủ nhất: **Tháng 01/2026** và **Tháng 02/2026** (Chọn preset có sẵn để nạp số liệu tức thì).
+2. **Cơ sở dữ liệu Bệnh viện Đa khoa Gò Vấp**:
+   - ID định danh: `backup_govap_20260408_010001`
+   - Dung lượng CSDL: **65 GB**
+   - Dùng để đối chiếu hiệu năng khi xử lý khối lượng bệnh án và lượt khám lớn.
+
+---
+
+> **Hỗ trợ kỹ thuật & Nâng cấp tính năng**:  
+> Đội ngũ phát triển phần mềm DH-HIS  
+> Gitea Issue Tracker: `https://i.dh-his.com/hdhiswork/DUAN/issues`