Data Dictionary · Khác (phần 11/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. 22 bảng, speak_schedule_signups tới walk_registrations.

speak_schedule_signups

Migration 0303 - Đăng ký buổi Speak together theo lịch tuần. SRC-1088. Chủ dự án 27.09.2026: lịch luyện Speaking hằng tuần, tối thứ Tư 20:00-21:30 và sáng Chủ nhật 10:00-11:30 (giờ VN); learner đăng ký bất kỳ buổi nào, chậm nhất 48 giờ trước giờ bắt đầu; xem lại được các buổi đã đăng ký và chi tiết từng buổi. ## Vì sao chỉ một bảng đăng ký, không có bảng buổi Buổi là một LỊCH CỐ ĐỊNH (hai khung giờ mỗi tuần, chủ đề xoay vòng theo thứ tự), nên máy chủ tính ra được mọi buổi từ một mốc (speakSchedule.ts) mà không cần lưu. Lưu từng buổi thành dòng thì phải có một việc định kỳ sinh dòng trước, và ngày việc ấy hỏng là trang lịch trống. Thứ duy nhất phải nhớ là ai đã đăng ký buổi nào; session_id là mã buổi dạng '2026-09-30-2000' (ngày giờ VN). ## Chạy lại không đổi gì CREATE TABLE / INDEX IF NOT EXISTS.

_{migration: 0303_speak_schedule_signups.sql}

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

Khóa ngoại: learner_id → learners

Index: idx_speak_schedule_learner(learner_id, session_id)

speak_trial_signups

Migration 0310 - Buổi học thử của program Speaking. SRC-1120. ## Vì sao migration này tồn tại Chủ dự án 28.09.2026: program Speaking ở learn.nemo12.com/speaking cho mỗi learner 3 buổi học thử, đăng ký trong tháng 9 hoặc tháng 10/2026, chỉ các buổi tối thứ Tư. Buổi thử vẫn là một dòng speak_schedule_signups như mọi lượt đăng ký (danh sách người đến, nhắc lịch, link Zoom dùng chung); bảng này chỉ ĐÁNH DẤU lượt nào đi qua program Speaking, để máy chủ đếm được đã dùng mấy buổi thử. Bảng riêng chứ không thêm cột: ALTER TABLE ADD COLUMN chạy lại sẽ lỗi, còn bảng thì chạy lại vô hại. ## Chạy lại không đổi gì CREATE TABLE / INDEX IF NOT EXISTS.

_{migration: 0310_speak_schedule_signups_program.sql}

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

Khóa ngoại: learner_id → learners

Index: idx_speak_trial_learner(learner_id)

specialized_programs

Lớp chuyên. subject_code cố ý KHÔNG khoá ngoại vào subjects của knowledge graph: lớp chuyên có Sinh, Sử, Địa, Nga, Nhật… trong khi graph mới có 6 môn. Khoá ngoại ở đây nghĩa là không nhập nổi lớp Chuyên Sinh cho tới ngày có content môn Sinh (SDD-020 §2).

_{migration: 0047_school_registry.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
school_id	TEXT	NOT NULL REFERENCES target_schools(id)
subject_code	TEXT	NOT NULL
name_vi	TEXT	NOT NULL
intake_size	INTEGER	—
notes	TEXT	—
status	TEXT	NOT NULL DEFAULT 'published' CHECK (status IN ('draft','published','archived'))
display_order	INTEGER	NOT NULL DEFAULT 100
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: school_id → target_schools

Index: idx_specialized_programs_school(school_id, display_order)

testimonials

Migration 0075 — Cảm nhận của người dùng (SRC-564, mở rộng SDD-019). Chỉ đạo: cần chỗ cho người xem thấy RẤT NHIỀU cảm nhận thật, để tăng niềm tin. Ảnh cộng đồng đã có chỗ từ 0046 (photo_albums); phần còn thiếu là lời của người thật. Vì sao KHÔNG nhét vào một bảng "content" chung: cảm nhận là lời khẳng định của MỘT NGƯỜI CÓ THẬT về sản phẩm. Nó cần đúng ba thứ mà nội dung marketing không cần: 1. consent — người đó đã đồng ý cho nêu tên chưa. Đăng lời khen của một phụ huynh mà chưa hỏi là chuyện pháp lý, không phải chuyện biên tập. 2. verified — ai trong đội đã đối chiếu lời này là thật, và lúc nào. 3. audience — cùng một câu chuyện kể cho bố mẹ khác với kể cho học sinh (SDD-019 §6). Cổng publish ở tầng API đòi đủ consent + verified, giống studentPublishBlockers của SDD-020.

_{migration: 0075_testimonials.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
author_name	TEXT	NOT NULL
author_role	TEXT	—
photo_media_id	TEXT	REFERENCES media(id)
quote	TEXT	NOT NULL
body	TEXT	—
program_code	TEXT	—
mentor_id	TEXT	REFERENCES mentor_profiles(id)
audience	TEXT	NOT NULL DEFAULT 'both' CHECK (audience IN ('both','parent','student'))
consent	INTEGER	NOT NULL DEFAULT 0 CHECK (consent IN (0,1))
consent_note	TEXT	—
verified	INTEGER	NOT NULL DEFAULT 0 CHECK (verified IN (0,1))
verified_at	TEXT	—
verified_by	TEXT	REFERENCES users(id)
internal_note	TEXT	—
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
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'))
said_on	TEXT	— thêm ở 0175_testimonial_card_fields.sql
facts_json	TEXT	NOT NULL DEFAULT '[]' — thêm ở 0175_testimonial_card_fields.sql
is_sample	INTEGER	NOT NULL DEFAULT 0 — thêm ở 0175_testimonial_card_fields.sql
kind	TEXT	NOT NULL DEFAULT 'quote' — thêm ở 0199_testimonial_stories.sql
slug	TEXT	— thêm ở 0199_testimonial_stories.sql
title	TEXT	— thêm ở 0199_testimonial_stories.sql
summary	TEXT	— thêm ở 0199_testimonial_stories.sql
cover_media_id	TEXT	REFERENCES media(id) — thêm ở 0199_testimonial_stories.sql
content_state	TEXT	NOT NULL DEFAULT 'draft' — thêm ở 0199_testimonial_stories.sql
visibility	TEXT	NOT NULL DEFAULT 'private' — thêm ở 0199_testimonial_stories.sql
placements_json	TEXT	NOT NULL DEFAULT '[]' — thêm ở 0199_testimonial_stories.sql
source_note_id	TEXT	REFERENCES family_notes(id) — thêm ở 0216_testimonial_from_note.sql

Khóa ngoại: photo_media_id → media · mentor_id → mentor_profiles · verified_by → users

Index: idx_testimonials_public(status, audience, featured DESC, display_order) · idx_testimonials_program(program_code, status) · idx_testimonials_slug(slug) UNIQUE · idx_testimonials_kind(kind, status, display_order) · idx_testimonials_source_note(source_note_id) UNIQUE

tp_agent_tokens

0189 — Tool Plane: nhiều token cho một agent, mỗi token có thể trói vào một user (SRC-667, SDD-030 §6). Vì sao: Claude Managed Agents chỉ gửi được Authorization: Bearer <token> tới MCP server, KHÔNG gửi được header tuỳ ý — nên X-Nemo12-User-Id không có đường đi. Người mà Agent thay mặt phải nằm trong chính token: một token = (agent, user). Mỗi vault của Managed Agents giữ một token, và vault vốn đã là "một người dùng", nên mô hình khớp nhau. tp_agents.token_hash (0188) vẫn dùng được như token không trói user (đường cũ).

_{migration: 0189_tool_plane_agent_tokens.sql}

Cột	Kiểu	Ràng buộc / ghi chú
token_hash	TEXT	PRIMARY KEY
agent_id	TEXT	NOT NULL REFERENCES tp_agents(id)
user_id	TEXT	REFERENCES users(id), -- NULL = token không thay mặt ai (job nền, research)
label	TEXT	—
status	TEXT	NOT NULL DEFAULT 'active' CHECK (status IN ('active','revoked'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
last_used_at	TEXT	—

Khóa ngoại: agent_id → tp_agents · user_id → users

Index: idx_tp_agent_tokens_agent(agent_id, status)

tp_agent_tools

Grant: agent nào được tool nào, trên tài nguyên nào, ở môi trường nào, đọc hay ghi. tool_id nhận cả learner.get_profile:v1, learner.get_profile và glob learner.*.

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
agent_id	TEXT	NOT NULL REFERENCES tp_agents(id)
tool_id	TEXT	NOT NULL
resource_scope	TEXT	NOT NULL DEFAULT 'user', -- '*' | 'user' | 'learner:L1,learner:L2' | 'family:F1'
environment_scope	TEXT	NOT NULL DEFAULT '', -- '' | 'production' | 'staging,development'
permission	TEXT	NOT NULL DEFAULT 'read' CHECK (permission IN ('read','write'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (agent_id, tool_id)

Khóa ngoại: agent_id → tp_agents

tp_agents

Agent = một danh tính gọi tool. token_hash NULL = chưa cấp token, không đăng nhập được. Cấp token: node scripts/tool-plane/issue-agent-token.mjs <agent_id> → in token + SQL cập nhật hash.

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
name	TEXT	NOT NULL
description	TEXT	—
status	TEXT	NOT NULL DEFAULT 'active' CHECK (status IN ('active','suspended','retired'))
token_hash	TEXT	UNIQUE
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'))

tp_applications

Application Registry (spec §4): Agent suy luận về hệ Nemo12 từ đây, không hardcode.

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
name	TEXT	NOT NULL
domain	TEXT	—
repository	TEXT	—
repository_path	TEXT	—
environment	TEXT	NOT NULL DEFAULT 'production'
owner	TEXT	—
status	TEXT	NOT NULL DEFAULT 'live' CHECK (status IN ('planned','live','deprecated'))
description	TEXT	—
architecture_reference	TEXT	—
database	TEXT	—
deployment_target	TEXT	—
metadata	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'))

tp_audit_logs

Một dòng cho MỖI lượt gọi, kể cả lượt bị từ chối. Không chứa input/output.

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
request_id	TEXT	NOT NULL
timestamp	TEXT	NOT NULL
agent_id	TEXT	NOT NULL
session_id	TEXT	NOT NULL
user_id	TEXT	—
tool_id	TEXT	NOT NULL
resource	TEXT	—
decision	TEXT	NOT NULL CHECK (decision IN ('allow','deny','require_approval'))
status	TEXT	NOT NULL CHECK (status IN ('success','error','denied'))
error_code	TEXT	—
duration_ms	INTEGER	NOT NULL DEFAULT 0
environment	TEXT	NOT NULL
metadata	TEXT	—

Index: idx_tp_audit_agent_time(agent_id, timestamp DESC) · idx_tp_audit_resource(resource, timestamp DESC) · idx_tp_audit_request(request_id)

tp_policies

Policy toàn hệ. deny thắng require_approval thắng allow (policy-engine.ts).

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
name	TEXT	NOT NULL
effect	TEXT	NOT NULL CHECK (effect IN ('allow','deny','require_approval'))
agent_scope	TEXT	NOT NULL DEFAULT '*'
tool_scope	TEXT	NOT NULL DEFAULT '*'
resource_scope	TEXT	NOT NULL DEFAULT '*'
environment_scope	TEXT	NOT NULL DEFAULT '*'
conditions	TEXT	, -- JSON: {"risk_at_least":"HIGH"} |
enabled	INTEGER	NOT NULL DEFAULT 1
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

tp_tools

Bản chiếu của Tool Registry. CODE (workers/tool-plane/src/registry/tools.ts) là nguồn sự thật; bảng này để grant/policy tham chiếu và để người vận hành đọc. Khớp lại bằng node scripts/tool-plane/sync-tools.mjs.

_{migration: 0188_tool_plane.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY, -- learner.get_profile:v1
name	TEXT	NOT NULL, -- learner.get_profile
description	TEXT	—
category	TEXT	NOT NULL
version	INTEGER	NOT NULL DEFAULT 1
risk_level	TEXT	NOT NULL CHECK (risk_level IN ('LOW','MEDIUM','HIGH','CRITICAL'))
mode	TEXT	NOT NULL CHECK (mode IN ('read','write'))
enabled	INTEGER	NOT NULL DEFAULT 1
input_schema	TEXT	—
output_schema	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'))

tutor_digest_items

_{migration: 0321_tutor_learner_profile_and_weekly_digest.sql}

Cột	Kiểu	Ràng buộc / ghi chú
family_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
tutor_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
sent_at	TEXT	NOT NULL
—	table constraint	PRIMARY KEY (family_listing_id, tutor_listing_id)

Khóa ngoại: family_listing_id → tutor_listings · tutor_listing_id → tutor_listings

Index: idx_tutor_digest_items_sent(family_listing_id, sent_at)

tutor_interests

Một lượt "Quan tâm" từ listing này tới listing phía kia. Một cặp (from, to) một dòng: bấm lại không tạo dòng mới.

_{migration: 0315_tutor_listings_and_interests.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
from_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
to_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
from_user_id	TEXT	NOT NULL, -- để đếm trần 10 lượt/ngày theo người, không theo listing
reasons	TEXT	NOT NULL, -- JSON mảng mã lý do
message	TEXT	, -- tối đa 300 ký tự, đã lọc số điện thoại, email, URL
status	TEXT	NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'accepted', 'declined'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
responded_at	TEXT	—

Khóa ngoại: from_listing_id → tutor_listings · to_listing_id → tutor_listings

Index: idx_tutor_interests_pair(from_listing_id, to_listing_id) UNIQUE · idx_tutor_interests_to(to_listing_id, status) · idx_tutor_interests_user_day(from_user_id, created_at)

tutor_listing_contacts

Phần RIÊNG TƯ: chỉ chủ listing và admin đọc được.

_{migration: 0315_tutor_listings_and_interests.sql}

Cột	Kiểu	Ràng buộc / ghi chú
listing_id	TEXT	PRIMARY KEY REFERENCES tutor_listings(id) ON DELETE CASCADE
contact_name	TEXT	NOT NULL
phone	TEXT	NOT NULL
email	TEXT	NOT NULL
learner_name	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
school	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql

Khóa ngoại: listing_id → tutor_listings

tutor_listings

Migration 0315 - tutor listings and interests. SRC-1141, SDD-050. ## Vì sao migration này tồn tại Chủ dự án 29.09.2026: NEMO TUTOR là hệ listing hai phía ở learn.nemo12.com/tutors. Gia đình và gia sư mỗi bên điền một form ngắn; mỗi bên chỉ xem listing của phía kia, ẩn danh; muốn làm quen thì bấm "Quan tâm", hai bên cùng quan tâm thì admin kết nối bằng tay. Không bên nào thấy thông tin liên hệ của bên kia qua hệ thống. Vì thế thông tin liên hệ (họ tên, điện thoại, email) nằm ở một BẢNG RIÊNG, tutor_listing_contacts, chứ không phải vài cột cạnh phần công khai: câu SELECT của trang duyệt listing đọc tutor_listings và không có đường nào kéo nhầm số điện thoại ra, kể cả khi ai đó viết SELECT *. Chỉ hai chỗ đọc bảng liên hệ: trang "listing của tôi" (chính chủ) và hàng chờ admin. Xoá listing là xoá cả dòng liên hệ, các lượt quan tâm và các cặp đã khớp của listing ấy (mã trong workers/api/src/modules/tutors/ xoá tường minh, không dựa vào ON DELETE CASCADE vì D1 chỉ thi hành khoá ngoại khi PRAGMA foreign_keys bật). ## Chạy lại không đổi gì CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS.

_{migration: 0315_tutor_listings_and_interests.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
user_id	TEXT	NOT NULL REFERENCES users(id)
side	TEXT	NOT NULL CHECK (side IN ('family', 'tutor'))
public_no	INTEGER	NOT NULL
status	TEXT	NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'hidden', 'paused'))
goals	TEXT	NOT NULL, -- JSON mảng mã mục tiêu: ielts, sat, chuyen, university, subject, other
subjects	TEXT	NOT NULL, -- môn / phần cần giúp (gia đình) hoặc môn dạy (gia sư)
area	TEXT	NOT NULL, -- quận Hà Nội hoặc 'online'
online	INTEGER	NOT NULL DEFAULT 0,-- nhận học online
schedule	TEXT	NOT NULL, -- lịch mong muốn (gia đình) hoặc lịch rảnh (gia sư)
note	TEXT	, -- ghi chú ngắn (gia đình) hoặc giới thiệu ngắn (gia sư)
family_role	TEXT	CHECK (family_role IS NULL OR family_role IN ('student', 'parent'))
grade	TEXT	—
level	TEXT	—
evidence	TEXT	, -- gia sư: mỗi dòng một bằng chứng
experience	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'))
approved_at	TEXT	—
birth_year	INTEGER	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
target	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
exam_month	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
sessions_per_week	INTEGER	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
budget	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql
closed_at	TEXT	— thêm ở 0321_tutor_learner_profile_and_weekly_digest.sql

Khóa ngoại: user_id → users

Index: idx_tutor_listings_user_side(user_id, side) UNIQUE · idx_tutor_listings_label(side, public_no) UNIQUE · idx_tutor_listings_browse(side, status, updated_at)

tutor_matches

Hai bên cùng quan tâm: một cặp đã khớp, chờ admin kết nối bằng tay.

_{migration: 0315_tutor_listings_and_interests.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
family_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
tutor_listing_id	TEXT	NOT NULL REFERENCES tutor_listings(id) ON DELETE CASCADE
status	TEXT	NOT NULL DEFAULT 'matched' CHECK (status IN ('matched', 'connected'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
connected_at	TEXT	—
connected_by	TEXT	—

Khóa ngoại: family_listing_id → tutor_listings · tutor_listing_id → tutor_listings

Index: idx_tutor_matches_pair(family_listing_id, tutor_listing_id) UNIQUE · idx_tutor_matches_status(status, created_at)

unit_prereqs

Migration 0055 — prerequisite graph ở cấp UNIT (SRC-396). Chỉ đạo chủ dự án 2026-08-19: "khi làm không ổn 1 unit thì đi học lại 1-2 unit trước đó, không tính theo node hay concept nữa" — và làm rõ tiếp: đó là 1-2 unit CHẶN unit hiện tại, tức quan hệ ngữ nghĩa, không phải vị trí đứng cạnh nhau trên bản đồ. Vì sao bảng mới chứ không dùng skill_edges: · skill_edges làm việc ở cấp node, mà một unit có tới ba node là biến thể theo lớp của cùng một ý. Sinh cạnh ở đó buộc phải chọn "node chốt", và chính chỗ chọn ấy đẻ ra 53/171 prerequisite đi ngược lớp (lớp 7 thành nền của lớp 2) trong lần sinh trước — sai mà không làm gãy gì, nên không ai thấy cho tới khi đi đếm. · Ở cấp unit thì mỗi cạnh là một câu người đọc được và bác được, và cả prerequisite graph chỉ còn ~150-250 dòng — rà bằng mắt hết được, khác hẳn 1.540 câu hỏi. Cạnh ĐƯỢC PHÉP đi xuyên Package: đó là lý do soạn tay thay vì sinh theo thứ tự bày. "Giải phương trình một ẩn" (B2) đứng trên "Dấu bằng nghĩa là hai bên cân nhau" (B1) — cách nhau cả Package, và vị trí trên bản đồ không đời nào tìm ra quan hệ đó. Mặc định là hệ tự soạn tự chốt (REQ-PLT-12, AI-First): cạnh sinh ra ở trạng thái 'auto' và CÓ HIỆU LỰC NGAY. Coral không phải cổng duyệt, mà là chỗ người vào xem lại và nâng cấp sau: auto — hệ soạn, đang chạy; reviewed — người đã đọc và giữ nguyên; edited — người đã sửa (rationale ghi lại vì sao); rejected — người bỏ; runtime KHÔNG dùng, nhưng giữ dòng lại để lần sinh sau không đề xuất lại.

_{migration: 0055_unit_prereqs.sql}

Cột	Kiểu	Ràng buộc / ghi chú
subject_id	TEXT	NOT NULL
unit_key	TEXT	NOT NULL, -- 'strand|module|unit', khớp unitKeyOf() ở apps/learn
prereq_key	TEXT	NOT NULL
rank	INTEGER	NOT NULL DEFAULT 1, -- 1 = prerequisite gần nhất, 2 = cái thứ hai
rationale_vi	TEXT	, -- một câu: vì sao unit kia là prerequisite của unit này
status	TEXT	NOT NULL DEFAULT 'auto', -- auto | reviewed | edited | rejected
source	TEXT	NOT NULL DEFAULT 'ai-claude'
reviewed_by	TEXT	—
reviewed_at	TEXT	—
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (subject_id, unit_key, prereq_key)

Index: idx_unit_prereqs_unit(subject_id, unit_key, status) · idx_unit_prereqs_prereq(subject_id, prereq_key, status)

user_program_interest

_{migration: 0336_inbound_mail_log_and_user_program_interest.sql}

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

Khóa ngoại: user_id → users

Index: idx_user_program_interest_recent(user_id, last_seen_at DESC) · idx_user_program_interest_program(program, last_seen_at DESC)

walk_checkins

NEMO WALK: check-in tại điểm tập trung và ghép cặp (chủ dự án 01.10.2026). Mỗi learner một dòng mỗi buổi. partner_id NULL nghĩa là đang chờ người ghép; ghép là hai chiều (A trỏ B và B trỏ A). paired_by = 'auto' khi hệ thống ghép, 'host' khi host đổi cặp. Idempotent: chạy lại vô hại.

_{migration: 0322_walk_checkins_and_pairs.sql}

Cột	Kiểu	Ràng buộc / ghi chú
walk_date	TEXT	NOT NULL
learner_id	TEXT	NOT NULL REFERENCES learners(id)
checked_in_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
partner_id	TEXT	REFERENCES learners(id)
paired_by	TEXT	CHECK (paired_by IN ('auto', 'host'))
paired_at	TEXT	—
—	table constraint	PRIMARY KEY (walk_date, learner_id)

Khóa ngoại: learner_id → learners · partner_id → learners

Index: idx_walk_checkins_waiting(walk_date, partner_id, checked_in_at)

walk_entry_profiles

Migration 0325 - walk entry profiles and quiz passes. SRC-1193. ## Vì sao migration này tồn tại Chủ dự án 03.10.2026: trước buổi NEMO WALK đầu tiên, learner khai một hồ sơ ngắn (số điện thoại, họ tên, ngày sinh, trình độ Speaking, trường hoặc nơi làm) rồi làm bài quiz 10 câu về luật chung, phải đúng 10/10 mới qua. Hệ thống phải GHI LẠI ở server rằng người này "đã qua bài kiểm tra để bắt đầu tham gia NEMO WALK" (learner, lúc qua, điểm, câu trả lời, phiên bản đề), để host và admin tin được con số ấy chứ không chỉ tin một cờ trong trình duyệt. walk_entry_profiles: một dòng mỗi learner, ghi dần từng bước của stepper (cột NULL = chưa trả lời), completed_at có giá trị khi đủ mọi bước bắt buộc. Số điện thoại và ngày sinh là dữ liệu cá nhân: chỉ chính learner và staff/admin đọc được (chốt ở workers/api/src/modules/walks/entry.ts). phone lưu dạng E.164 (+84...), dob dạng ISO YYYY-MM-DD; hiển thị DD.MM.YYYY là việc của UI. walk_quiz_attempts: mọi lượt nộp, kể cả lượt trượt (để biết câu nào hay sai mà sửa đề). Lượt qua là dòng passed = 1; mỗi learner nhiều nhất một lượt qua cho mỗi phiên bản đề (index UNIQUE có điều kiện), nên bấm nộp hai lần cùng lúc không đẻ hai dòng "đã qua". ## Chạy lại không đổi gì Chỉ CREATE TABLE IF NOT EXISTS và CREATE INDEX IF NOT EXISTS.

_{migration: 0325_walk_entry_profiles_and_quiz_passes.sql}

Cột	Kiểu	Ràng buộc / ghi chú
learner_id	TEXT	PRIMARY KEY REFERENCES learners(id)
phone	TEXT	—
full_name	TEXT	—
dob	TEXT	—
speaking_answers	TEXT	—
speaking_level	TEXT	—
speaking_confidence	TEXT	CHECK (speaking_confidence IN ('low', 'medium'))
occupation	TEXT	CHECK (occupation IN ('student', 'working', 'other'))
school_name	TEXT	—
school_grade	TEXT	—
workplace	TEXT	—
job_title	TEXT	—
completed_at	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'))

Khóa ngoại: learner_id → learners

walk_quiz_attempts

_{migration: 0325_walk_entry_profiles_and_quiz_passes.sql}

Cột	Kiểu	Ràng buộc / ghi chú
id	TEXT	PRIMARY KEY
learner_id	TEXT	NOT NULL REFERENCES learners(id)
quiz_version	TEXT	NOT NULL
score	INTEGER	NOT NULL
total	INTEGER	NOT NULL
answers	TEXT	NOT NULL
passed	INTEGER	NOT NULL DEFAULT 0 CHECK (passed IN (0, 1))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))

Khóa ngoại: learner_id → learners

Index: idx_walk_quiz_attempts_learner(learner_id, created_at) · idx_walk_quiz_one_pass(learner_id, quiz_version) UNIQUE

walk_registrations

Migration 0314 - walk registrations. SRC-1136, SDD-038 §146. ## Vì sao migration này tồn tại Chủ dự án 29.09.2026: NEMO WALK (15:00 Chủ nhật hằng tuần, miễn phí) cần đăng ký để biết bao nhiêu người đến và gửi thư xác nhận điểm hẹn. Mỗi learner đăng ký tối đa một lần mỗi tuần: khoá chính (walk_date, learner_id) chặn luôn hai lượt bấm cùng lúc. Lịch các tuần không nằm trong D1 mà ở workers/api/src/modules/walks/weeks.ts (bản sao của apps/learn/src/ielts/walk/weeks.json). Huỷ đăng ký là xoá dòng: không có tiền, không cần giữ vết. Cùng ngày, trước khi gộp: chỉ learner đã ghi danh NEMO SPEAK 1 (speak-2) hoặc NEMO SPEAK 2 (speak-3) mới đi WALK, mỗi lượt ghi danh cho 5 suất. course_id ghi suất của khoá nào đã được dùng; không có cột này thì người học cả hai khoá không đếm được còn bao nhiêu suất của từng khoá. ## Chạy lại không đổi gì CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS.

_{migration: 0314_walk_registrations.sql}

Cột	Kiểu	Ràng buộc / ghi chú
walk_date	TEXT	NOT NULL
learner_id	TEXT	NOT NULL REFERENCES learners(id)
course_id	TEXT	NOT NULL CHECK (course_id IN ('speak-2', 'speak-3'))
created_at	TEXT	NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
—	table constraint	PRIMARY KEY (walk_date, learner_id)

Khóa ngoại: learner_id → learners

Index: idx_walk_registrations_learner(learner_id, course_id)