# Chương 7: Hướng dẫn dành cho Lập trình viên (Developer Guide)
Chương này cung cấp những kiến thức và quy ước cần thiết nhất cho một lập trình viên (Developer) mới tham gia vào dự án, để có thể nhanh chóng làm quen, build source code và debug lỗi hệ thống Signing Service Tân Cảng.
# 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 `` của Root POM. Không cần đi sửa rải rác.
Ví dụ các Properties quan trọng:
```xml
17
6.0
```
Đặ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 `` 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ẻ `` 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](https://www.jetbrains.com/idea/download/download-thanks.html?platform=windows)**[ ](https://www.jetbrains.com/idea/download/download-thanks.html?platform=windows)**)
\- Hoặc cài đặt **Visual Studio Code** ( [Link cài đặt Visual Studio Code](https://code.visualstudio.com/sha/download?build=stable&os=win32-x64-user) )
\- Cài đặt **JDK-17** ( [Link cài đặt JDK-17](https://download.oracle.com/java/17/archive/jdk-17.0.12_windows-x64_bin.exe) )
Thêm java vào biến môi trường:
[ ](https://docs.lifetex.vn/uploads/images/gallery/2026-04/Greimage.png)[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/m4Wimage.png)
\- Cài đặt **Maven** ( [Link tải maven](https://dlcdn.apache.org/maven/maven-3/3.9.14/binaries/apache-maven-3.9.14-bin.zip) )
Giải nén thư mục và thêm vào biến môi trường
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/s28image.png)
Kiểm tra java và maven đã được cấu hình chưa:
```bash
java --version
mvn -v
```
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/Sokimage.png)
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**
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/Jpoimage.png)
Clone source code: [http://192.168.0.95/nam/signing\_service\_tan\_cang.git](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:
```bash
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**"
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/3wGimage.png)
Mở thư mục Project **kyso\_service** lên để thực hiện phát triển phần mềm
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/75uimage.png)
---
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. ```bash
mvn clean install -DskipTests
```
Build source thành công
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/FzBimage.png)
4. **Chạy Local Signing Web Service:**
**Với môi trường phát triển là VScode:**
```bash
cd signing-web-service\target
java -jar signing-web-service-0.0.1-SNAPSHOT.jar
```
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/3n1image.png)
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)
```bash
java -jar signing-web-service-0.0.1-SNAPSHOT.jar --server.port=
```
**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. [](https://docs.lifetex.vn/uploads/images/gallery/2026-04/jS8image.png)
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**
[](https://docs.lifetex.vn/uploads/images/gallery/2026-04/toVimage.png)
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`.*