Data Dictionary · Khác (phần 9/11)

⚙️ Trang này sinh tự động từ source code bằng scripts/gen-reference.mjs — đừng sửa tay, sửa code rồi chạy npm run gen:reference.

Thuộc Data Dictionary. 29 bảng, outreach_status_log tới referral_milestones.

outreach_status_log

_{migration: 0308_school_codes_and_outreach.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
org_id	TEXT	NOT NULL REFERENCES outreach_orgs(id) ON DELETE CASCADE
status	TEXT	NOT NULL
note	TEXT	—
by_user	TEXT	—
at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: org_id → outreach_orgs

Index: idx_outreach_status_org(org_id, at)

outreach_templates

Khuôn thư theo ngôn ngữ, là DỮ LIỆU: sửa chữ không cần deploy. approved = chủ dự án đã duyệt khuôn này; khuôn chưa duyệt thì không gửi thật được (chỉ xem trước). Chỗ điền: .

_{migration: 0308_school_codes_and_outreach.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY, -- vd 'school-oct-2026-en-initial'
language	TEXT	NOT NULL
kind	TEXT	NOT NULL CHECK (kind IN ('initial', 'reminder'))
subject	TEXT	NOT NULL
greeting	TEXT	NOT NULL
body	TEXT	NOT NULL
promo_url	TEXT	NOT NULL
approved	INTEGER	NOT NULL DEFAULT 0 CHECK (approved IN (0, 1))
approved_by	TEXT	—
approved_at	TEXT	—
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Index: uq_outreach_template_lang_kind(language, kind) UNIQUE

parent_beliefs

---------------------------------------------------------------- parent_beliefs

_{migration: 0082_english_state_enums.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
learner_id	TEXT	NOT NULL REFERENCES learners(id)
user_id	TEXT	NOT NULL REFERENCES users(id)
subject_id	TEXT	NOT NULL
worry_level	INTEGER	NOT NULL CHECK (worry_level BETWEEN 1 AND 5)
perceived_state	TEXT	CHECK (perceived_state IN
predicted_score	REAL	—
score_scale	REAL	NOT NULL DEFAULT 10
will_pass	INTEGER	—
note	TEXT	—
recorded_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: learner_id → learners · user_id → users

Index: idx_parent_beliefs(learner_id, subject_id, recorded_at)

parent_course_journeys

Migration 0334 - parent course journeys. SRC-1252. ## Vì sao migration này tồn tại Khoá học của bố mẹ (marlins.nemo12.com/parent-courses) đổi từ "đọc rồi làm quiz" sang một vòng sáu hành trình GOAL, UNDERSTAND, LEARN, TRY, REFLECT, DECIDE ở cấp khoá, và năm bước GOAL, LEARN, TRY, REFLECT, NEXT ở cấp chỗ học. Những gì bố mẹ tự viết ra trong vòng ấy (mục tiêu, điểm xuất phát của gia đình, phản ứng của con khi thử, điều rút ra, quyết định tiếp theo) phải theo họ sang máy khác và phải đi vào Parent Model. parent_course_progress chỉ có chỗ cho mốc đọc và điểm quiz, nên không có bảng này thì mọi câu trả lời chỉ sống trong một trình duyệt. Một dòng là MỘT bước của MỘT phụ huynh ở MỘT chỗ: bước cấp khoá dùng unit_index = -1 và lesson_index = -1. Nội dung là JSON vì mỗi bước hỏi một bộ câu khác nhau; luật hình dạng nằm ở zod trong workers/api/src/modules/parent/journeys.ts, không nằm ở đây. ## Chạy lại không đổi gì Chỉ có CREATE ... IF NOT EXISTS.

_{migration: 0334_parent_course_journeys.sql}

Cột	Kiểu	Ràng buộc / ghi chú
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
course_code	TEXT	NOT NULL
unit_index	INTEGER	NOT NULL DEFAULT -1
lesson_index	INTEGER	NOT NULL DEFAULT -1
step	TEXT	NOT NULL CHECK (step IN ('goal','understand','try','reflect','decide'))
data_json	TEXT	NOT NULL
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (user_id, course_code, unit_index, lesson_index, step)

Khóa ngoại: user_id → users

Index: idx_parent_course_journeys_user(user_id, course_code)

parent_course_progress

Tiến độ đọc và điểm quiz của BỐ MẸ trong khoá học cho bố mẹ (SRC-671, REQ-PAR-18). VÌ SAO KHÔNG DÙNG LẠI curriculum_part_completions / curriculum_stage_completions: hai bảng kia khoá theo learner_id và theo lesson trong CSDL nội dung của học sinh. Ở đây người học là NGƯỜI LỚN (users.id), và nội dung không nằm trong CSDL mà nằm trong mã nguồn của app dưới dạng 15 khoá tĩnh. Nhét vào bảng của learner thì mọi câu đếm tiến độ của học sinh phải nhớ loại trừ người lớn ra, và sẽ có ngày một câu quên loại trừ. KHOÁ CHÍNH là (user_id, course_code, unit_index, lesson_index): một người, một chỗ học, đúng một dòng. Làm quiz lại thì CẬP NHẬT dòng cũ chứ không thêm dòng — lịch sử từng lần làm không phải câu hỏi mà màn hình này trả lời; câu hỏi của nó là "còn hổng chỗ nào NGAY BÂY GIỜ". course_code cố tình KHÔNG có khoá ngoại: danh mục khoá nằm trong mã nguồn (parentCourses.ts), không có bảng nào để trỏ tới. Đổi lại, mã đọc phải chịu được dòng trỏ tới khoá đã bị xoá.

_{migration: 0197_parent_course_progress.sql}

Cột	Kiểu	Ràng buộc / ghi chú
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
course_code	TEXT	NOT NULL
unit_index	INTEGER	NOT NULL
lesson_index	INTEGER	NOT NULL
read_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
quiz_attempts	INTEGER	NOT NULL DEFAULT 0
quiz_total	INTEGER	—
last_correct	INTEGER	—
best_correct	INTEGER	—
missed_json	TEXT	—
quiz_at	TEXT	—
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (user_id, course_code, unit_index, lesson_index)

Khóa ngoại: user_id → users

Index: idx_parent_course_progress_user(user_id, course_code)

parent_digest_sends

Migration 0327 - parent digest one row per recipient. SRC-1204. ## Vì sao migration này tồn tại Thư tổng kết ngày được dựng cho từng cặp (con, email bố mẹ), nhưng chốt chặn trùng ở parent_digest_sends có khoá chính (learner_id, digest_date). Con có HAI phụ huynh thì người thứ nhất giành được dòng, người thứ hai bị INSERT OR IGNORE bỏ qua và bị đếm là "đã gửi": không bao giờ nhận thư, không có log nào nói ra (audit 03.10.2026). Khoá chính phải có cả người nhận. SQLite không đổi được khoá chính tại chỗ nên dựng lại bảng. ## Chạy lại không đổi gì Dựng bảng mới IF NOT EXISTS, chép bằng INSERT OR IGNORE, rồi thay bảng cũ. Chạy lần hai thì bảng "cũ" đã mang khoá mới, chép sang nguyên vẹn và thay lại: cùng một kết quả.

_{migration: 0327_parent_digest_one_row_per_recipient.sql}

Cột	Kiểu	Ràng buộc / ghi chú
learner_id	TEXT	NOT NULL REFERENCES learners(id)
digest_date	TEXT	NOT NULL
to_email	TEXT	NOT NULL
intended_email	TEXT	NOT NULL
status	TEXT	NOT NULL CHECK (status IN ('sent','failed','skipped'))
provider_id	TEXT	—
error	TEXT	—
items	INTEGER	NOT NULL DEFAULT 0
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (learner_id, digest_date, intended_email)

Khóa ngoại: learner_id → learners

Index: idx_digest_sends_date(digest_date, status)

parent_ebook_progress

Migration 0330 - parent ebook reading progress. SRC-1228. ## Vì sao migration này tồn tại Lượt tính Parent Model đầu tiên (04.10.2026) cho ra một con số nói thẳng: 26/32 phụ huynh không có mẩu bằng chứng nào ở chiều "tự học". Không phải vì họ không học, mà vì cổng này chỉ ghi lại đúng MỘT loại việc học: đọc một chỗ học trong khoá dành cho bố mẹ (6 dòng trên toàn production). Thư viện Marlins có 20 quyển sách và trang đọc đã chạy từ SRC-673, nhưng đọc xong một chương thì không để lại dấu vết nào - mở trang, đọc, đóng lại, hệ không biết gì cả. Bảng này là chỗ ghi dấu ấy. Nó cũng là thứ cho phép trang đọc sau này nói "bạn đang đọc dở quyển nào", việc mà hôm nay không làm được. ## MỞ và ĐỌC XONG là hai việc khác nhau Hai cột thời gian chứ không phải một cờ: mở một chương rồi đóng ngay là một tín hiệu YẾU về việc tự học, còn đọc tới hết chương là một tín hiệu mạnh. Gộp cả hai thành "đã đọc" là biến một cú bấm nhầm thành bằng chứng ngang với một buổi ngồi đọc thật. ## Chạy lại không đổi gì CREATE TABLE IF NOT EXISTS và CREATE INDEX IF NOT EXISTS; không câu nào ghi dữ liệu.

_{migration: 0330_parent_ebook_reading_progress.sql}

Cột	Kiểu	Ràng buộc / ghi chú
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
book_slug	TEXT	NOT NULL
chapter_index	INTEGER	NOT NULL
opened_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
finished_at	TEXT	—
opens	INTEGER	NOT NULL DEFAULT 1
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (user_id, book_slug, chapter_index)

Khóa ngoại: user_id → users

Index: idx_parent_ebook_user(user_id, updated_at DESC)

parent_evidence

── Evidence Registry của phụ huynh ───────────────────────────────────────────────────────── BẤT BIẾN như sổ của learner: một mẩu đã ghi thì không sửa. Muốn nói điều khác thì ghi mẩu mới. Nhờ vậy mọi ảnh chụp model cũ vẫn giải thích lại được bằng đúng số liệu đã sinh ra nó.

_{migration: 0328_parent_evidence_registry_and_parent_model.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
event_id	TEXT	NOT NULL UNIQUE
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
family_id	TEXT	—
about_learner_id	TEXT	—
source	TEXT	NOT NULL
type	TEXT	NOT NULL
dimension	TEXT	NOT NULL CHECK (dimension IN ('learning','understanding','acting','presence'))
observed	REAL	NOT NULL
reliability	REAL	NOT NULL
payload_json	TEXT	—
occurred_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
recorded_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: user_id → users

Index: idx_parent_evidence_user(user_id, occurred_at DESC) · idx_parent_evidence_dim(user_id, dimension) · idx_parent_evidence_about(about_learner_id)

parent_lesson_gates

_{migration: 0335_lesson_gates.sql}

Cột	Kiểu	Ràng buộc / ghi chú
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
course_code	TEXT	NOT NULL
unit_index	INTEGER	NOT NULL
lesson_index	INTEGER	NOT NULL
part_index	INTEGER	NOT NULL
attempts	INTEGER	NOT NULL DEFAULT 0
last_correct	INTEGER	—
last_total	INTEGER	—
failed_at	TEXT	—
passed_at	TEXT	—
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (user_id, course_code, unit_index, lesson_index, part_index)

Khóa ngoại: user_id → users

Index: idx_parent_lesson_gates_user(user_id, course_code)

parent_models

── Parent Model ──────────────────────────────────────────────────────────────────────────── Cùng khuôn với ielts_learner_models (0229): mỗi lần tính ra một ẢNH CHỤP mới, không sửa đè ảnh cũ. Model là một kết luận, mà kết luận thì phải xem lại được nó đã đổi thế nào.

_{migration: 0328_parent_evidence_registry_and_parent_model.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
user_id	TEXT	NOT NULL REFERENCES users(id) ON DELETE CASCADE
engine_version	INTEGER	NOT NULL
evidence_count	INTEGER	NOT NULL DEFAULT 0
evidence_through	TEXT	—
learning	REAL	, understanding REAL, acting REAL, presence REAL
confidence	REAL	NOT NULL DEFAULT 0
layer_json	TEXT	NOT NULL
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: user_id → users

Index: idx_parent_models_user(user_id, created_at DESC)

partner_attributions

Người mua thuộc về đối tác nào. buyer_user_id UNIQUE: first touch thắng, trọn đời.

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
buyer_user_id	TEXT	PRIMARY KEY REFERENCES users(id)
partner_id	TEXT	NOT NULL REFERENCES partners(id)
campaign_id	TEXT	—
product_line	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
buyer_discount_bp	INTEGER	NOT NULL DEFAULT 0 — thêm ở 0305_partner_discount_and_tax.sql

Khóa ngoại: buyer_user_id → users · partner_id → partners

Index: idx_partner_attributions_partner(partner_id)

partner_campaigns

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
partner_id	TEXT	NOT NULL REFERENCES partners(id)
slug	TEXT	NOT NULL
product_line	TEXT	NOT NULL CHECK (product_line IN ('ielts', 'sat', 'speaking'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	UNIQUE (partner_id, slug)

Khóa ngoại: partner_id → partners

partner_clicks

Lượt bấm: chỉ để đếm. Không lưu IP thô.

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	INTEGER	PRIMARY KEY AUTOINCREMENT
partner_id	TEXT	NOT NULL REFERENCES partners(id)
campaign_id	TEXT	—
product_line	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: partner_id → partners

Index: idx_partner_clicks_partner(partner_id, created_at)

partner_commissions

Sổ hoa hồng: CHỈ CHÈN. Số dư = SUM. Hoàn tiền = dòng âm (kind='reverse').

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
partner_id	TEXT	NOT NULL REFERENCES partners(id)
payment_ref	TEXT	NOT NULL REFERENCES partner_sales(payment_ref)
tier	INTEGER	NOT NULL CHECK (tier IN (1, 2))
kind	TEXT	NOT NULL CHECK (kind IN ('earn', 'reverse'))
base_amount_vnd	INTEGER	NOT NULL
rate_bp	INTEGER	NOT NULL
amount_vnd	INTEGER	NOT NULL
available_at	TEXT	NOT NULL
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	UNIQUE (payment_ref, tier, kind)

Khóa ngoại: partner_id → partners · payment_ref → partner_sales

Index: idx_partner_commissions_partner(partner_id)

partner_payouts

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
partner_id	TEXT	NOT NULL REFERENCES partners(id)
amount_vnd	INTEGER	NOT NULL CHECK (amount_vnd > 0)
status	TEXT	NOT NULL DEFAULT 'requested' CHECK (status IN ('requested', 'paid', 'cancelled'))
scheduled_for	TEXT	NOT NULL
bank_ref	TEXT	—
requested_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
paid_at	TEXT	—
paid_by	TEXT	—
tax_rate_bp	INTEGER	NOT NULL DEFAULT 0 — thêm ở 0305_partner_discount_and_tax.sql
tax_withheld_vnd	INTEGER	NOT NULL DEFAULT 0 — thêm ở 0305_partner_discount_and_tax.sql
net_amount_vnd	INTEGER	— thêm ở 0305_partner_discount_and_tax.sql
tax_id	TEXT	— thêm ở 0305_partner_discount_and_tax.sql

Khóa ngoại: partner_id → partners

Index: idx_partner_payouts_partner(partner_id) · idx_partner_payouts_one_open(partner_id) UNIQUE

partner_rates

Tỷ lệ theo dòng sản phẩm và tầng. Không nằm trong pricing_items vì bảng ấy được trang chủ công khai đọc; tỷ lệ của người bán không phải thứ phụ huynh cần thấy.

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
product_line	TEXT	NOT NULL CHECK (product_line IN ('ielts', 'sat', 'speaking'))
tier	INTEGER	NOT NULL CHECK (tier IN (1, 2))
rate_bp	INTEGER	NOT NULL CHECK (rate_bp >= 0 AND rate_bp <= 5000)
—	table constraint	PRIMARY KEY (product_line, tier)

partner_sales

Một khoản người mua THỰC TRẢ. Chưa có cổng thanh toán nên admin ghi; ngày có cổng thì cổng gọi cùng một hàm. payment_ref UNIQUE: ghi hai lần một khoản không thành hai khoản.

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
payment_ref	TEXT	PRIMARY KEY
buyer_user_id	TEXT	NOT NULL REFERENCES users(id)
partner_id	TEXT	NOT NULL REFERENCES partners(id)
product_line	TEXT	NOT NULL CHECK (product_line IN ('ielts', 'sat', 'speaking'))
amount_vnd	INTEGER	NOT NULL CHECK (amount_vnd > 0)
paid_at	TEXT	NOT NULL
refunded_at	TEXT	—
recorded_by	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: buyer_user_id → users · partner_id → partners

partners

Migration 0304 - partner program (partners.nemo12.com). SRC-1089, SDD-046. ## Vì sao migration này tồn tại Người bán chuyên nghiệp (affiliate) cần một hệ ghi công và một sổ hoa hồng TIỀN MẶT riêng, tách khỏi referral của learner (referral_*), vì hai luật của referral learner sai với người bán: "hai bên cùng vai" (bảo vệ trẻ con) và "hoa hồng vào tài khoản ảo tiêu vào học phí". Nới hai luật ấy tại chỗ là mở lỗ ở một hệ đang chạy; nên người bán có bảng riêng. Chốt với chủ dự án 27.09.2026: tự duyệt; ghi công ngay; hoa hồng rút được sau 30 ngày; số dư phải đạt 5.000.000 mới rút, mỗi lần rút tối thiểu 3.000.000, và luôn để lại 1.000.000 cọc; trả ngày 5 hằng tháng; tầng hai 2%. Các con số tiền nằm trong code (partners/policy.ts), tỷ lệ theo dòng sản phẩm nằm ở partner_rates dưới đây để sửa không cần deploy. ## Chạy lại không đổi gì CREATE TABLE IF NOT EXISTS, INSERT ... ON CONFLICT DO NOTHING.

_{migration: 0304_partner_program.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
user_id	TEXT	NOT NULL UNIQUE REFERENCES users(id)
code	TEXT	NOT NULL UNIQUE
status	TEXT	NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended'))
full_name	TEXT	NOT NULL
phone	TEXT	NOT NULL
channel	TEXT	—
terms_version	TEXT	NOT NULL
upline_partner_id	TEXT	REFERENCES partners(id)
bank_name	TEXT	—
bank_account	TEXT	—
bank_holder	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	CHECK (upline_partner_id IS NULL OR upline_partner_id <> id)
tax_id	TEXT	— thêm ở 0305_partner_discount_and_tax.sql

Khóa ngoại: user_id → users · upline_partner_id → partners

photo_album_items

alt_text NOT NULL là có chủ đích: album là bằng chứng niềm tin, mà một trang toàn ảnh không alt text thì với người dùng trình đọc màn hình là một trang trống (SDD-019 §5).

_{migration: 0046_mentor_profiles_albums.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
album_id	TEXT	NOT NULL REFERENCES photo_albums(id)
media_id	TEXT	NOT NULL REFERENCES media(id)
alt_text	TEXT	NOT NULL
caption	TEXT	—
caption_parent	TEXT	—
caption_student	TEXT	—
display_order	INTEGER	NOT NULL DEFAULT 100
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
description	TEXT	— thêm ở 0323_photo_item_description.sql
taken_at	TEXT	— thêm ở 0324_photo_album_item_metadata.sql
location	TEXT	— thêm ở 0324_photo_album_item_metadata.sql
original_filename	TEXT	— thêm ở 0324_photo_album_item_metadata.sql
source_ref	TEXT	— thêm ở 0324_photo_album_item_metadata.sql

Khóa ngoại: album_id → photo_albums · media_id → media

Index: idx_photo_album_items_album(album_id, display_order) · idx_photo_album_items_source(source_ref) UNIQUE

photo_album_people

Gắn người ở tầng album, không ở tầng từng ảnh (Q-133).

_{migration: 0046_mentor_profiles_albums.sql}

Cột	Kiểu	Ràng buộc / ghi chú
album_id	TEXT	NOT NULL REFERENCES photo_albums(id)
mentor_profile_id	TEXT	NOT NULL REFERENCES mentor_profiles(id)
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (album_id, mentor_profile_id)

Khóa ngoại: album_id → photo_albums · mentor_profile_id → mentor_profiles

Index: idx_photo_album_people_mentor(mentor_profile_id)

photo_albums

photo_albums — mỗi trường chữ có 3 cột: gốc + bản bố mẹ + bản học sinh (SDD-019 §6). audience là chuyện KHÁC: nó quyết album có được xuất hiện ở vùng đó không.

_{migration: 0046_mentor_profiles_albums.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
slug	TEXT	NOT NULL UNIQUE
title	TEXT	NOT NULL
title_parent	TEXT	—
title_student	TEXT	—
caption	TEXT	—
caption_parent	TEXT	—
caption_student	TEXT	—
description	TEXT	—
description_parent	TEXT	—
description_student	TEXT	—
cover_media_id	TEXT	REFERENCES media(id)
audience	TEXT	NOT NULL DEFAULT 'both' CHECK (audience IN ('both','parent','student'))
status	TEXT	NOT NULL DEFAULT 'draft' CHECK (status IN ('draft','published','archived'))
featured	INTEGER	NOT NULL DEFAULT 0 CHECK (featured IN (0,1))
display_order	INTEGER	NOT NULL DEFAULT 100
taken_on	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
updated_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
source_ref	TEXT	— thêm ở 0324_photo_album_item_metadata.sql

Khóa ngoại: cover_media_id → media

Index: idx_photo_albums_public(status, audience, display_order) · idx_photo_albums_source(source_ref) UNIQUE

pricing_items

Migration 0177 — Bảng giá công khai của khoá IELTS (SRC-643). Chủ dự án chốt 2026-08-30: học phí, gói bài tập tự chấm, combo bốn kỹ năng, thưởng top tuần/tháng và hoa hồng giới thiệu. Yêu cầu "đưa vào database" chứ không để trong mã nguồn. ## Vì sao vào DB trong khi danh mục gói học giữ giá trong mã (Danh mục ấy nằm ở apps/web/src/packages.ts khi viết dòng này; từ 2026-09-19 nó chuyển từ hai bản trong app sang một gói dùng chung packages/catalog — SRC-867. Chỉ đường dẫn đổi, lập luận dưới đây không đổi.) Hai thứ khác nhau, và ranh giới phải rõ để về sau không ai phải đoán: | | packages.ts (mã nguồn) | Bảng này (D1) | | --- | --- | --- | | Cái gì | CHƯƠNG TRÌNH: Nemo Dive · Swim · 360 · Marlin Start/Compass/Mind | KHOÁ HỌC: học phí IELTS, gói bài tập, combo, thưởng | | Đổi giá bằng cách nào | sửa mã + deploy | sửa dòng trong D1 | Giá khoá đổi theo đợt khai giảng và người đổi không nhất thiết biết code, nên nó thuộc về dữ liệu. Giá chương trình gắn với mô tả dài trong cùng file và đổi rất hiếm, nên để yên tại chỗ — kéo nó sang đây chỉ tạo thêm một chỗ phải đồng bộ mà không giải quyết vấn đề nào. ## Vì sao lưu SỐ chứ không lưu chuỗi đã định dạng Cùng lý do đã ghi trong packages.ts: số chỉ xuất hiện đúng một lần, còn cách viết do Intl.NumberFormat lo. Lưu "3.200.000 ₫" thì sớm muộn có dòng ghi "3tr2", dòng ghi "3,200,000", và không ai biết dòng nào mới đúng.

_{migration: 0177_pricing.sql}

Cột	Kiểu	Ràng buộc / ghi chú
code	TEXT	PRIMARY KEY
kind	TEXT	NOT NULL CHECK (kind IN ('tuition', 'addon', 'bundle', 'reward', 'referral'))
name_vi	TEXT	NOT NULL
amount_vnd	INTEGER	—
unit_vi	TEXT	—
list_amount_vnd	INTEGER	—
percent	INTEGER	—
note_vi	TEXT	—
seq	INTEGER	NOT NULL
active	INTEGER	NOT NULL DEFAULT 1

Index: idx_pricing_items_active(active, seq)

product_updates

_{migration: 0337_mail_series_state_and_product_updates.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
program	TEXT	NOT NULL
title_vi	TEXT	NOT NULL
body_vi	TEXT	NOT NULL
url	TEXT	NOT NULL
status	TEXT	NOT NULL DEFAULT 'draft'
published_at	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Index: idx_product_updates_program(program, status, published_at DESC)

program_joins

Migration 0345 - program joins. SRC-1336. ## Vì sao migration này tồn tại Chỉ đạo chủ dự án 10.10.2026: trang tổng quan mỗi chương trình có nút "Tham gia"; thư THEO LỊCH của chương trình (chuỗi thư, báo cáo tuần, Learning Plan) chỉ bắt đầu sau khi bấm. Thư xác nhận và thư sau buổi học vẫn đi như cũ. Người ĐANG học từ trước được tính là đã tham gia (quyết định của chủ dự án), nên migration này ghi sẵn một dòng grandfathered cho họ: không có dòng ấy thì đúng lượt cron đầu sau deploy, mọi gia đình đang học mất thư tuần mà không ai báo. Một dòng mỗi (user, chương trình). Tham gia là của MỘT người dùng; bộ gửi coi một học sinh là đã tham gia khi chính em, hoặc một phụ huynh (owner/guardian) của gia đình em, có dòng ở đây. ## Chạy lại không đổi gì CREATE TABLE IF NOT EXISTS, và mọi câu ghi sẵn là INSERT OR IGNORE.

_{migration: 0345_program_joins.sql}

Cột	Kiểu	Ràng buộc / ghi chú
user_id	TEXT	NOT NULL REFERENCES users(id)
program	TEXT	NOT NULL
source	TEXT	NOT NULL
joined_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (user_id, program)

Khóa ngoại: user_id → users

Index: idx_program_joins_program(program)

province_aliases

Bí danh: mọi cách người ta thật sự gõ, quy về một mã. ĐÂY là thứ làm một bảng cứng chịu được thực tế, và là thứ migration 0221 không có. alias lưu dạng ĐÃ CHUẨN HOÁ (thường, bỏ dấu, bỏ tiền tố "tỉnh"/"thành phố"/"tp"), để 'Hà Nội', 'hà nội', 'HA NOI' và 'TP Hà Nội' rơi vào cùng một dòng thay vì bốn dòng. Phép chuẩn hoá ấy nằm ở tầng code (geography/normalize.ts) và phải giống hệt ở cả lượt nạp lẫn lượt tra — nếu hai bên lệch nhau thì bảng này im lặng không khớp gì cả.

_{migration: 0279_learner_geography_country_and_province_codes.sql}

Cột	Kiểu	Ràng buộc / ghi chú
alias	TEXT	PRIMARY KEY
province_code	TEXT	NOT NULL REFERENCES provinces(code)

Khóa ngoại: province_code → provinces

provinces

─── 2. Tỉnh/thành/bang, có mã ───────────────────────────────────────────────────────────────── Một bảng cho MỌI quốc gia, không phải một bảng riêng cho Việt Nam: chỉ đạo nói "tỉnh/thành phố/ bang", tức là chiều thứ hai phải chịu được cả state của Mỹ lẫn tỉnh của Việt Nam. Khác biệt giữa chúng là chữ NHÃN, không phải cấu trúc.

_{migration: 0279_learner_geography_country_and_province_codes.sql}

Cột	Kiểu	Ràng buộc / ghi chú
code	TEXT	PRIMARY KEY
country_code	TEXT	NOT NULL
—	table constraint	CHECK (length(country_code) = 2 AND country_code = upper(country_code))
name_vi	TEXT	NOT NULL
name_en	TEXT	NOT NULL
kind	TEXT	NOT NULL DEFAULT 'tinh'
seq	INTEGER	NOT NULL DEFAULT 1
active	INTEGER	NOT NULL DEFAULT 1

Index: idx_provinces_country(country_code, active, seq)

referral_attributions

Ai giới thiệu ai. referred_user_id là KHOÁ CHÍNH nên mỗi người chỉ được ghi công đúng MỘT lần trong đời: first-touch thắng, không ai đổi được người giới thiệu của mình về sau. Đây là ràng buộc chống gian lận đặt ở tầng dữ liệu, không phải ở tầng code.

_{migration: 0064_referrals.sql}

Cột	Kiểu	Ràng buộc / ghi chú
referred_user_id	TEXT	PRIMARY KEY REFERENCES users(id)
referrer_user_id	TEXT	NOT NULL REFERENCES users(id)
code	TEXT	NOT NULL
source_app	TEXT	NOT NULL CHECK (source_app IN ('marlins','learn'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	CHECK (referred_user_id <> referrer_user_id) -- không tự giới thiệu chính mình

Khóa ngoại: referred_user_id → users · referrer_user_id → users

Index: idx_referral_attr_referrer(referrer_user_id)

referral_codes

Mỗi người MỘT mã, sinh khi họ mở trang giới thiệu lần đầu.

_{migration: 0064_referrals.sql}

Cột	Kiểu	Ràng buộc / ghi chú
code	TEXT	PRIMARY KEY, -- chuỗi ngắn, phân biệt HOA/thường khi tra thì chuẩn hoá về hoa
user_id	TEXT	NOT NULL UNIQUE REFERENCES users(id), -- UNIQUE: một người không được có hai mã
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: user_id → users

referral_milestones

Ghi nhận hoạt động của người ĐƯỢC giới thiệu (SRC-754, REQ-GRW-02; nối tiếp SRC-450). VÌ SAO CẦN BẢNG NÀY: referral_attributions trả lời được đúng một câu — "ai giới thiệu ai" — rồi im lặng mãi mãi. Người giới thiệu mở trang chỉ thấy một dòng tên và chữ "đang chờ", không biết người mình rủ vào có dùng Nemo12 thật hay đã bỏ đi sau một lần đăng nhập. Mà đó mới là câu hỏi khiến người ta rủ tiếp người thứ hai. VÌ SAO LÀ MỘT BẢNG CHỨ KHÔNG PHẢI ĐẾM LẠI MỖI LẦN HỎI: mốc là chuyện xảy ra MỘT LẦN tại MỘT THỜI ĐIỂM. Tính lại từ dữ liệu thô mỗi lần đọc thì "lần đầu tiên" trôi theo dữ liệu — một learner bị lưu trữ, một dòng evidence bị xoá, và cái mốc đã báo cho người giới thiệu tuần trước biến mất khỏi màn hình tuần này. Ghi lại một lần rồi thôi là cách duy nhất để câu chuyện kể cho người giới thiệu không tự sửa sau lưng họ. KHOÁ CHÍNH (referred_user_id, milestone): mỗi người mỗi mốc đúng một dòng, trọn đời. Nhờ vậy lượt quét chỉ cần INSERT OR IGNORE và chạy lại bao nhiêu lần cũng không sinh dòng thừa — tính bình thản (idempotent) đặt ở tầng dữ liệu, không phải ở tầng code nhớ kiểm tra.

_{migration: 0226_referral_milestones.sql}

Cột	Kiểu	Ràng buộc / ghi chú
referred_user_id	TEXT	NOT NULL REFERENCES users(id)
referrer_user_id	TEXT	NOT NULL REFERENCES users(id)
milestone	TEXT	NOT NULL CHECK (milestone IN ('joined','learner_linked','diagnostic_done','first_lesson','active_week','course_enrolled','paid'))
occurred_at	TEXT	NOT NULL
ref_id	TEXT	—
notified_at	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (referred_user_id, milestone)

Khóa ngoại: referred_user_id → users · referrer_user_id → users

Index: idx_referral_milestones_notify(referrer_user_id, notified_at)