Chương 7: Hướng dẫn dành cho Lập trình viên (Developer Guide)

• 7.1. Cấu trúc Quản lý Dependency (Parent POM)
• 7.2. Hướng dẫn Môi trường & Build Source
• 7.3. Cách Debug (Kiểm thử) các Tính năng Phức tạp

7.1. Cấu trúc Quản lý Dependency (Parent POM)

Toàn bộ dự án đi theo mô hình Maven Multi-Module, được kiểm soát chặt chẽ bởi file 

pom.xml nằm ở gốc dự án (Root Directory). Đây là nơi khai báo dependencyManagement.

Lý do của kiến trúc này:

1. Đảm bảo toàn bộ 5 module con (signing-core, signing-web-service, v.v.) luôn đồng nhất một phiên bản thư viện.
2. Khi muốn nâng cấp hệ thống Spring Boot, Lõi DSS hoặc Aspose, lập trình viên chỉ cần thay đổi tại <properties> của Root POM. Không cần đi sửa rải rác.

Ví dụ các Properties quan trọng:

<properties>
    <java.version>17</java.version>
    <dss.version>6.0</dss.version> <!-- Phiên bản cốt lõi Digital Signature Services EU -->
</properties>

Đặc biệt, hệ thống sử dụng dss-pades-pdfbox (bản 6.0.1.d4j.1) kết hợp với các Custom Handler tự phát triển trong thư mục eu.europa.esig.dss ở module lõi.

Tuyệt đối không khai báo <version> thủ công vào các dependency bên dưới các module con (ví dụ ở signing-web-service/pom.xml). Mọi version phải tham chiếu từ thẻ <dependencyManagement> của Parent POM.

7.2. Hướng dẫn Môi trường & Build Source

Hướng dẫn cài đặt môi trường

      Môi trường phát triển hệ điều hành Windows

          - Cài đặt IntelliJ IDEA ( Link cài đặt Intellij IDEA )

         - Hoặc cài đặt Visual Studio Code ( Link cài đặt Visual Studio Code )

         - Cài đặt JDK-17 ( Link cài đặt JDK-17  )

Thêm java vào biến môi trường: 

         - Cài đặt Maven ( Link tải maven  )

Giải nén thư mục và thêm vào biến môi trường

Kiểm tra java và maven đã được cấu hình chưa:

java --version
mvn -v

1. Clone mã nguồn & Mở IDE:
   • Hỗ trợ tốt nhất trên IntelliJ IDEA. 
   • Ví dụ sử dụng IDE Visual Studio Code 

Clone source code: http://192.168.0.95/nam/signing_service_tan_cang.git nhánh dev_namdh_app_signing_desktop

Mở terminal vscode lên và clone source code về bằng lệnh sau: 

git clone --single-branch --branch dev_namdh_app_signing_desktop http://192.168.0.95/nam/signing_service_tan_cang.git kyso_service 

Nhập thông tin tài khoản Gitlab để clone source code về với tên thư mục "kyso_service"

Mở thư mục Project kyso_service lên để thực hiện phát triển phần mềm

---

1. • Khi Import, chọn Import theo chuẩn Maven Project tại thư mục Gốc.
2. Build Dự án Local: Mở terminal và gõ lệnh: (Bỏ qua Unit Test để tiết kiệm thời gian)

3. mvn clean install -DskipTests

   Build source thành công
   

   

   
   
4. Chạy Local Signing Web Service:

Với môi trường phát triển là VScode:

cd signing-web-service\target
java -jar signing-web-service-0.0.1-SNAPSHOT.jar

Port mặc địch của định của dịch vụ khi chạy lên là 6868 (Có thể cấu hình chay port khác bằng lệnh sau)

java -jar signing-web-service-0.0.1-SNAPSHOT.jar --server.port=<port_service>

Với môi trường phát triển là IntelliJ IDEA

1. • Trỏ IDE vào thư mục module signing-web-service.
   • Tìm Main class SigningWebServiceApplication.java và thiết lập Run Configuration.

2. 

3.  
   • Chú ý: Web Service cần có cấu hình application.yml trỏ đúng vào CSDL và Server Redis (Trường hợp không có DB thật, có thể dựng Docker Container Redis & SQL Server Local trước khi chạy).
4. chạy thành công

1. Chạy Local Signing Desktop (Cổng 6868):
   • Trỏ IDE vào thư mục module signing-desktop.
   • Chạy class SigningDesktopApplication.java. (Ứng dụng chạy Swing UI, cần gắn thử một USB Token thật vào máy để test tính năng Load Danh sách chứng thư).

7.3. Cách Debug (Kiểm thử) các Tính năng Phức tạp

Gỡ chặn CORS khi gọi từ môi trường Frontend (Local Web Proxy)

Vì Desktop App chạy ở cổng localhost:6868 nhưng Frontend Portlet lại chạy trên tên miền của hệ thống E-Office (Ví dụ https://portal.tancang.com.vn), nên mặc định trình duyệt như Chrome/Edge sẽ chặn CORS (Cross-Origin Resource Sharing).

Để lập trình Frontend kiểm thử chức năng gọi API ký xuống Local Desktop, Lập trình viên cần tắt tường lửa bảo mật của trình duyệt Chrome:

• Mở command line, khởi động trình duyệt bằng luồng riêng biệt (Vô hiệu hóa Web Security và định tuyến User Data cục bộ):

chrome.exe --disable-web-security --user-data-dir="C:\ChromeDevSession"

• Tính năng này đã được ghi chép trong nội bộ dự án, nhưng Bắt buộc phải tắt cờ này khi mang lên môi trường Production (Xử lý dứt điểm trong code bằng config Spring @CrossOrigin trên Controller Local).

Môi trường giả lập USB Token

Trong quá trình phát triển (Dev) nếu không có USB Token cứng do công ty cung cấp, bạn có thể tạo một file Mock PKCS12 (.p12) và thiết đặt dss-token trong mã nguồn đọc thẳng từ file vật lý này thay vì giao tiếp qua thư viện .dll / PKCS#11. Xem code tham khảo tại class UsbTokenService.java.