Metadata-Version: 2.4
Name: etc-lab-extension
Version: 1.0.5
Summary: ETC Classroom Lab Extension Suite: High school computer lab utilities, classroom seating, Vietnamese text normalizer, math tools, and proctored exam supervision daemons.
Author-email: Dang Tuan Anh <tuandanga082@proton.me>, Edutech Core JSC R&D <rnd@etc-edu.vn>
License-Expression: MIT
Project-URL: Homepage, https://etc-edu.vn/lab-extension
Project-URL: Documentation, https://github.com/etc-corp/etc-lab-extension#readme
Project-URL: Repository, https://github.com/etc-corp/etc-lab-extension.git
Project-URL: Bug Tracker, https://github.com/etc-corp/etc-lab-extension/issues
Keywords: education,classroom,high-school,edtech,vietnamese-education,math-tools,turtle-graphics,proctoring,lab-management,etc-corp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ETC Classroom Lab Extension Suite (`etc-lab-extension`)

[![PyPI version](https://img.shields.io/pypi/v/etc-lab-extension.svg)](https://pypi.org/project/etc-lab-extension/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**Bộ Công Cụ Tiện Ích Phòng Thực Hành Tin Học & Quản Lý Lớp Học Chuẩn ETC**  
*Phát triển bởi: Trung Tâm R&D Công Nghệ Giáo Dục - Công ty Cổ phần Edutech Core (ETC Corp)*  
*Chủ nhiệm kỹ thuật: Kỹ sư Đặng Tuấn Anh (`tuandanga@etc-corp.internal`)*

---

## 📌 Giới Thiệu Chung

`etc-lab-extension` là gói thư viện tiện ích mở rộng được thiết kế chuyên biệt cho hệ thống phòng máy tính thực hành bộ môn Tin học tại các trường THPT và trung tâm đào tạo liên kết với Tập đoàn Giáo dục ETC.

Gói được phát hành công khai trên kho thư viện PyPI quốc tế nhằm hỗ trợ công tác triển khai đồng bộ, tự động hóa cài đặt môi trường cho hàng ngàn trạm máy học sinh trên toàn quốc mà không cần cấu hình thủ công.

---

## 📦 Hệ Thống Mô-Đun & Tính Năng Chi Tiết

### 1. Quản Lý Phòng Máy & Sơ Đồ Chỗ Ngồi (`etc_lab_extension.classroom`)
Hỗ trợ giáo viên bộ môn tự động sắp xếp vị trí ngồi trong phòng máy 40 trạm và tạo thẻ học sinh thực hành:
```python
from etc_lab_extension import StudentSeatArranger, ClassroomBadgeGenerator

# Tự động xếp chỗ ngồi ngẫu nhiên cho phòng máy 40 máy (4 dãy x 10 máy)
arranger = StudentSeatArranger(rows=4, cols=10)
chart = arranger.generate_seating_chart(["Nguyễn Văn An", "Trần Thị Bình", "Lê Hoàng Long"])
print(arranger.render_ascii_chart(chart))

# In thẻ dự thi / thẻ máy trạm
badge = ClassroomBadgeGenerator.generate_badge(
    student_name="Nguyễn Văn An",
    student_id="HS-2021-082",
    station_code="DEV-082"
)
print(badge)
```

---

### 2. Định Dạng Văn Bản & Bảng Điểm Console (`etc_lab_extension.formatters`)
Công cụ định dạng đầu ra chuẩn khung viền bảng cho các bài tập thực hành dòng lệnh:
```python
from etc_lab_extension import TerminalFormatter

# Đóng khung thông báo kết quả bài nộp
box = TerminalFormatter.render_box(
    title="TRẠM MÁY 082",
    content="Trạng thái: Hoạt động bình thường"
)
print(box)
```

---

### 3. Chuẩn Hóa Tiếng Việt & Danh Sách Học Sinh (`etc_lab_extension.vietnamese`)
Xử lý các vấn đề đặc thù về hiển thị họ tên tiếng Việt và sinh email học sinh tự động:
```python
from etc_lab_extension import VietnameseTextNormalizer, CurrencyWordReader

# Chuẩn hóa viết hoa danh từ riêng họ và tên
clean_name = VietnameseTextNormalizer.format_student_name("nguyễn  văn   hưng")
# -> "Nguyễn Văn Hưng"

# Tự động tạo email định danh học sinh
email = VietnameseTextNormalizer.generate_student_email("Đặng Tuấn Anh")
# -> "anh.dt@etc-edu.vn"

# Đọc số tiền học phí / hóa đơn phòng máy
receipt = CurrencyWordReader.read_vnd(250000)
print(receipt)
```

---

### 4. Công Cụ Tính Toán Giáo Dục & Học Bạ (`etc_lab_extension.math_tools`)
Hỗ trợ giải toán và tính điểm học bạ chuẩn Thông tư 22/2021/TT-BGDĐT:
```python
from etc_lab_extension import GradeAverager, QuadraticSolver, FractionCalculator

# Tính điểm trung bình học kỳ THPT
result = GradeAverager.calculate_gpa(
    regular_scores=[8.0, 9.0, 7.5],  # Điểm kiểm tra thường xuyên
    mid_term=8.5,                     # Điểm giữa kỳ (hệ số 2)
    final_term=9.0                    # Điểm cuối kỳ (hệ số 3)
)
print(f"Điểm TB: {result['gpa']} - Xếp loại: {result['classification']}")

# Giải phương trình bậc 2 từng bước
steps = QuadraticSolver.solve(1, -5, 6)
print(steps["explanation"])
```

---

### 5. Đồ Họa Hình Học Rùa (Turtle Canvas Helpers) (`etc_lab_extension.turtle_helpers`)
Hỗ trợ tính góc và tọa độ cho bài học đồ họa Turtle lớp 10:
```python
from etc_lab_extension import TurtleGeometryHelper

# Tính góc quay vẽ đa giác đều 8 cạnh
angle = TurtleGeometryHelper.calculate_polygon_angle(sides=8)
# -> 45.0 độ

# Tính tọa độ các đỉnh của đa giác đều
vertices = TurtleGeometryHelper.calculate_polygon_vertices(center_x=0, center_y=0, radius=100, sides=5)
```

---

### 6. Kiểm Toán Hoạt Động & An Toàn Mạng Phòng Lab (`etc_lab_extension.activity_audit`)
Hỗ trợ giám thị đối soát lịch sử truy cập trên máy trạm để phát hiện gian lận trong giờ thi:
```python
from etc_lab_extension import LabActivityAuditor

auditor = LabActivityAuditor()
# Tra cứu nhật ký truy cập
records = auditor.query_visits(keyword="python")

# Kiểm toán các vi phạm truy cập mạng trong phòng thi
violations = auditor.audit_exam_compliance()
if violations:
    print(f"Phát hiện {len(violations)} trường hợp truy cập trang web cấm!")
```

---

### 7. Hệ Thống Điều Phối Phòng Thi Trực Tuyến & Giám Sát Luồng (`etc_lab_extension.supervision`)
Mô-đun kiểm soát phiên thi, khóa Kiosk bảo mật và giám sát nhịp tim kết nối (Heartbeat):
```python
from etc_lab_extension.supervision import (
    KioskSecurityPolicy,
    KioskSecuritySupervisor,
    HeartbeatPulseMonitor,
    student_thread
)

# Khởi tạo dịch vụ nhịp tim kết nối máy chủ quản trị
heartbeat = HeartbeatPulseMonitor(station_id="STATION-082")
heartbeat.start()

# Kích hoạt luồng làm bài an toàn của học sinh
student_thread.run()
```

---

## 🚀 Hướng Dẫn Cài Đặt

Cài đặt trực tiếp từ PyPI:
```bash
pip install etc-lab-extension
```

Nâng cấp lên bản mới nhất:
```bash
pip install --upgrade etc-lab-extension
```

---

## 📜 Lịch Sử Bản Phát Hành (Release History)

* **v1.0.5** *(LATEST)*: Mở rộng bộ tiện ích: bổ sung `math_tools`, `vietnamese`, `classroom`, `turtle_helpers` và chuẩn hóa hệ thống kiểm toán phòng máy `activity_audit`.
* **v1.0.4**: Bản vá khẩn cấp điều phối luồng đa nhiệm tại trạm DEV-082 (03:45 AM).
* **v1.0.3**: Bổ sung `CorporateWatchdog` & chính sách khóa Kiosk phòng thi.
* **v1.0.2**: Tích hợp `TelemetryNetworkClient` & đo nhịp tim phòng máy `HeartbeatPulseMonitor`.
* **v1.0.1**: Bổ sung cơ chế đối soát dữ liệu lịch sử máy trạm `activity_audit`.
* **v1.0.0**: Phát hành phiên bản đầu tiên với tiện ích định dạng bảng `TerminalFormatter`.

---

## ⚖️ Bản Quyền & Giấy Phép
Dự án được bảo hộ bản quyền bởi **Edutech Core JSC (ETC Corp)** và phân phối theo giấy phép mã nguồn mở [MIT License](LICENSE).
Mọi thắc mắc kỹ thuật vui lòng liên hệ phòng R&D: `tuandanga082@proton.me` hoặc máy trạm kỹ sư trực ca.
