Operations

1. Deployment

Thuộc tính	Giá trị
Image	registry/taxation:<tag> (build từ packages/taxation/Dockerfile)
Container Port	3000 (external 31032)
Replicas	1 (Snowflake worker id 13 cố định cứng - 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 khi mở rộng: worker id 13 được cố định cứng trong env. Chạy hơn 1 replica có nguy cơ trùng Snowflake id. Nhiều replica cũng đều chạy một CDC consumer trong cùng group - việc cân bằng lại partition vẫn áp dụng, nhưng rủi ro trùng id mới là yếu tố cản trở.

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ó gì 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 dựa trên resource, seed theo từng controller; cấp mức cơ bản cho OWNER/EMPLOYEE/CASHIER
Secrets	mount qua env (APP_ENV_POSTGRES_PASSWORD, thông tin SASL của Kafka); không bao giờ nằm trong code
Kafka	SASL SCRAM-SHA-512
Soft-delete	deletedAt - không hard-delete; deprovision dùng status DEACTIVATED
Không có audit trail	Thay đổi cấu hình thuế không được ghi vết (khác với InvoiceAuditTracing của invoice)

4. Runbook

4.1 Nhóm cảnh báo

Alert	Trigger	Kiểm tra	Khắc phục	Escalate
taxationCDCLag	sản phẩm cập nhật nhưng không có thay đổi TaxSet	log Received message, độ trễ consumer group	restart consumer; kiểm tra broker	on-call backend
taxationProvisionErrors	lỗi TaxGroup not found / has no items	log level=error trong provisioning	xác nhận seed đã chạy (migrate); kiểm tra tính hợp lệ của taxGroupId	on-call backend
taxationMissingBackfill	sản phẩm tạo khi consumer down nay không có thuế	-	POST /tax-provisioning/provision thủ công cho từng sản phẩm	on-call backend

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

Thao tác	Lệnh
Theo dõi log	kubectl logs -n <ns> -f deploy/taxation
Chạy lại 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 }
Phát lại product CDC	kích hoạt lại một lần cập nhật product trong commerce (không có replay job có sẵn)

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 sẽ không bao giờ được xử lý lại. Khôi phục qua các 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