Invoice Service

@nx/invoice phát hành hoá đơn điện tử Việt Nam. Nó phản ứng với sự kiện thanh toán từ sale và CDC merchant, dựng payload nhà cung cấp từ dữ liệu đơn hàng + thuế, và điều phối phát hành qua hai lớp adapter nhà cung cấp (@nx/iiapi, @nx/t-van) trên một pipeline BullMQ 3 phân vùng với phát hành theo lô định kỳ và tự khai báo từ người mua.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/invoice
Code	SVC-00150-INVOICE (đã đăng ký trong ServiceCodes của core; Kafka client id mặc định SVC-00150-INVOICE_CONSUMER)
Type	Microservice
Runtime	Bun
Base Class	VerifierApplication
Location	packages/invoice
Base Path	/v1/api (không có segment riêng cho service)
Dev Port	1190 ⚠️ (các service khác dùng 310x0)
Local nginx upstream	invoice_upstream → 127.0.0.1:31140 (packages/gateway/local/nginx.conf)
Snowflake ID	chưa đặt ⚠️ (APP_ENV_..._WORKER_ID chưa cấu hình)
DB Schema	invoice (8 bảng) + tax (TaxInfo, dùng chung)
Binding Namespace	@nx/invoice
Owner	invoice-team

⚠️ Định danh service bị lệch/chưa đặt. Cần đối chiếu một SVC code duy nhất, snowflake id, và một port 310x0 trước khi deploy production. Xem Operations.

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Phát hành HĐĐT VN (VAT, sale, POS, vé, xuất nội bộ)	Thu tiền thanh toán (thuộc @nx/payment / @nx/mq-pay)
Đa nhà cung cấp qua iiapi (VNIS, VNPAY) + T-VAN	Vòng đời đơn hàng (thuộc @nx/sale)
Phát hành theo thanh toán + định kỳ + thủ công + tự khai báo từ người mua	Nhập thông tin thuế merchant (nhập trong @nx/commerce metadata.tax)
Điều chỉnh / thay thế / huỷ hoá đơn đã phát hành	Cơ quan đăng ký mã số thuế (do GDT cấp)
Người mua tự khai báo (token + QR + hết hạn)	Pipeline render PDF (phía nhà cung cấp)
Hồ sơ hoá đơn merchant + lưu trữ an toàn credential nhà cung cấp	—

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, DI, base class, ControllerFactory
hono	HTTP server (qua IGNIS)
drizzle-orm	Truy cập DB qua PostgresCoreDataSource
@platformatic/kafka	Kafka consumer (PAYMENT_SUCCESS, Merchant CDC)
bullmq	Queue phát hành bất đồng bộ phân vùng + hết hạn claim
ioredis	Backing store BullMQ + WebSocket emitter
zod	Validate request/response

Nội bộ:

Package	Mục đích
@nx/core	Toàn bộ schema Invoice/TaxInfo, repository, KafkaTopics/CDCKafkaTopics, kiểu Debezium, VerifierApplication, createAppConfig
@nx/iiapi	Lớp adapter HĐĐT (VNIS + VNPAY); IIAPIProviders
@nx/t-van	Lớp adapter cổng T-VAN; TVanProviders
@nx/mq-pay	Hợp đồng thông điệp payment-success

4. Cấu trúc dự án

packages/invoice/
├── src/
│   ├── application.ts          # Lớp con VerifierApplication
│   ├── index.ts                # Entry → bootstrapApplication()
│   ├── migrate.ts              # Entry migration → bootstrapMigration()
│   ├── common/                 # RestPaths, queues, websocket, providers (iiapi mapper), constants
│   ├── components/             # kafka-consumer, invoice-queue, websocket, redis, cron,
│   │                           #   invoice-provider-connection (iiapi), tvan-connection (t-van)
│   ├── controllers/            # 11 REST controller + definitions
│   ├── datasources/            # Binding PostgresCoreDataSource
│   ├── migrations/             # Seed: dữ liệu hành chính VN, configs, webhook configs, permissions
│   ├── models/                 # Schema request/response (zod)
│   ├── repositories/           # Re-export từ @nx/core (+ TransactionRepository)
│   ├── services/               # 22 service (issuance, worker, queue, provider, claim, tax-info)
│   └── utilities/              # Mã hoá, validate mã số thuế, chuyển số thành chữ VN
├── package.json
└── tsconfig.json

5. Kiến trúc

Chi tiết: xem Architecture.

6. Ảnh chụp Domain

ERD đầy đủ + bảng từng entity: xem Domain Model.

7. Tổng quan bề mặt

REST controller (tham chiếu đầy đủ render trực tiếp từ /doc/openapi.json của service — xem Operations):

Controller	Base path	Ghi chú
InvoiceController	/invoices	phát hành / điều chỉnh / huỷ / liệt kê
InvoiceRequestController	/invoice-requests	thu thập thông tin người mua
InvoiceProviderController	/invoice-providers	credential theo merchant
InvoiceProviderConfigController	/invoice-provider-configs	serial + chính sách phát hành
InvoiceConfigMappingController	/invoice-config-mappings	định tuyến principal → config
MerchantInvoiceProfileController	/merchant-invoice-profiles	đăng ký merchant
TaxInfoController	/tax-infos	định danh thuế người bán/người mua
InvoiceOnboardingController	/invoice-onboarding	luồng đăng ký có hướng dẫn
BuyerClaimController	/invoice-claim	người mua tự khai báo
VnAddressController	/vn-address	tra cứu đơn vị hành chính VN
WebhookController	/webhooks	callback VNPAY/iiapi + commerce

Async topic (tham chiếu đầy đủ tại API Events):

Hướng	Số lượng
Inbound (Kafka)	2 — PAYMENT_SUCCESS, Merchant CDC
Outbound (Kafka)	0
WebSocket out	1 — cập nhật trạng thái hoá đơn
BullMQ jobs in	2 — phát hành (+kiểu phụ adjustment), hết hạn claim
BullMQ jobs out	tự enqueue (phát hành, retry, hết hạn claim)

8. Components

Component	File	Mục đích
KafkaConsumerComponent	src/components/kafka-consumer/component.ts	Subscribe PAYMENT_SUCCESS + Merchant CDC → InvoiceWorkerService
InvoiceQueueComponent	src/components/invoice-queue/component.ts	BullMQ: 3 phân vùng ×
InvoiceWebSocketComponent	src/components/websocket/component.ts	WS trạng thái phát hành trực tiếp (Redis emitter)
InvoiceProviderConnectionComponent	src/components/invoice-provider-connection/component.ts	Đăng ký VNIS + provider theo merchant với @nx/iiapi
TVanConnectionComponent	src/components/tvan-connection/component.ts	Đăng ký client T-VAN với @nx/t-van
RedisComponent	src/components/redis/component.ts	Redis dùng chung (queue + emitter)
CronComponent	src/components/cron/component.ts	Phát hành theo lô định kỳ

9. Services

22 service. Điểm nổi bật bên dưới; phân lớp đầy đủ tại Architecture.

Service	File	Tóm tắt
InvoiceIssuanceService	src/services/invoice-actions/invoice-issuance.service.ts	Dựng payload từ đơn hàng + TaxInfo, gọi adapter, ghi audit
InvoiceAdjustmentService	src/services/invoice-actions/invoice-adjustment.service.ts	Hoá đơn điều chỉnh sau phát hành
InvoiceCancellationService	src/services/invoice-actions/invoice-cancellation.service.ts	Huỷ hoá đơn đã phát hành
InvoiceResolveService	src/services/invoice-actions/invoice-resolve.service.ts	Đối chiếu trạng thái nhà cung cấp/cơ quan thuế
InvoiceIssuanceQueueService	src/services/invoice-issuance-queue.service.ts	Enqueue + xử lý phát hành/hết hạn claim; chính sách retry
InvoiceWorkerService	src/services/invoice-worker.service.ts	Kafka handler: handlePaymentSuccess, handleMerchantCDC
InvoiceScheduledIssuanceService	src/services/invoice-scheduled-issuance.service.ts	Phát hành theo lô bằng cron
InvoiceProviderService	src/services/invoice-provider.service.ts	Credential nhà cung cấp (đã mã hoá)
InvoiceProviderConfigService	src/services/invoice-provider-config.service.ts	Serial + chính sách phát hành
InvoiceConfigMappingService	src/services/invoice-config-mapping.service.ts	Định tuyến principal → config
InvoiceRequestService	src/services/invoice-request.service.ts	Vòng đời invoice-request
MerchantInvoiceProfileService	src/services/merchant-invoice-profile.service.ts	Đăng ký merchant
InvoiceOnboardingService	src/services/invoice-onboarding.service.ts	Luồng onboarding có hướng dẫn
TaxInfoService	src/services/tax-info.service.ts	Đồng bộ TaxInfo có thẩm quyền (nguồn CDC)
BuyerClaimService / BuyerClaimDeliveryService	src/services/buyer-claim*.service.ts	Token claim, QR, gửi
CommerceWebhookService	src/services/commerce-webhook.service.ts	Handler webhook commerce inbound
VNPAYInvoiceService / VNPAYInvoiceWebhookService	src/services/third-parties/*.ts	Phát hành VNPAY + webhook inbound
InvoiceSocketEventService	src/services/invoice-socket-event.service.ts	Phát sự kiện WS trạng thái hoá đơn
VnAddressService	src/services/vn-address.service.ts	Tra cứu đơn vị hành chính VN
AuthorizationService	src/services/authorization.service.ts	Kiểm tra truy cập ở mức merchant

10. Repositories

Toàn bộ schema + repository thuộc @nx/core; service này chỉ re-export và đăng ký (cộng thêm TransactionRepository cục bộ).

Repository	Bảng	Nguồn
InvoiceRepository	invoice.Invoice	@nx/core
InvoiceRequestRepository	invoice.InvoiceRequest	@nx/core
InvoiceIssuanceRepository	invoice.InvoiceIssuance	@nx/core
InvoiceAuditTracingRepository	invoice.InvoiceAuditTracing	@nx/core
InvoiceProviderRepository	invoice.InvoiceProvider	@nx/core
InvoiceProviderConfigRepository	invoice.InvoiceProviderConfig	@nx/core
InvoiceConfigMappingRepository	invoice.InvoiceConfigMapping	@nx/core
MerchantInvoiceProfileRepository	invoice.MerchantInvoiceProfile	@nx/core
TaxInfoRepository	tax.TaxInfo	@nx/core
Vn*Repository	Vn{Province,Ward,AdministrativeUnit}	@nx/core

Bảng trường đầy đủ: xem Domain Model.

11. Entry Points

File	Mục đích
src/index.ts	Entry service → bootstrapApplication()
src/migrate.ts	Entry migration → bootstrapMigration()
src/application.ts	Application kế thừa VerifierApplication

Chế độ chạy: api, worker (BullMQ + hết hạn claim), migrate.

12. Configuration

Env var + feature flag + dữ liệu seed: xem Configuration.

13. Operations

Deployment + observability + bảo mật + runbook: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Decisions
• Tính năng: Numbering · Digital Signature · PDF Generation · T-VAN Integration · XML Format
• REST endpoint — OpenAPI trực tiếp tại /doc/openapi.json của invoice service