Operations

1. Deployment

Thuộc tính	Giá trị
Image	registry/taxation:<tag> (build từ packages/taxation/Dockerfile)
Container Port	3000 (external 31130)
Replicas	1 (Snowflake worker id 13 hardcode — xem cảnh báo)
Probes	GET /healthz (live), GET /readyz (ready)
Snowflake ID	13 (APP_ENV_SNOWFLAKE_WORKER_ID)
Run modes	RUN_MODE=startup (app + CDC consumer) · RUN_MODE=migrate (seed)
Migration mode	job bun run migrate chạy-một-lần trước/khi boot

Cảnh báo scale: worker id 13 hardcode trong env. Chạy >1 replica rủi ro collision Snowflake id. Nhiều replica cũng mỗi cái chạy một CDC consumer trong cùng group — rebalance partition áp dụng, nhưng nguy cơ id là blocker.

Traefik labels

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.taxation.rule=PathPrefix(`/v1/api/taxation`)"
  - "traefik.http.services.taxation.loadbalancer.server.port=3000"

2. Observability

Signal	Nguồn	Nơi xem
Logs	stdout (key-value có cấu trúc)	kubectl logs <pod> / Loki
Health	GET /healthz, GET /readyz	Gateway portal
Metrics	không có riêng cho package	—
Traces	không có	—

Dòng log quan trọng

Scope	Dòng đáng chú ý
ApplicationKafkaComponent	Connected/Disconnected to broker, Received message | Topic | Partition | Offset, Error processing message
TaxationWorkerService	Handling product CDC | OP | After, DONE product CDC reconcile (provisioned/deprovisioned)
TaxProvisioningService	START/DONE provision, SKIP provision — already provisioned, DEACTIVATED existing TaxSet
TaxGroupService	VALIDATED | TaxGroup ... for Merchant ...

3. Security

Mối quan tâm	Biện pháp
AuthN	JWT (ES256, JWKS từ identity) + HTTP Basic; strategies: ['jwt','basic'] trên mọi route
AuthZ	Permission resource-based seed theo từng controller; cấp baseline cho OWNER/EMPLOYEE/CASHIER
Secrets	mount qua env (APP_ENV_POSTGRES_PASSWORD, Kafka SASL creds); không bao giờ trong code
Kafka	SASL SCRAM-SHA-512
Soft-delete	deletedAt — không hard-delete; deprovision dùng status DEACTIVATED
Không audit trail	Thay đổi config thuế không được audit (khác với InvoiceAuditTracing của invoice)

4. Runbook

4.1 Lớp Alert

Alert	Trigger	Check	Fix	Escalate
taxationCDCLag	sản phẩm cập nhật nhưng không có thay đổi TaxSet	log Received message, lag consumer group	restart consumer; verify broker	on-call backend
taxationProvisionErrors	lỗi TaxGroup not found / has no items	log level=error trong provisioning	verify seed đã chạy (migrate); check tính hợp lệ taxGroupId	on-call backend
taxationMissingBackfill	sản phẩm tạo khi consumer down hiện không có thuế	—	POST /tax-provisioning/provision thủ công theo từng sản phẩm	on-call backend

4.2 Thao tác thường gặp

Thao tác	Lệnh
Tail log	kubectl logs -n <ns> -f deploy/taxation
Re-run seed	bun run migrate (trong pod, RUN_MODE=migrate)
Provision thủ công	POST /v1/api/taxation/tax-provisioning/provision { productId, taxGroupId }
Deprovision thủ công	POST /v1/api/taxation/tax-provisioning/deprovision { productId }
Replay product CDC	re-trigger một product update trong commerce (không có replay job tích hợp)

Không có CDC backfill. fallbackMode: latest nghĩa là sản phẩm thay đổi trước cửa sổ offset của consumer không bao giờ được reprocess. Phục hồi qua endpoint provisioning thủ công hoặc bằng cách lưu lại sản phẩm trong commerce.

5. Trang liên quan

• Configuration
• /runbook/ — runbook trung tâm cho sự cố cross-service
• Decisions