Invoice Service

@nx/invoice issues Vietnamese electronic invoices. It reacts to sale-payment events and merchant CDC, builds provider payloads from order + tax data, and drives issuance through two provider-adapter layers (@nx/iiapi, @nx/t-van) over a 3-partition BullMQ pipeline with scheduled batch issuance and buyer-claim self-service.

1. Quick Reference

Property	Value
Package	@nx/invoice
Code	SVC-00150-INVOICE (registered in core ServiceCodes; Kafka client id defaults to SVC-00150-INVOICE_CONSUMER)
Type	Microservice
Runtime	Bun
Base Class	VerifierApplication
Location	packages/invoice
Base Path	/v1/api (no per-service segment)
Dev Port	1190 ⚠️ (others use 310x0)
Local nginx upstream	invoice_upstream → 127.0.0.1:31140 (packages/gateway/local/nginx.conf)
Snowflake ID	unset ⚠️ (APP_ENV_..._WORKER_ID not configured)
DB Schema	invoice (8 tables) + tax (TaxInfo, shared)
Binding Namespace	@nx/invoice
Owner	invoice-team

⚠️ Service identity is drifted/unset. Reconcile a unique SVC code, snowflake id, and a 310x0 port before production deploy. See Operations.

2. Purpose & Scope

Included	Excluded
Issue VN e-invoices (VAT, sale, POS, ticket, internal-delivery)	Payment capture (owned by @nx/payment / @nx/mq-pay)
Multi-provider via iiapi (VNIS, VNPAY) + T-VAN	Order lifecycle (owned by @nx/sale)
Payment-driven + scheduled + manual + buyer-self-service issuance	Merchant tax-info input (entered in @nx/commerce metadata.tax)
Adjustment / replacement / cancellation of issued invoices	Authoritative tax-code registry (issued by GDT)
Buyer self-service claim (token + QR + expiry)	PDF rendering pipeline (provider-side)
Merchant invoice profile + provider credential vaulting	—

3. Tech Stack

External:

Library	Purpose
@venizia/ignis	IoC container, DI, base classes, ControllerFactory
hono	HTTP server (via IGNIS)
drizzle-orm	DB access via PostgresCoreDataSource
@platformatic/kafka	Kafka consumer (PAYMENT_SUCCESS, Merchant CDC)
bullmq	Partitioned async issuance + claim-expiry queues
ioredis	BullMQ backing store + WebSocket emitter
zod	Request/response validation

Internal:

Package	Purpose
@nx/core	All Invoice/TaxInfo schemas, repositories, KafkaTopics/CDCKafkaTopics, Debezium types, VerifierApplication, createAppConfig
@nx/iiapi	E-invoice adapter layer (VNIS + VNPAY); IIAPIProviders
@nx/t-van	T-VAN gateway adapter layer; TVanProviders
@nx/mq-pay	Payment-success message contract

4. Project Structure

packages/invoice/
├── src/
│   ├── application.ts          # VerifierApplication subclass
│   ├── index.ts                # Entry → bootstrapApplication()
│   ├── migrate.ts              # Migration entry → 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 controllers + definitions
│   ├── datasources/            # PostgresCoreDataSource binding
│   ├── migrations/             # Seeds: VN admin data, configs, webhook configs, permissions
│   ├── models/                 # Request/response schemas (zod)
│   ├── repositories/           # Re-exports from @nx/core (+ TransactionRepository)
│   ├── services/               # 22 services (issuance, worker, queue, provider, claim, tax-info)
│   └── utilities/              # Encryption, tax-code validation, VN number-to-words
├── package.json
└── tsconfig.json

5. Architecture

Detail: see Architecture.

6. Domain Snapshot

Full ERD + per-entity tables: see Domain Model.

7. Surface Summary

REST controllers (full reference rendered live from the service's /doc/openapi.json — see Operations):

Controller	Base path	Notes
InvoiceController	/invoices	issue / adjust / cancel / list
InvoiceRequestController	/invoice-requests	buyer-info capture
InvoiceProviderController	/invoice-providers	per-merchant credentials
InvoiceProviderConfigController	/invoice-provider-configs	serial + issuance policy
InvoiceConfigMappingController	/invoice-config-mappings	principal → config routing
MerchantInvoiceProfileController	/merchant-invoice-profiles	merchant enrollment
TaxInfoController	/tax-infos	seller/buyer tax identity
InvoiceOnboardingController	/invoice-onboarding	guided enrollment flow
BuyerClaimController	/invoice-claim	buyer self-service claim
VnAddressController	/vn-address	VN administrative-unit lookup
WebhookController	/webhooks	VNPAY/iiapi + commerce callbacks

Async topics (full reference in API Events):

Direction	Count
Inbound (Kafka)	2 — PAYMENT_SUCCESS, Merchant CDC
Outbound (Kafka)	0
WebSocket out	1 — invoice status updates
BullMQ jobs in	2 — issuance (+adjustment sub-type), claim-expiry
BullMQ jobs out	self-enqueued (issuance, retry, claim-expiry)

8. Components

Component	File	Purpose
KafkaConsumerComponent	src/components/kafka-consumer/component.ts	Subscribes PAYMENT_SUCCESS + Merchant CDC → InvoiceWorkerService
InvoiceQueueComponent	src/components/invoice-queue/component.ts	BullMQ: 3 partitions ×
InvoiceWebSocketComponent	src/components/websocket/component.ts	Live issuance-status WS (Redis emitter)
InvoiceProviderConnectionComponent	src/components/invoice-provider-connection/component.ts	Registers VNIS + per-merchant providers with @nx/iiapi
TVanConnectionComponent	src/components/tvan-connection/component.ts	Registers T-VAN client with @nx/t-van
RedisComponent	src/components/redis/component.ts	Shared Redis (queue + emitter)
CronComponent	src/components/cron/component.ts	Scheduled batch issuance

9. Services

22 services. Highlights below; full layering in Architecture.

Service	File	One-liner
InvoiceIssuanceService	src/services/invoice-actions/invoice-issuance.service.ts	Build payload from order + TaxInfo, call adapter, record audit
InvoiceAdjustmentService	src/services/invoice-actions/invoice-adjustment.service.ts	Post-issuance adjustment invoice
InvoiceCancellationService	src/services/invoice-actions/invoice-cancellation.service.ts	Cancel issued invoice
InvoiceResolveService	src/services/invoice-actions/invoice-resolve.service.ts	Reconcile provider/tax-authority status
InvoiceIssuanceQueueService	src/services/invoice-issuance-queue.service.ts	Enqueue + process issuance/claim-expiry; retry policy
InvoiceWorkerService	src/services/invoice-worker.service.ts	Kafka handlers: handlePaymentSuccess, handleMerchantCDC
InvoiceScheduledIssuanceService	src/services/invoice-scheduled-issuance.service.ts	Cron batch issuance
InvoiceProviderService	src/services/invoice-provider.service.ts	Provider credentials (encrypted)
InvoiceProviderConfigService	src/services/invoice-provider-config.service.ts	Serial + issuance policy
InvoiceConfigMappingService	src/services/invoice-config-mapping.service.ts	Principal → config routing
InvoiceRequestService	src/services/invoice-request.service.ts	Invoice-request lifecycle
MerchantInvoiceProfileService	src/services/merchant-invoice-profile.service.ts	Merchant enrollment
InvoiceOnboardingService	src/services/invoice-onboarding.service.ts	Guided onboarding flow
TaxInfoService	src/services/tax-info.service.ts	Authoritative TaxInfo sync (CDC-sourced)
BuyerClaimService / BuyerClaimDeliveryService	src/services/buyer-claim*.service.ts	Claim token, QR, delivery
CommerceWebhookService	src/services/commerce-webhook.service.ts	Inbound commerce webhook handler
VNPAYInvoiceService / VNPAYInvoiceWebhookService	src/services/third-parties/*.ts	VNPAY issuance + inbound webhook
InvoiceSocketEventService	src/services/invoice-socket-event.service.ts	Emit invoice-status WS events
VnAddressService	src/services/vn-address.service.ts	VN administrative-unit lookup
AuthorizationService	src/services/authorization.service.ts	Merchant-level access checks

10. Repositories

All schemas + repositories are owned by @nx/core; this service only re-exports and registers them (plus a local TransactionRepository).

Repository	Table	Source
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

Full field tables: see Domain Model.

11. Entry Points

File	Purpose
src/index.ts	Service entry → bootstrapApplication()
src/migrate.ts	Migration entry → bootstrapMigration()
src/application.ts	Application extends VerifierApplication

Run modes: api, worker (BullMQ + claim-expiry), migrate.

12. Configuration

Env vars + feature flags + seeded data: see Configuration.

13. Operations

Deployment + observability + security + runbook: see Operations.

14. Related Pages

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Decisions
• Features: Numbering · Digital Signature · PDF Generation · T-VAN Integration · XML Format
• REST endpoints — live OpenAPI at the invoice service /doc/openapi.json