Taxation Service

@nx/taxation sở hữu các template tax-rule TaxGroup/TaxGroupItem và cung cấp chúng lên sản phẩm dưới dạng các dòng TaxSet + Tax, phản ứng với thay đổi sản phẩm qua Debezium CDC. Nó cũng phục vụ đơn vị hành chính, tỉnh, và phường Việt Nam dạng read-only. Pricing tiêu thụ TaxSet đã cung cấp; invoice là consumer thuế downstream.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/taxation
Code	SVC-00130-TAXATION
Loại	Microservice
Runtime	Bun
Base Class	VerifierApplication
Vị trí	packages/taxation
Base Path	/v1/api/taxation
Dev Port	31130
Container Port	3000 (external 31130)
Snowflake ID	13
DB Schema	tax (TaxGroup, TaxGroupItem, Vn* refs) + pricing (TaxSet, Tax, TaxType) — tất cả do @nx/core sở hữu
Binding Namespace	@nx/taxation
Owner	taxation-team

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

Bao gồm	Không bao gồm
CRUD template TaxGroup/TaxGroupItem	Tính tax-rate lúc bán (@nx/pricing)
Provision/deprovision TaxSet + Tax lên sản phẩm	Định danh thuế seller/buyer TaxInfo (commerce → invoice)
CDC reconcile khi tạo/cập nhật/xóa sản phẩm	Override thuế cấp variant (tạo thủ công, sourceType chưa set)
Validate tương thích merchant taxMethod ↔ group	Seed dữ liệu tham chiếu VN (load bên ngoài)
Tỉnh / phường / đơn vị hành chính VN read-only	Phát hành hóa đơn (@nx/invoice)

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, DI, BaseService, BaseRestController, ControllerFactory
hono	Framework HTTP server (qua IGNIS)
drizzle-orm	Truy cập DB qua PostgresCoreDataSource
@platformatic/kafka	Kafka consumer + (de)serializer key/value
@venizia/ignis-helpers	KafkaConsumerHelper, truy cập env, getError/HTTP, dayjs
zod	Validate request schema (controller provisioning)

Nội bộ:

Package	Mục đích
@nx/core	TẤT CẢ Drizzle schema, repository, VerifierApplication, hằng số CDC topic, TProductPgRow/TDebeziumMessage

Phụ thuộc nội bộ duy nhất là @nx/core. Package này không khai báo schema riêng.

4. Cấu trúc Project

packages/taxation/
├── src/
│   ├── application.ts          # Lớp Application (VerifierApplication)
│   ├── index.ts                # Entry → bootstrapApplication()
│   ├── migrate.ts              # Migration entry → bootstrapMigration()
│   ├── common/                 # BindingKeys, RestPaths
│   ├── components/kafka/        # CDC consumer trên CDCKafkaTopics.PRODUCT
│   ├── controllers/            # 6 REST controller + permission defs
│   ├── datasources/            # PostgresCoreDataSource binding
│   ├── migrations/processes/   # Seed (discrimination types, groups, perms, role-perms)
│   ├── repositories/           # Lớp con Repository trên schema @nx/core
│   ├── resources/              # app-info.json, banner
│   └── services/               # TaxGroup, TaxProvisioning, TaxationWorker
├── package.json
└── tsconfig.json

5. Architecture

Chi tiết: xem Architecture.

6. Snapshot Domain

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

7. Tổng quan bề mặt

REST controllers (tham chiếu đầy đủ render trực tiếp từ /v1/api/taxation/doc/openapi.json):

Controller	Base path	Style	Endpoints
TaxGroupController	/tax-groups	ControllerFactory CRUD	8
TaxGroupItemController	/tax-group-items	ControllerFactory CRUD	8
TaxProvisioningController	/tax-provisioning	Custom (provision/deprovision)	2
VnProvinceController	/vn-provinces	Read-only	—
VnWardController	/vn-wards	Read-only	—
VnAdministrativeUnitController	/vn-administrative-units	Read-only	—

Async topics (tham chiếu đầy đủ trong API Events):

Hướng	Số lượng
Inbound (Kafka CDC)	1 (public.Product)
Outbound (Kafka)	0
WebSocket out	0
BullMQ jobs in/out	0

8. Components

Component	File	Mục đích
ApplicationKafkaComponent	src/components/kafka/component.ts	Subscribe CDCKafkaTopics.PRODUCT (Debezium), fallbackMode: latest, route payload tới TaxationWorkerService.handleProductCDC

9. Services

Service	File	Mô tả ngắn
TaxGroupService	src/services/tax-group.service.ts	Validate TaxGroup.taxMethod theo merchant taxMethod; tìm group theo method
TaxProvisioningService	src/services/tax-provisioning.service.ts	Provision/deprovision idempotent TaxSet + Tax từ một template TaxGroup
TaxationWorkerService	src/services/taxation-worker.service.ts	Logic CDC consumer: c/u/r → reconcile, d → deprovision

10. Repositories

Đăng ký trong application.ts. Tất cả extend repository @nx/core trên schema do core sở hữu.

Repository	Bảng	Nguồn	Method tùy chỉnh
TaxGroupRepository	tax.TaxGroup	@nx/core	—
TaxGroupItemRepository	tax.TaxGroupItem	@nx/core	—
TaxTypeRepository	pricing.TaxType	@nx/core	—
TaxSetRepository	pricing.TaxSet	@nx/core	findActiveTaxSetByPrincipal
TaxRepository	pricing.Tax	@nx/core	—
VnProvinceRepository	tax.VnProvince	@nx/core	—
VnWardRepository	tax.VnWard	@nx/core	—
VnAdministrativeUnitRepository	tax.VnAdministrativeUnit	@nx/core	—
DiscriminationTypeRepository	DiscriminationType	@nx/core	—
MigrationRepository, PermissionRepository, PolicyDefinitionRepository, RoleRepository	infra	@nx/core	—

11. Entry Points

File	Mục đích
src/index.ts	Service entry → bootstrapApplication()
src/migrate.ts	Migration entry → bootstrapMigration()
src/application.ts	Lớp Application extends VerifierApplication

12. Configuration

Env vars + feature flags + dữ liệu seed: xem Configuration.

13. Operations

Deployment + observability + security + runbook: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Decisions
• REST endpoints — OpenAPI trực tiếp tại /v1/api/taxation/doc/openapi.json
• Pricing — tiêu thụ TaxSet/Tax đã cung cấp
• Commerce — nguồn CDC thay đổi sản phẩm