Bếp ăn Học đường & Nutrition Engine (BAHD)

Phân hệ Bếp ăn Học đường (BAHD) kết nối trực tiếp Supply Chain Traceability (TXNG) vào Bếp ăn trường học, tích hợp Cơ sở dữ liệu Dinh dưỡng (FAO / Viện Dinh dưỡng Quốc gia), Nutrition Engine, Cost Reconciliation Engine, và Parent Portal.

1. BAHD End-to-End Architecture

Rendering diagram...

2. Phân tích Chi tiết 18 Modules trong Phân hệ BAHD

2.1. Cafeteria Profile & Nutrition Master Data

Module (`apps/backend/src/modules/*`)	Endpoint chính (`/api/v1/*`)	Chức năng & Core Logic
`school-cafeterias`	`/school-cafeterias`	Quản lý hồ sơ bếp ăn trường học (mã tự sinh `BAHD-{PROVINCE}-{SEQ}` dùng Transactional Advisory Lock `pg_advisory_xact_lock(910000 + provinceId)`), mô hình vận hành (Tự nấu, Suất ăn công nghiệp, Liên kết), công suất phục vụ, danh sách nhà cung cấp liên kết và giấy chứng nhận ATTP.
`food-composition`	`/food-composition/items`, `/food-groups`, `/nutrient-codes`	Cơ sở dữ liệu Bảng thành phần thực phẩm Việt Nam (Năng lượng kcal, Protein, Lipid, Glucid, Chất xơ, Vitamin A/B1/B2/C/D, Canxi, Sắt, Kẽm, Natri...), tỷ lệ phần ăn được (`edible_portion`) và hệ số giữ lại dưỡng chất sau chế biến (`retention_factor`).
`rda-standards`	`/rda-standards`	Quản lý ngưỡng dinh dưỡng khuyến nghị (Recommended Dietary Allowances — RDA) phân theo nhóm tuổi/cấp học (Mầm non, Tiểu học, THCS, THPT) và bữa ăn (Bữa trưa, Bữa phụ), bao gồm tỷ lệ cân đối năng lượng từ P : L : G (Protein : Lipid : Glucid).

2.2. Menu Planning, Recipes & Nutrition Engine (`nutrition-engine`)

Module (`apps/backend/src/modules/*`)	Endpoint chính (`/api/v1/*`)	Chức năng & Core Logic
`menu-recipes`	`/menu-recipes`	Xây dựng định lượng nguyên liệu chuẩn cho 1 khẩu phần món ăn (gram nguyên liệu sống → gram chín), liên kết từng nguyên liệu với `FoodCompositionItem`.
`menu-planning` & `meal-sets`	`/menu-planning`, `/meal-sets`	Lập thực đơn theo tuần/tháng cho từng nhóm tuổi, ghép các món ăn (Món mặn, Món xào, Canh, Cơm, Tráng miệng) thành `MealSet` và kiểm tra rule chống lặp món trong tuần.
`nutrition-engine`	`/nutrition-balance`, `/nutrition-thresholds`, `/recipe-nutrition`	Core Nutrition Engine của BAHD: 1. `RecipeNutritionService`: Tính tổng hàm lượng từng dưỡng chất của món ăn theo công thức: `NetNutrient = Σ [ (PurchaseWeight_i × (1 - WasteRatio_i) / 100) × NutrientPer100g_i × RetentionFactor_i ]` 2. `NutritionBalanceService`: So sánh tổng dinh dưỡng của thực đơn ngày/tuần với chuẩn `RdaStandard` và `NutritionThreshold`, đánh giá trạng thái (`BALANCED`, `DEFICIENT`, `EXCESS`), đồng thời sinh gợi ý điều chỉnh khẩu phần (`suggestions/:id/apply` hoặc `dismiss`).

2.3. Kitchen Processing, Cost Norms & Cost Reconciliation Engine

Module (`apps/backend/src/modules/*`)	Endpoint chính (`/api/v1/*`)	Chức năng & Core Logic
`ingredient-demands` & `meal-processing-orders`	`/ingredient-demands`, `/meal-processing-orders`	Từ số lượng suất ăn thực tế trong ngày và định lượng thực đơn, tự động tính toán Bảng dự trù nguyên liệu (`IngredientDemand`) và Lệnh chế biến bếp ăn (`MealProcessingOrder`), gắn trực tiếp với các lô nguyên liệu (`Batch` / `InputSource`) đã nhập từ nhà cung cấp để khép kín chuỗi traceability từ vùng nguyên liệu tới bàn ăn học sinh.
`meal-cost-norms` & `meal-cost-sheets`	`/meal-cost-norms`, `/meal-cost-sheets`	Quản lý định mức chi phí mỗi suất ăn (`MealCostNorm`, mã `MCN-xxxxx` với Advisory Lock `920001`) gồm cơ cấu chi phí thực phẩm, nhiên liệu, nhân công; tự động lập Bảng tính chi phí suất ăn hàng ngày (`MealCostSheet`, mã `MCS-YYYYMMDD-xxxx` với Advisory Lock `920002`) từ giá nhập thực tế của các lô nguyên liệu xuất bếp.
`finance-ledgers`, `finance-thresholds`, `cost-reconciliations`	`/finance-ledgers`, `/finance-thresholds`, `/cost-reconciliations`	Ghi nhận sổ thu/chi tài chính bếp ăn (`FinanceLedger`), đối soát tự động giữa Norm Cost — Sheet Cost — Actual Ledger Cost (`CostReconciliation`), và kích hoạt cảnh báo khi tỷ lệ chi thực phẩm lệch khỏi ngưỡng (`FinanceThreshold`).
`cost-disclosures`	`/cost-disclosures`	Phát hành bản công khai tài chính suất ăn (`PCD-YYYYMMDD-xxxx` kèm mã public lookup 8 ký tự Base32 Crockford với Advisory Lock `920003`) để phụ huynh tra cứu minh bạch cơ cấu tiền ăn.

2.4. Daily Menu QR & Parent Portal (`TXNG-F52`)

Module (`apps/backend/src/modules/*`)	Endpoint chính (`/api/v1/*`)	Chức năng & Business Rules
`menu-qr` & `public-menu-trace`	`/menu-qr`, `/public/menu-trace/:code`	Mỗi ngày bếp ăn phát hành một mã QR thực đơn (`MenuQrCode`). Khi phụ huynh quét mã QR, `PublicMenuTraceController` trả về: Danh sách món ăn + ảnh thực tế suất ăn, bảng phân tích dinh dưỡng đạt chuẩn RDA, nguồn gốc từng batch nguyên liệu chế biến trong ngày, kết quả lab test (`lab-tests`) và giấy chứng nhận ATTP của các nhà cung cấp (`certification-shares`).
`parent-portal` & `parent-rep`	`/public/parent-feedbacks`, `/parent-feedbacks`, `/parent-rep`, `/scan-stats`	Cho phép phụ huynh và Ban đại diện Cha mẹ học sinh (`ParentRep`) gửi đánh giá/phản ánh trực tiếp kèm tối đa 3 ảnh minh chứng (`FB-{YYYYMMDD}-{SEQ4}`, dùng Advisory Lock `920052`). - Kiểm soát tuân thủ NĐ 13/2023/NĐ-CP (`E-F52-204`: bắt buộc tích `consent_flag = true` nếu phụ huynh điền họ tên hoặc số điện thoại). - Quản lý State Machine xử lý phản ánh: `REPORTED` → `INVESTIGATING` → `RESOLVED` → `CLOSED`. - Nếu phản ánh thuộc nhóm sự cố ATTP nghiêm trọng, hệ thống tự động route sang luồng cảnh báo sự cố (`routed_to_incident = true` qua `ThresholdEventsService`).