Integration
1. Sister Services
Direction:→calls /←called by (consumes from) /↔bidir.
| Sister | Direction | Surface | Contract | Auth | Failure Mode | Idempotency |
|---|---|---|---|---|---|---|
@nx/sale | ← | Kafka payment.success | event → RECEIPT voucher | — | at-least-once | (SALE_ORDER, attempt.uid) |
@nx/inventory | ← | Kafka purchase-order.received | event → PAYMENT voucher (party VENDOR) | — | at-least-once | (PURCHASE_ORDER, purchaseOrderId) |
@nx/inventory | ← | Kafka inventory.issued-for-sale | event → COGS ADJUSTMENT | — | at-least-once | (SALE_ORDER, attemptUid) |
@nx/inventory | ← | Kafka inventory.adjusted | event → INVENTORY ADJUSTMENT | — | at-least-once | (INVENTORY_ADJUSTMENT, inventoryTrackingId) |
@nx/commerce | ← | Debezium CDC Merchant | row → account reconciliation | — | at-least-once | account existence checks |
@nx/core | → | in-process (re-exported repos/services) | DI bindings | — | — | — |
@nx/asset | → | in-process component | VN bank reference data | — | — | — |
@nx/identity | → | HTTP — JWKS verification (VerifierApplication) | JWT (ES256) | JWT | retry / cache | request-id propagated |
Finance resolves
PurchaseOrder+Vendorvia re-exported@nx/corerepositories (same DB) to enrich the PAYMENT voucher party — there is no HTTP call to inventory.
2. External Systems
None directly. Payment-gateway credentials (VNPAY, banks, e-wallets) are stored in PaymentIntegration (encrypted) but finance does not call those gateways — @nx/mq-pay owns provider traffic. @nx/asset supplies static Vietnamese bank reference data.
3. Critical Cross-Service Flows
3.1 Sale payment → ledger income
Contract: finance only posts when the sale payload carries the chosen account (attempt.finance.source.id). Split tenders post one RECEIPT per attempt, deduped by attempt.uid.
3.2 Purchase order received → vendor payment + inventory asset
3.3 Inventory issuance/adjustment → COGS & asset posting
3.4 Merchant onboarding (CDC)
4. Contract Stability
| Surface | Stability | Versioning |
|---|---|---|
HTTP /v1/api/finance/* | stable | URL prefix /v1/ |
Kafka payment.success (consumed) | stable | payload field-additive only |
Kafka purchase-order.received (consumed) | stable | payload field-additive only |
Kafka inventory.issued-for-sale / inventory.adjusted (consumed) | stable | payload field-additive only |
Debezium Merchant CDC | follows commerce schema | column-additive |
| Outbound Kafka | none today | reserved |
5. Related Pages
- API Events
- Sale — produces
payment.success - Decisions