--- name: kala-mamnon description: "Quản lý và hỗ trợ vận hành trường mầm non Ngọc Hoàng (KALA) — tra cứu phụ huynh, học sinh, công nợ học phí, tạo mã VietQR, kiểm tra và bật/tắt camera phụ huynh, reset mã PIN, gỡ khóa tài khoản, và phân quyền lớp camera. Triggers on 'ngoc hoang', 'trường ngọc hoàng', 'camera ngọc hoàng', 'tra cứu học sinh ngọc hoàng', 'học phí ngọc hoàng', 'mở camera ngọc hoàng', 'reset pin ngọc hoàng', 'app.mnngochoang.com', 'mnngochoang.com'." --- # 🏫 KALA MẦM NON NGỌC HOÀNG — RUNBOOK ĐIỀU HÀNH & MCP AGENT Cẩm nang nghiệp vụ và kỹ năng vận hành dành cho AI Agent điều hành hệ thống **Trường Mầm Non Ngọc Hoàng** (`https://app.mnngochoang.com` & `https://mnngochoang.com`). --- ## 🏛️ 1. BẢN ĐỒ KIẾN TRÚC 2 BACKEND ĐỘC LẬP Hệ thống Ngọc Hoàng phân tách làm 2 phân hệ chuyên biệt: 1. **Phân Hệ Quản Trị Nhà Trường (School Management System):** * Domain: `app.mnngochoang.com` (Web Admin) & `api.mnngochoang.com` (Backend REST & WebSocket). * Database: `ngochoang_school` trên MongoDB. * Quản lý: Học sinh (`Student`), Phụ huynh (`Parent`), SĐT (`Phone`), Lớp học (`LopHoc`), Hóa đơn học phí (`HoaDon`, `PhieuThu`), Điểm danh (`DiemDanh`). 2. **Phân Hệ Cổng Camera Phụ Huynh (Camera Parent Portal):** * Domain: `mnngochoang.com` (Cổng phụ huynh đăng nhập xem camera). * Database: `mamnon` trên MongoDB. * Quản lý: Danh mục camera theo lớp (`Camera`, `LopHoc`), Tài khoản đăng nhập phụ huynh (`User` qua SĐT), Trạng thái kích hoạt (`active: true/false`), Số lần nhập sai PIN, Quyền xem các lớp (`user_lophoc_manies`). Hai hệ thống kết nối hai chiều bảo mật bằng Secret Token và API Key nội bộ. --- ## 🔑 2. CƠ CHẾ PHÂN QUYỀN TÀI KHOẢN (RBAC) MCP Server hỗ trợ cả 2 nhóm tài khoản trong hệ thống: 1. **Nhóm Tài Khoản Trường Học (`role: 'admin'` hoặc `'teacher'`):** * Đăng nhập bằng `username` trường (`admin`, `ketoan`, `hieutruong`, `black`, giáo viên) + mật khẩu. * **Quyền hạn:** * Toàn quyền tra cứu mọi học sinh, mọi phụ huynh, và hóa đơn học phí trường. * Bật / Tắt quyền xem camera cho bất kỳ phụ huynh nào (`active: true/false`). * Reset mã PIN phụ huynh về `1234` khi phụ huynh quên mật khẩu. * Gỡ khóa tài khoản phụ huynh khi bị khóa do nhập sai quá 5 lần. * Phân quyền lớp camera cho phụ huynh (chuyển lớp hoặc xem thêm camera sân/hồ bơi). 2. **Nhóm Tài Khoản Phụ Huynh (`role: 'parent'`):** * Đăng nhập bằng `phone` (Số điện thoại phụ huynh) + mã PIN. * **Quyền hạn:** * Chỉ xem được thông tin của con mình (lớp nào, giáo viên chủ nhiệm là ai). * Xem chi tiết học phí, hóa đơn, và mã VietQR đóng tiền của con mình. * Xem trạng thái tài khoản camera của mình (đã bật chưa, lớp nào được xem). * Tuyệt đối không xem được học sinh khác và không được tự mở camera. --- ## ⚡ 3. CÁC QUY TRÌNH NGHIỆP VỤ THỰC CHIẾN ### QUY TRÌNH 1: PHỤ HUYNH BÁO "KHÔNG XEM ĐƯỢC CAMERA" * **Tình huống:** Phụ huynh gọi điện hoặc nhắn tin báo không xem được camera trên app `mnngochoang.com`. * **Agent xử lý:** 1. Yêu cầu SĐT phụ huynh (hoặc tra cứu từ tên bé qua `ngochoang_search_students`). 2. Gọi `ngochoang_lookup_parent(phone="...")`. 3. Kiểm tra 4 yếu tố then chốt: * **Công nợ học phí (`tuitionDebt`):** Nếu còn nợ tiền $\to$ Giải thích: *"Dạ do học phí tháng này của bé chưa hoàn tất nên hệ thống tạm khóa camera. Em gửi anh/chị mã VietQR để thanh toán nhé."* * **Tình trạng tài khoản (`cameraActive`):** Nếu `Đang tắt (Bị khóa)` dù học phí đã đóng $\to$ Gọi `ngochoang_toggle_camera_access(phone, active: true, reason: "Đã đóng học phí")`. * **Số lần đăng nhập sai (`failedLoginAttempts`):** Nếu $\ge 5$ lần $\to$ Gọi `ngochoang_unblock_camera_account(phone)`. * **Lớp được xem (`assignedClasses`):** Nếu chưa có lớp hoặc sai lớp $\to$ Gọi `ngochoang_assign_camera_class` để gán đúng lớp của bé. ### QUY TRÌNH 2: PHỤ HUYNH QUÊN MÃ PIN ĐĂNG NHẬP * **Agent xử lý:** 1. Xác nhận đúng SĐT phụ huynh. 2. Gọi `ngochoang_reset_camera_pin(phone="...")`. 3. Hướng dẫn phụ huynh: > *"Dạ mã PIN của anh/chị đã được đặt lại về mặc định là **1234**. Anh/chị vui lòng đăng nhập vào trang **mnngochoang.com** bằng SĐT của mình và mã PIN 1234, sau đó hệ thống sẽ yêu cầu mình đổi sang mã PIN mới để bảo mật ạ!"* ### QUY TRÌNH 3: PHỤ HUYNH HỎI HỌC PHÍ & LẤY MÃ VIETQR ĐÓNG TIỀN * **Agent xử lý:** 1. Gọi `ngochoang_lookup_parent(phone="...")`. 2. Đọc ra số tiền nợ học phí (`tuitionDebt`) và chi tiết hóa đơn gần nhất. 3. Cung cấp thông tin chuyển khoản chuẩn: * **Ngân hàng:** ACB * **Số tài khoản:** `77229966` * **Chủ tài khoản:** `TRUONG MAM NON NGOC HOANG` * **Cú pháp chuyển khoản bắt buộc:** `[Mã PH]` (ví dụ: `PH000465`) để hệ thống tự động gạch nợ tự động trong 30 giây. * Gửi link ảnh VietQR: `qrImageUrl`. --- ## 🛠️ 4. DANH MỤC CÔNG CỤ MCP HỖ TRỢ (`ngochoang_*`) * `ngochoang_whoami`: Xem danh tính và quyền hạn của phiên làm việc. * `ngochoang_login`: Đăng nhập chuyển đổi tài khoản (quản trị trường hoặc phụ huynh). * `ngochoang_lookup_parent`: Tra cứu toàn diện hồ sơ phụ huynh, học sinh, công nợ, camera app và VietQR. * `ngochoang_search_students`: Tìm kiếm học sinh theo tên/mã/lớp. * `ngochoang_get_classes`: Danh sách tất cả các lớp học kèm danh mục camera bố trí từng lớp. * `ngochoang_toggle_camera_access`: Bật / Tắt quyền xem camera trên app mnngochoang.com. * `ngochoang_reset_camera_pin`: Đặt lại mã PIN đăng nhập về "1234". * `ngochoang_unblock_camera_account`: Gỡ khóa tài khoản khi nhập sai PIN quá nhiều lần. * `ngochoang_assign_camera_class`: Phân quyền / gán lớp camera cho phụ huynh. * `ngochoang_get_tuition_invoices`: Tra cứu chi tiết các khoản phí và lịch sử thu tiền. --- # Quy Chuẩn Quản Lý Phụ Huynh & Camera Trường Mầm Non Ngọc Hoàng ## 1. Cấu Trúc Dữ Liệu Học Sinh & Phụ Huynh - Mỗi phụ huynh có mã định danh `PHxxxxx` (vd: `PH000465`). - Mỗi học sinh thuộc một lớp học (`Mầm 1`, `Chồi 2`, `Lá 3`, `Nhà trẻ`...). - Mỗi phụ huynh có thể liên kết một hoặc nhiều số điện thoại (`Phone`), mỗi số điện thoại có thể liên kết tài khoản xem camera trên cổng `mnngochoang.com`. ## 2. Quy Tắc Bật / Tắt Quyền Camera - **Điều kiện bật camera:** 1. Bé có trạng thái `DANG_HOC` (Đang học). 2. Phụ huynh đã đóng đủ học phí và tiền camera tháng hiện tại (`debt <= 0`). 3. Tài khoản camera được gán đúng lớp học của bé. - **Trường hợp tạm ngưng camera:** 1. Phụ huynh nợ học phí quá hạn quy định. 2. Bé có trạng thái `NGHI_LUON` (Thôi học). 3. Lớp học tạm ngưng hoạt động trong kỳ nghỉ hoặc sửa chữa. ## 3. Quy Chuẩn Tài Khoản & Bảo Mật Mã PIN - Tên đăng nhập mặc định: Số điện thoại phụ huynh (chuẩn 10 số, bắt đầu bằng `0`). - Mã PIN mặc định khi reset: `1234`. - Sau khi reset, cờ `pinResetPending` sẽ là `true`; phụ huynh bắt buộc phải đổi mã PIN mới trong lần đăng nhập đầu tiên trên App `mnngochoang.com`. - Tài khoản bị khóa (State: `BLOCKED`) nếu nhập sai mã PIN quá 5 lần liên tiếp. --- # Danh Mục Lớp Học & Bố Trí Camera Trường Ngọc Hoàng | Tên Lớp / Khu Vực | Số Lượng Camera | Các Camera Bố Trí Thực Tế | Ghi Chú | | :--- | :---: | :--- | :--- | | **Mầm 1** | 4 | Mầm 1, Hồ Bơi, Sân 3, Sân 5 | Phòng học lầu 1 | | **Mầm 2** | 4 | Mầm 2, Hồ Bơi, Sân 4, Sân 5 | Phòng học lầu 1 | | **Mầm 3** | 4 | Mầm 3, Hồ Bơi, Sân 5, Sân 7 | Phòng học lầu 1 | | **Chồi 1** | 4 | Chồi 1, Hồ Bơi, Sân 2, Sân 5 | Phòng học trệt | | **Chồi 2** | 4 | Chồi 2, Hồ Bơi, Sân 5, Sân 6 | Phòng học trệt | | **Chồi 3** | 4 | Chồi 3, Hồ Bơi, Sân 5, Sân 6 | Phòng học trệt | | **Lá 1** | 3 | Lá 1, Hồ Bơi, Sân 5 | Phòng học lầu 2 | | **Lá 2** | 3 | Lá 2, Hồ Bơi, Sân 5 | Phòng học lầu 2 | | **Lá 3** | 3 | Lá 3, Hồ Bơi, Sân 5 | Phòng học lầu 2 | | **Nhà Trẻ** | 3 | Nhà Trẻ, Sân 4, Sân 5 | Phòng trệt riêng biệt | | **Sân trường** | 7 | Hồ Bơi, Sân 2, Sân 3, Sân 4, Sân 5, Sân 6, Sân 7 | Khu vực sinh hoạt chung | *Mặc định phụ huynh các lớp đều được cấp quyền xem camera lớp chính và các camera sân trường/hồ bơi khi đến giờ hoạt động ngoài trời.* --- # Các Tình Huống Vận Hành Thực Tế & Kịch Bản Mẫu ## Tình Huống 1: Phụ Huynh Đóng Tiền $\to$ Kế Toán / Agent Mở Camera - **Admin/Kế toán:** *"Phụ huynh số 0975227637 vừa chuyển khoản học phí, mở camera giúp chị."* - **Agent thực thi:** 1. `ngochoang_lookup_parent(phone="0975227637")` $\to$ Xác minh đúng tên phụ huynh và học sinh. 2. `ngochoang_toggle_camera_access(phone="0975227637", active=true, reason="Đã đóng học phí")` 3. Phản hồi: *"Dạ em đã kiểm tra và kích hoạt thành công quyền xem camera cho phụ huynh Dư Đức Duy (0975227637) rồi ạ!"* --- ## Tình Huống 2: Phụ Huynh Nhập Sai PIN Bị Khóa Tài Khoản - **Phụ huynh:** *"Tôi đăng nhập vào app mnngochoang.com báo tài khoản bị khóa do nhập sai mật khẩu."* - **Agent thực thi:** 1. `ngochoang_unblock_camera_account(phone="...")` 2. `ngochoang_reset_camera_pin(phone="...")` 3. Phản hồi: *"Dạ tài khoản của anh/chị đã được mở khóa và mã PIN đã được đặt lại về 1234. Anh/chị vào lại app bằng SĐT và nhập 1234 để đổi mã PIN mới nhé ạ!"*