web-giao-ban-go/docs/HUONG_DAN_CAI_DAT_TRIEN_KHAI_DEMO.md

# 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": {
    "key": "U2FsdGVkX18Zsq52FPbB7FS1QM7CwWh+t1Esi96gUMFILJD0vZXM69uQBC4sP7TjLVOiJPZt0KIq17iql+hXehLCVSbCEhwKKm+zNab+u2Swah63A52hz0KMJXddLRZ6vanmP2goLTzY7749HsFVRDq+3bdbi8fdUZCpAsSTEiqC2cRTpF5WVh0SHt1wX/i42YSQgOYPeXQtg+lRx/URk4p7lYSVQOYWXglp99kO+Va1ADoNcTgrfz3aaAxAkj0S"
  }
}
```

> [!NOTE]
> - Mật khẩu CSDL (`password`) đượ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).
- **Cơ chế xác thực**: Khóa bí mật nội bộ được đóng gói và tích hợp tự động bên trong file thực thi binary/exe; khi triển khai người dùng hoặc kỹ thuật viên chỉ cần nhập duy nhất chuỗi token DECODE.
- **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`