HTKK Web PWA

PWA React + TypeScript được dựng từ bộ cài HTKK 5.7.3. Ứng dụng chạy trên Linux/macOS/Windows bằng trình duyệt, lưu nháp ngoại tuyến, nhập/xuất XML và chuyển XML tới phần mềm ký số XAdES qua HTTP DSS-X.

Chạy local

Yêu cầu Node.js >=22.13.

npm install
npm run dev

Mở http://localhost:3000.

Kiểm tra toàn bộ:

npm run lint
npx tsc --noEmit
npm test

Triển khai Cloudflare Pages

Tạo project Direct Upload một lần, sau đó dùng script build và đóng gói SSR:

npx wrangler pages project create httk-web \
  --production-branch main \
  --compatibility-date 2026-05-15 \
  --compatibility-flag nodejs_compat
npm run pages:deploy

pages:stage giữ static assets ở thư mục gốc và đóng gói Vinext server theo Pages Advanced Mode.

Phạm vi đã chuyển đổi

• Giải nén đủ 4.190 file, 421.959.737 byte từ MSI.
• Tái dựng đúng cây cài đặt tại legacy/installed-tree.
• 223/223 biểu mẫu có workbook giao diện.
• 849/849 sheet/phụ lục được ánh xạ tới nguồn XML:
  • 564 mapping trực tiếp, đúng phiên bản;
  • 184 mapping KHBS dùng chung, đúng KieuKHBS và VersionKHBS;
  • 101 sheet chỉ có XML skeleton trong bộ cài, được giữ nguyên và đánh dấu rõ, không mượn mapping sai phiên bản.
• 220/220 schema XSD của biểu mẫu được tìm thấy.
• 45.000+ trường được sinh từ metadata Cell, gồm bảng động, XPath, control type, default, min/max và max length.
• 223/223 workbook biểu mẫu đã được chuyển sang XLSX để trích 28.517 công thức và 7.774 rule/validation; 9.054 công thức map thẳng tới field.
• Danh mục tìm kiếm toàn bộ biểu mẫu, renderer form và bảng động.
• Lưu/khôi phục bản nháp bằng IndexedDB, có fallback localStorage.
• Import XML theo local-name, export từ XML skeleton, hỗ trợ clone dòng động.
• Validation metadata/XSD cơ bản, engine số học an toàn cho 4.490 công thức workbook đã map đầy đủ và rule chuyên biệt cho mẫu 01/GTGT.
• PWA manifest, service worker và cache form theo nhu cầu để dùng ngoại tuyến.
• Adapter ký XML HTTP DSS-X có timeout, correlation ID, hủy yêu cầu và xử lý lỗi chuẩn.

Báo cáo máy đọc được nằm tại public/data/conversion-report.json.

Tái sinh catalog từ bộ HTKK gốc

Catalog đã sinh trong public/data/ được lưu cùng source nên không cần bộ cài HTKK để chạy hoặc build ứng dụng. Nếu cần tái chuyển đổi, đặt cây HTKK đã giải nén tại legacy/installed-tree/ rồi chạy:

npm run catalog:build

Thư mục legacy/ chỉ dùng cục bộ và không đưa lên Git vì chứa bộ cài, DLL và workbook gốc dung lượng lớn.

Ký XML XAdES qua HTTP DSS-X

Địa chỉ mặc định là http://127.0.0.1:20005/v1/sign và có thể đổi trong phần Cấu hình ký số. PWA gửi đúng một tài liệu XML UTF-8 dưới dạng Base64 theo profile DSS-X:

{
  "profile": ["urn:flygo:profile:dss-x:xml-xades-baseline-b:1"],
  "reqID": "uuid",
  "inDocs": {
    "doc": [{
      "ID": "htkk-xml",
      "b64Data": { "val": "BASE64_XML", "mimeType": "application/xml" }
    }]
  },
  "optInp": { "sigType": "urn:ietf:rfc:3275" }
}

Service trả XML có chữ ký enveloped XAdES Baseline B trong optOutp.docWithSignature[0].doc.b64Data.val. Tên tệp được gửi qua X-Signer-File-Name; trình duyệt tự gửi Origin. Private key/PIN không đi vào PWA: chọn chứng thư, xác nhận quyền website và nhập PIN diễn ra trong ứng dụng ký số native.

Profile chung ký toàn bộ document. Những schema cơ quan yêu cầu XPath, ID hoặc vị trí chữ ký riêng vẫn cần integration chuyên biệt.

Cấu trúc

app/                    React UI và engine TypeScript
  lib/xml.ts            import/export XML + bảng động
  lib/storage.ts        IndexedDB/localStorage
  lib/signer.ts         HTTP DSS-X/XAdES signing adapter
  lib/calculations.ts   rule tính tự động đã port
public/data/forms/      catalog/form-pack sinh tự động
scripts/                tái dựng MSI, compiler catalog và workbook rules
legacy/installed-tree/  nguồn HTKK cục bộ để tái sinh catalog (không lưu trên Git)
tests/                  test SSR, catalog, PWA, validation, XML round-trip

Giới hạn tương thích nghiệp vụ

“100% tài nguyên/catalog” không đồng nghĩa “100% hành vi nghiệp vụ”. Toàn bộ 223 workbook biểu mẫu đã được trích rule, nhưng các hàm Excel phức tạp và hàng nghìn method trong TAX.HTKK.Business.dll vẫn cần tiếp tục port theo từng phiên bản, rồi đối chiếu bằng golden test với HTKK Windows trước khi dùng để nộp hồ sơ thật. Ứng dụng hiện hiển thị đúng nguồn/coverage thay vì âm thầm thay thế bằng template phiên bản khác.