Finance — Subsidy

Subsidy là trợ cấp ảnh hưởng eligibility, billing/payment và reporting. Wiki đặt Subsidy dưới Finance vì OpenSpec mới có vài capability subsidy, còn nghiệp vụ chủ yếu tác động nghĩa vụ tài chính.

Khái niệm

Khái niệm	Nghĩa
SubsidyAcceptance	Bản ghi chấp thuận trợ cấp theo attendee/khoảng ngày; thường dùng để xác định eligibility.
Subsidy policy	Quy tắc áp dụng trợ cấp theo site/BU/chương trình/quốc gia.
Site licence setup	Cấu hình licence/eligibility ở site để trợ cấp có hiệu lực.
Allocation	Cách trợ cấp được gắn vào billing/invoice/payment để giảm nghĩa vụ customer phải trả.

Tương tác với domain khác

Domain	Tương tác
Booking	Có thể kiểm tra subsidy khi xác định deposit eligibility hoặc pricing context.
Payment	Deposit eligibility dùng SubsidyAcceptance theo attendee, không dựa vào trạng thái subsidy tổng quát trên account.
Billing/Invoice	Trợ cấp có thể ảnh hưởng amount, allocation và báo cáo tài chính.
Master Data	Site/BU/attendee là scope chính để xác định subsidy hợp lệ.

Quy tắc cần nhớ

• Eligibility nên dựa trên attendee và date range cụ thể.
• Nếu subsidy chỉ là config site/BU, không được coi là payment đã thu.
• Khi trợ cấp thay đổi, cần kiểm tra lại tác động tới invoice/payment/reporting thay vì chỉ sửa UI hiển thị.

Các chương trình trợ cấp

Subsidy là government welfare funding giảm chi phí childcare cho gia đình hợp lệ — không phải discount, credit note hay cơ chế internal budget. Bật theo BusinessUnit qua BusinessUnit.SubsidyTypeId.

SubsidyType	Value	Jurisdiction	Programme
NZ_OSCAR	1	New Zealand	OSCAR (Out of School Care and Recreation)
IRELAND_NCS	2	Ireland	NCS (National Childcare Scheme)
CANADA_ALBERTA	3	Canada	Alberta Child Care Subsidy

Hai đường allocation

Đường	Chương trình	Luồng
Batch allocation	OSCAR / Alberta	Upload file gov (PDF/CSV) → SubsidyBatch + SubsidyBatchLine → fuzzy match attendee/contact → staff review → ApproveAllocationAsync → SubsidyBatchLineAllocation → Payment → Xero sync
Estimation allocation	Ireland NCS	SubsidyAcceptance approved → attendance records → round hours → × rate → SubsidyEstimation + SubsidyEstimationAllocation → Invoice → Payment + Xero sync

• Batch: line amount phân bổ vào invoice account FIFO theo due date; over-allocation lưu thành overpayment, không reject (INV-SUB-13).
• Estimation: làm tròn giờ trước khi nhân rate; rule rounding None/15min/30min/Hour (ceil, không floor) (INV-SUB-05).

Ví dụ thực tế: NZ site upload file OSCAR tháng 7 → match từng child line với Attendee/Contact (OCR lệch → staff chỉnh tay) → Approve → allocation giảm AmountDue invoice theo FIFO; dư thành overpayment.

Ví dụ thực tế: BU Ireland NCS có acceptance approved (StatusId=500), attendance 90 phút, rule 15min, rate €X → round 90→90 phút rồi × rate, tạo estimation → approve mới allocation vào invoice.

Core entities

Entity	Vai trò
SubsidyBatch / SubsidyBatchLine	Batch gov tải lên + line theo từng child.
SubsidyBatchLineAllocation	Allocation line vào invoice payment.
SubsidyAcceptance	Chấp thuận trợ cấp cho 1 child; status machine định nghĩa vòng đời.
SubsidyRate / SubsidyRateLine	Rate master + line có hiệu lực theo khoảng ngày.
SubsidyEstimation / SubsidyEstimationBatch / SubsidyEstimationAllocation	Ireland NCS: ước tính theo child/period + container + allocation.
SubsidyReducedEnrolment	NZ compliance: theo dõi under-attendance.
OcrSubsidyBatch	Metadata OCR từ PDF upload; line low confidence cần staff correction (INV-SUB-11).

SubsidyAcceptance status machine

100 (Draft)     ← tạo tại Booking Confirm
  ↓
300 (Pending)   ← staff submit review
  ↓
500 (Approved)  ← staff approve; dùng cho estimation
  ↓ (hoặc từ bất kỳ state nào)
600 (Archived)

• Quan trọng: SubsidyAcceptance tạo ở Booking Confirm, không phải Submit (INV-SUB-08); Contact.SocialBenefitNumber có thể update tại confirm (INV-SUB-12).
• Chỉ StatusId = 500 mới được dùng trong estimation (INV-SUB-03); transition hợp lệ là 100 → 300 → 500 (INV-SUB-02).
• Eligibility: ProgramCategory.SubsidyEnabled == true, attendance date nằm trong [StartDate, EndDate] của acceptance, SubsidyTypeId != None.

Ví dụ thực tế: Phụ huynh confirm booking có subsidy intent → tạo SubsidyAcceptance Draft, cập nhật SocialBenefitNumber → staff duyệt → Approved; estimation chỉ chạy với acceptance Approved và attendance trong khoảng ngày.

Subsidy vs Discount

	Subsidy	Discount
Nguồn	Government	Merchant
Áp tại	Invoice level	Booking line level
Code path	Độc lập	Độc lập
Stacking	N/A	Tối đa 3 per type

Hai khái niệm hoàn toàn orthogonal: không chung code path, không có dependency thứ tự thực thi.

Site licence setup (OSCAR / Alberta)

Chỉ xuất hiện khi SubsidyTypeId là NZ_OSCAR hay CANADA_ALBERTA:

• Entry point — Settings > Finance > Subsidy hiện nút top-right: Setup SWN (OSCAR) hoặc Setup Program ID (Alberta).
• Setup page — liệt kê licence active của BU, add/edit/delete; CTA tạo chung dạng + New SWN / + New Program ID.
• Site binding — licence không gắn site (Licence.OrgId = null) hoặc gắn 1 site; mỗi site tối đa 1 licence active; đổi site → clear OrgId cũ trước khi set mới.
• Site Subsidy Settings — dropdown licence site lấy từ Licence.OrgId = site, không dùng OrgProgramCategory.SubsidyLicenceId; quick-create prefill OrgId = site nhưng cho phép bỏ trống.

Ví dụ thực tế: Admin BU OSCAR bấm Setup SWN → tạo SWN mới chưa gắn site (OrgId = null) → mở Site Subsidy Settings site S, chọn SWN đó → gán Licence.OrgId = S; chọn SWN khác thì licence cũ clear gán lại.