Schema Database (DTI) | QIG LMS Docs

Tài liệu mô tả các bảng database mà hệ thống DTI sử dụng để lưu trữ dữ liệu push từ LMS. Chỉ bao gồm các bảng liên quan trực tiếp đến luồng push — các bảng phục vụ Dashboard sẽ được bổ sung sau.

1. Tổng quan

LMS Push API
  ├── POST /api/v1/lms/hub/push        → lms_school_stats (chỉ số cấp trường)
  ├── POST /api/v1/lms/hub/push/users  → lms_user_stats   (chỉ số cấp user)
  └── Auto upsert           → lms_school_profiles (metadata trường)

Lookup:
  ├── lms_metric_definitions  (registry metric keys)
  ├── lms_dimension_types     (registry loại dimension)
  ├── lms_dimension_values    (giá trị hợp lệ cho mỗi dimension)
  └── lms_providers           (danh sách NCC LMS)

2. Bảng Raw Data

2.1. lms_school_stats

Bảng fact chính cho chỉ số cấp trường. Mỗi row = 1 giá trị metric tại 1 thời điểm cho 1 trường. Là TimescaleDB hypertable, tối ưu cho time-series data.

Column	Type	Bắt buộc	Mô tả
`id`	BIGSERIAL	Auto	PK auto-increment
`provdoet_code`	VARCHAR(10)	Có	Mã Sở GD&ĐT
`school_code`	VARCHAR(50)	Có	Mã trường
`school_level`	VARCHAR(5)	Có	Cấp học: 01-05
`school_year_code`	SMALLINT	Có	Năm học: 2025, 2026...
`semester_code`	SMALLINT	Có	Học kỳ: 1 hoặc 2
`metric_key`	VARCHAR(100)	Có	Mã metric (VD: `teacher_accounts`)
`dim_value`	VARCHAR(100)	Có	Giá trị dimension. Default `''`. VD: `mobile`, `video`
`subject_code`	VARCHAR(4)	Không	Mã chương trình môn học (tối đa 4 ký tự số). VD: `0101`
`grade_code`	VARCHAR(2)	Không	Mã khối/lớp (2 ký tự số). VD: `09` = Khối 9
`value`	NUMERIC	Có	Giá trị metric
`measured_at`	TIMESTAMPTZ	Có	Thời điểm đo (do LMS gửi)
`received_at`	TIMESTAMPTZ	Auto	Thời điểm server nhận, default `NOW()`
`etl_status`	VARCHAR(10)	Auto	`pending` → `processed`. ETL worker đọc pending rows

Đặc tính TimescaleDB:

Hypertable: chunk interval = 1 ngày trên measured_at
Columnstore compression: tự động sau 3 ngày
Indexes: (school_code, metric_key, dim_value, measured_at DESC), (school_code, metric_key, subject_code, measured_at DESC), partial index trên etl_status = 'pending'

2.2. lms_user_stats

Bảng fact cho chỉ số cấp người dùng (GV/HS). Cấu trúc giống lms_school_stats nhưng thêm user_pin và chunk interval lớn hơn do volume cao.

Column	Type	Bắt buộc	Mô tả
`id`	BIGSERIAL	Auto	PK auto-increment
`provdoet_code`	VARCHAR(10)	Có	Mã Sở GD&ĐT
`school_code`	VARCHAR(50)	Có	Mã trường
`school_level`	VARCHAR(5)	Có	Cấp học: 01-05
`school_year_code`	SMALLINT	Có	Năm học
`semester_code`	SMALLINT	Có	Học kỳ: 1 hoặc 2
`user_pin`	VARCHAR(100)	Có	Mã định danh người dùng trên LMS
`metric_key`	VARCHAR(100)	Có	Mã metric
`dim_value`	VARCHAR(100)	Có	Giá trị dimension. Default `''`
`subject_code`	VARCHAR(4)	Không	Mã chương trình môn học (tối đa 4 ký tự số). VD: `0101`
`grade_code`	VARCHAR(2)	Không	Mã khối/lớp (2 ký tự số). VD: `09` = Khối 9
`value`	NUMERIC	Có	Giá trị metric
`measured_at`	TIMESTAMPTZ	Có	Thời điểm đo
`received_at`	TIMESTAMPTZ	Auto	Default `NOW()`
`etl_status`	VARCHAR(10)	Auto	`pending` → `processed`

Đặc tính TimescaleDB:

Hypertable: chunk interval = 7 ngày trên measured_at
Columnstore compression: tự động sau 7 ngày
Indexes: (school_code, user_pin, metric_key, measured_at DESC), (school_code, metric_key, subject_code, measured_at DESC), partial index trên etl_status = 'pending'

2.3. lms_school_profiles

Metadata trường học. Tự động upsert khi LMS push. Phục vụ tra cứu và group by cấp học/địa phương trên Dashboard.

Column	Type	Bắt buộc	Mô tả
`id`	UUID	Auto	PK
`provdoet_code`	VARCHAR(10)	Có	Mã Sở GD&ĐT
`school_code`	VARCHAR(50)	Có	Mã trường
`school_level`	VARCHAR(5)	Có	Cấp học: 01-05
`school_year_code`	SMALLINT	Có	Năm học
`has_lms`	BOOLEAN	Có	Trường có sử dụng LMS không. Default `false`
`provider_id`	UUID FK	Không	→ `lms_providers`
`division_code`	VARCHAR(20)	Không	Mã xã/phường
`start_date`	DATE	Không	Ngày bắt đầu sử dụng LMS
`created_at`	TIMESTAMPTZ	Auto
`updated_at`	TIMESTAMPTZ	Auto

Unique constraint: (provdoet_code, school_code, school_level, school_year_code) — bộ 4 giá trị xác định duy nhất 1 trường.

3. Bảng Definitions

3.1. lms_metric_definitions

Registry tất cả metric keys. LMS đọc qua API GET /api/v1/lms/hub/metrics/push-config để biết cần push những chỉ số nào.

Column	Type	Mô tả
`id`	UUID PK
`key`	VARCHAR(100) UNIQUE	Mã metric (VD: `total_lessons`, `teacher_accounts`)
`name`	VARCHAR(200)	Tên hiển thị
`unit`	VARCHAR(50)	Đơn vị: lessons, accounts, %, GB, minutes...
`value_type`	ENUM	`cumulative` (tích lũy) hoặc `gauge` (snapshot)
`push_interval`	VARCHAR(20)	Tần suất push: `1 hour`, `1 day`, `1 week`, `1 month`
`dim_type`	VARCHAR(50)	Loại dimension nếu có (VD: `device`, `content_type`). NULL = không có
`target_role`	VARCHAR(20)	Đối tượng: `teacher`, `student`, hoặc NULL (cấp trường)
`source`	VARCHAR(20)	`push` (LMS gửi) hoặc `computed` (ETL tính). Default `push`
`description`	TEXT	Mô tả chi tiết
`is_active`	BOOLEAN	Metric bị deactivate sẽ bị reject khi push

3.2. lms_dimension_types

Registry loại dimension. Dùng cho labels hiển thị và validation.

Column	Type	Mô tả
`id`	UUID PK
`key`	VARCHAR(50) UNIQUE	`content_type`, `grade_code`, `subject`, `device`, `school_level`
`name`	VARCHAR(200)	Tên hiển thị (VD: Loại bài giảng, Khối lớp)
`description`	TEXT
`is_active`	BOOLEAN

3.3. lms_dimension_values

Giá trị hợp lệ cho mỗi dimension type. Frontend dùng để hiển thị label tiếng Việt.

Column	Type	Mô tả
`id`	UUID PK
`dim_type_id`	UUID FK	→ `lms_dimension_types`
`code`	VARCHAR(100)	Mã giá trị (VD: `video`, `01`, `mobile`)
`label`	VARCHAR(200)	Label hiển thị (VD: Video, Khối 1, Mobile)
`sort_order`	INT	Thứ tự sắp xếp
`is_active`	BOOLEAN

Unique constraint: (dim_type_id, code)

Dữ liệu đã seed:

Dimension type	Số values	Ví dụ
`content_type`	8	content, video, audio, document, scorm, iframe, test, interactive_video
`grade_code`	12	01 → 12 (Khối 1 → Khối 12)
`device`	3	mobile, pc, tablet
`school_level`	5	01 Mầm non, 02 Tiểu học, 03 THCS, 04 THPT, 05 GDTX
`subject`	—	LMS tự gửi mã riêng (không seed sẵn)

3.4. lms_providers

Danh sách nhà cung cấp LMS.

Column	Type	Mô tả
`id`	UUID PK
`name`	VARCHAR(200)	Tên NCC (VD: VnEdu, OLM, Edmicro)
`code`	VARCHAR(50) UNIQUE	Mã NCC
`is_active`	BOOLEAN

4. Quan hệ giữa các bảng

lms_providers
  └──< lms_school_profiles.provider_id

lms_metric_definitions.key
  └── được dùng trong lms_school_stats.metric_key
  └── được dùng trong lms_user_stats.metric_key

lms_dimension_types
  └──< lms_dimension_values.dim_type_id
  └── lms_metric_definitions.dim_type → tham chiếu bằng key (không FK)

lms_school_profiles
  └── tự động upsert khi push (provdoet_code + school_code + school_level + school_year_code)

Lưu ý: lms_school_stats và lms_user_stats tham chiếu metric_key bằng giá trị string (không dùng FK UUID) để tối ưu insert performance trên hypertable.