From 3bbc3b00c20da20da3941f1e86efe0719928c4c9 Mon Sep 17 00:00:00 2001
From: huanld <huanleducout@outlook.com>
Date: Mon, 18 May 2026 15:21:36 +0700
Subject: [PATCH] docs: add detailed README for installation and API usage

---
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cf40ae8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# Hướng Dẫn Cài Đặt và Sử Dụng Excel To PDF Service
+
+Đây là service độc lập chuyên dùng để chuyển đổi file Excel sang PDF, sử dụng Syncfusion XlsIORenderer (chạy trên .NET 8).
+
+## 1. Cài đặt làm Windows Service (Chạy ngầm)
+
+Để service tự động chạy cùng hệ thống và chạy ngầm (không hiện cửa sổ đen), bạn hãy làm theo các bước sau:
+
+1. **Mở PowerShell dưới quyền Admin** (Run as Administrator)
+2. Chạy lệnh sau để tạo service:
+
+```powershell
+sc.exe create "ExcelToPdfService" binPath= "C:\Users\huanld\Desktop\ExcelToPdfService-deploy\ExcelToPdfService.exe" start= auto
+```
+*(Lưu ý: Nếu bạn di chuyển folder `ExcelToPdfService-deploy` đi chỗ khác, hãy cập nhật lại đường dẫn `binPath` ở trên cho chính xác)*
+
+3. Bật service:
+```powershell
+sc.exe start "ExcelToPdfService"
+```
+
+> **Cách xóa service (nếu muốn gỡ bỏ):**
+> `sc.exe stop "ExcelToPdfService"`
+> `sc.exe delete "ExcelToPdfService"`
+
+---
+
+## 2. API Endpoints
+
+Mặc định Service sẽ chạy ở cổng **5200**: `http://localhost:5200`
+Bạn có thể gọi API bằng Postman, Axios, HttpClient, hoặc bất cứ công cụ nào hỗ trợ REST API.
+
+### API 1: Convert file bằng đường dẫn có sẵn trên Server (Khuyên dùng)
+Dùng khi file Excel và Service nằm trên cùng một máy (hoặc cùng map chung ổ đĩa mạng).
+
+- **URL:** `POST http://localhost:5200/api/ExcelToPdf/convert-by-path`
+- **Body (JSON):**
+```json
+{
+  "FilePath": "C:\\Users\\huanld\\Desktop\\PTSC STR\\SWG-PTSC-70-PL-PLI-T01-FUR-0001.xlsx",
+  "PrintArea": "A1:G50",   // Tuỳ chọn (để null nếu muốn in hết)
+  "Landscape": true        // Tuỳ chọn (true = in ngang, false = in dọc)
+}
+```
+- **Kết quả:** Trả về trực tiếp nội dung file PDF (dạng File Download - `application/pdf`).
+
+### API 2: Convert file bằng cách Upload trực tiếp
+Dùng khi bạn muốn upload file trực tiếp từ Client lên Service để lấy file PDF về. (Hỗ trợ upload tối đa 50MB).
+
+- **URL:** `POST http://localhost:5200/api/ExcelToPdf/convert?landscape=true&printArea=A1:G50`
+- **Body (Form-Data):**
+  - Key: `file` (Kiểu File)
+  - Value: Chọn file `.xlsx` hoặc `.xls`
+- **Kết quả:** Trả về trực tiếp file PDF để tải xuống.
+
+### API 3: Health Check
+Dùng để kiểm tra xem Service có đang hoạt động hay không.
+- **URL:** `GET http://localhost:5200/api/ExcelToPdf/health`
+- **Kết quả (JSON):**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "time": "2026-05-18T08:15:30Z"
+}
+```
+
+---
+
+## 3. Cấu hình (appsettings.json)
+
+Bạn có thể chỉnh sửa cổng mạng (port) hoặc License Key của Syncfusion bằng cách mở file `appsettings.json` trong cùng thư mục:
+
+```json
+{
+  "Syncfusion": {
+    "LicenseKey": "MjExMDkzMEAzMjMxMmUzMTJlMzMzNWd1RGM1NVFmUUMzWmZlN0dCc3NadUJyM1RUYVh1SHVSS1B2Tzdwa0NhcE09"
+  },
+  "Urls": "http://0.0.0.0:5200"
+}
+```
+*Lưu ý: Nếu sửa file `appsettings.json`, bạn cần Restart lại Windows Service (trong `services.msc`) để thay đổi có hiệu lực.*