Nemo12 Docs

SDD-043 · Tick từng bước và vòng duyệt nội dung 08.10.2026 ​

Một phần của SDD-043. learner tick từng bước của lesson, lưu theo learner, quyền xem; vòng duyệt nội dung 08.10.2026.

15. Tick từng bước: "Mình đã làm xong bước này" (SRC-1283) ​

Chủ dự án 07.10.2026: lesson gồm các Activity, Activity gồm các Bước (AI Teen 1 chuyển sang năm Activity mỗi lesson ở SRC-1281; AI Teen 2-3 giữ ba journey Bắt đầu · Tìm hiểu · Đúc kết, cũng là Activity). Learner tick từng bước là đã làm xong; hệ ghi ở server theo learner (đổi máy vẫn còn); card Activity (§14) và NavBar phản ánh. Đã dựng 07.10.2026 (REQ-LRN-48); những gì dựng và các quyết định lúc dựng ở §15.8.

15.1 Ba loại bước, một luật xong ​

Bước của lesson không cùng một loại. Có bước máy đã biết là xong hay chưa (qua cổng đọc, trả lời đúng câu kiểm), có bước chỉ learner biết (đọc câu hỏi mở đầu, viết "Mang theo", làm thử trên máy). Tick là tín hiệu cho loại thứ hai; nó không được là đường vòng qua loại thứ nhất.

Loại (kind)BướcXong khiÔ tick trong card
gatedphần đọc có cổng (part-k)cổng của phần ấy QUA (§10), đọc từ dòng :gateskhông bấm được; tự tick khi qua; trước đó là ổ khoá hoặc ô trống kèm lời "Qua kiểm tra nhanh để xong phần này"
checkedcâu kiểm (qN), bước tổng kết câu kiểm (result của SRC-1281)câu ấy đúng (§8), hay mọi câu của Activity đã trả lờikhông bấm được; tự tick
selfmọi bước còn lại: question, read (bài không có cổng), output, next, bước ví dụ hay thực hành của năm Activitylearner tickbấm được; bấm lại là bỏ tick
  • ✍️ Tick KHÔNG thay cổng, cũng không thay câu kiểm. Server từ chối tick cho bước gated và checked (422 STEP_NOT_TICKABLE), nên một client sửa tay cũng không đi vòng được. Một bước cổng "xong" chỉ có một nghĩa: đúng 3/3; cho tick thêm một nghĩa thứ hai là để hai sự thật cùng nói về một bước và sớm muộn nói ngược nhau.
  • ✍️ Tick không đổi luật qua lesson. Lesson vẫn "qua" theo §8 (mọi trắc nghiệm đúng), unit vẫn sang Practice theo §9.2. Tick là tự khai công sức, không phải bằng chứng học được (bài học SRC-849: sổ bằng chứng không phải sổ công sức). Activity xong khi MỌI bước của nó xong theo bảng trên; lesson hiện "k/N bước" trong card và trong Mục lục, tách khỏi nhãn "đã qua".
  • Bước self ở cuối vùng chính có thêm một nút "Xong bước này" (cùng việc với ô tick, rồi cuộn tới bước kế), vì trên điện thoại card thường thu gọn. Nút ấy là chữ hành động nên tiếng Việt, không em dash.

15.2 Khoá lưu: slot, Activity, Bước ​

text
<course>:u<unit>:s<slot>:<activity>:<step>        ví dụ  ai-teen-1:u1:s7:understand:question
  • Slot, không phải vị trí (§12.4): đổi thứ tự lesson không làm tick gắn sang lesson khác; lesson gộp hay soạn lại lấy slot mới nên không thừa hưởng tick cũ.
  • Id Activity, không phải số: understand, check, review và các id của năm Activity mới (SRC-1281 chọn). Đổi tên hiển thị không đổi id (bài học SRC-1279).
  • Id Bước là định danh NỘI DUNG: bước self phải mang id khai trong dữ liệu (question, output, next, hay slug của bước ví dụ như compare-prompts), dạng ^[a-z][a-z0-9-]{1,31}$, KHÔNG được là id theo vị trí. part-k và qN là id theo vị trí nhưng chỉ dùng cho bước gated/checked, vốn không lưu tick (sự thật của chúng nằm ở cổng và kết quả bài tập, đã được slots.test.ts giữ). Soạn lại một bước đến mức đổi nghĩa thì đổi id; id cũ nghỉ, dòng cũ ở D1 bị bỏ qua khi đọc.
  • Test thuần giữ luật: mọi bước self có id khai, không trùng trong một Activity, không có dạng part-\d+ / q\d+.

15.3 Lưu ở đâu ​

Bảng mới ai_teen_step_ticks (số migration cấp bằng npm run migration:new lúc dựng, skill d1-migrate):

CộtKiểuLuật
learner_idTEXTFK learners, ON DELETE CASCADE
course_idTEXTid có trong courseIds.ts
unit_noINTEGERCHECK 1-20
lesson_slotINTEGERCHECK 1-20 (cùng trần slot của §12.4)
activity_idTEXTCHECK độ dài 2-32
step_idTEXTCHECK độ dài 2-32
ticked_atTEXTgiờ server, giữ nguyên khi tick lại
ticked_by_user_idTEXTluôn là tài khoản của chính learner (§15.4)

Khoá chính là cả sáu cột đầu; một dòng = một bước đang được tick, bỏ tick là xoá dòng (không giữ lịch sử, cùng luật §8). Chỉ mục (learner_id, course_id).

✍️ Bảng riêng, không nhét vào ai_teen_journeys như cổng đọc (§10) và chỉ báo (§13.4). Hai lần trước là trạng thái nhỏ, ghi thưa, một máy; tick thì nhiều (mỗi lesson 10-20 bước), ghi dày và hay từ hai máy cùng lúc. Một blob JSON mỗi unit nghĩa là đọc, sửa, ghi cả blob: hai lần tick gần nhau từ hai máy thì lần sau đè mất lần trước. Một dòng mỗi tick là UPSERT/DELETE nguyên tử, và đếm "k/N bước" cho mentor là một câu COUNT thay vì giải JSON.

15.4 API ​

RouteAiLàm gì
GET /v1/ai-teen/courses/{courseId}/steps?learner_id=learner, phụ huynh, mentor (canAccessLearner, QG-008)mọi tick self của learner trong course: {ticks: [{unit, slot, activity, step, ticked_at}]}
PUT /v1/ai-teen/courses/{courseId}/stepschỉ chính learner, đã ghi danh coursebody {learner_id, unit, slot, activity, step, done}; done: true UPSERT (giữ ticked_at cũ nếu đã có), false xoá; trả {tick} hay {tick: null}
  • Chỉ learner ghi. Ngoài canAccessLearner, PUT đòi tài khoản đang đăng nhập là tài khoản CỦA learner ấy (403 NOT_LEARNER cho phụ huynh, mentor, staff): tick là lời learner tự nói về mình, bố mẹ tick hộ thì con số mất nghĩa. Chưa ghi danh: 409, như §8.
  • Server kiểm bước có thật và là self. Bản kê bước tick được của từng course sinh vào phía API bằng node scripts/aiteen/gen-api-catalog.mjs (cạnh taskSkills.ts), program.test.ts đối chiếu với nội dung; khi nội dung vào D1 (SDD-056) server đọc thẳng bản phát hành. Bước lạ: 400 UNKNOWN_STEP; bước gated/checked: 422 STEP_NOT_TICKABLE.
  • Giới hạn. zod .strict(): learner_id 1-64 ký tự, unit và slot 1-20, activity/step theo regex 15.2, done boolean; thân yêu cầu dưới 1 KB. Rate limit bằng enforceRateLimit với luật mới aiTeenStepTick (120 lần / 60 giây / tài khoản, khai trong RATE_LIMITS), 429 kèm Retry-After. Số dòng mỗi learner bị chặn tự nhiên bởi bản kê (không ghi được bước không có).
  • Idempotent: tick hai lần cùng một bước không đổi gì; bỏ tick bước chưa tick trả {tick: null}.
  • Test hành vi (skill api-test, createTestDb()): tick và đọc lại, tick lại giữ ticked_at, bỏ tick xoá, phụ huynh và mentor đọc được nhưng ghi bị 403, người lạ 401 (§15.8), chưa ghi danh 409, bước cổng và câu kiểm 422, bước lạ 400, slot ngoài 1-20 400, quá rate 429.

15.5 Client ​

  • Luật thuần stepState(step, { gates, results, ticks }) trả done | open | locked theo bảng 15.1, ở cạnh journeys.ts; card, NavBar, Mục lục và bộ đếm "k/N bước" đều gọi nó (một chỗ khai luật xong).
  • Tick là lạc quan: card đổi ngay, PUT gửi ngay (không độ trễ, một lần bấm là một ý), lỗi thì trả ô về trạng thái cũ và báo một dòng.
  • Chưa ghi danh: tick giữ ở localStorage (nemo12.aiTeen.steps.<learner>.<course>, bọc try/catch), card nói "Ghi danh course để lưu tiến độ trên mọi máy"; ghi danh xong client gửi các tick ấy một lượt (hợp hai bên, không xoá tick nào ở server).
  • Dịch slot ở đúng ranh giới kho như §12.4 (slots.ts): giao diện làm việc theo vị trí, kho theo slot.

15.6 Mentor, phụ huynh và Evidence Registry ​

  • ✍️ Không ghi vào Evidence Registry. Tick không chứng minh hiểu hay làm được gì; đưa nó vào sổ bằng chứng là đúng lỗi SRC-849 (đếm công sức như năng lực). Bằng chứng của lesson vẫn là trắc nghiệm và thực hành (§11). Không nguồn EVIDENCE_SOURCES mới, Learner Model không đổi.
  • Mentor (Dolphin, tab AI Teen của §12 trang lát cắt): mỗi lesson thêm dòng "k/N bước đã tự đánh dấu xong · lần cuối DD.MM.YYYY", tính lúc đọc từ bảng (modelPage.ts). Đặt cạnh "đã qua" để mentor thấy chỗ đáng hỏi: tick đủ mà chưa qua câu kiểm, hay qua câu kiểm mà bỏ trống bước thực hành.
  • Phụ huynh: đọc được qua cùng route GET (quan hệ gia đình); Marlins chưa có màn AI Teen nên chưa hiện gì. Khi có, chỉ hiện số đếm theo lesson và ngày, không hiện giờ từng tick.

15.7 Riêng tư ​

  • Dữ liệu chỉ là id + giờ, không có chữ tự do của learner; không gửi bên thứ ba, không vào analytics.
  • Không route công khai nào trả tick; mentor đọc qua canAccessLearner, nên lượt đọc của vai nội bộ vào audit_log như mọi dữ liệu learner.
  • Xoá learner xoá tick (CASCADE). Rút course không xoá tick: ghi danh lại thì tiến độ còn nguyên, như kết quả bài tập.

15.8 Đã dựng (07.10.2026, SRC-1283) ​

PhầnỞ đâu
Bảngmigrations/0339_ai_teen_step_ticks.sql, đúng §15.3
Bản kê bướcworkers/api/src/modules/aiTeen/stepCatalog.ts, sinh bằng node scripts/aiteen/gen-api-catalog.mjs từ CHÍNH lessonJourneys + stepKind của learn (plugin esbuild thay import.meta.glob), nên không có bản luật thứ hai; steps.test.ts bên learn đối chiếu lại
APIGET / PUT /v1/ai-teen/courses/{courseId}/steps ở routes.ts, dịch vụ steps.ts; mã lỗi mới NOT_LEARNER (403), UNKNOWN_STEP (400), STEP_NOT_TICKABLE (422) trong shared/errors.ts và errors.md; luật aiTeenStepTick trong RATE_LIMITS
Luật xongstepKind + khoá ở apps/learn/src/aiTeen/steps.ts; luật xong vẫn là MỘT hàm, lessonStepState (journeys.ts), nay nhận thêm ticks; lessonStepCount cho "k/N bước"
ClientuseStepTicks.ts (lạc quan, trả về khi lỗi, bản trình duyệt khi chưa ghi danh); ô tick trong LessonOutline (card và sheet), nút "Xong bước này" cuối bước self; "k/N bước" đầu card và trong Mục lục (CourseTree.tsx)
DolphinmodelPage.ts trả steps (k/N theo lesson), apps/mentors/src/AiTeenReport.tsx hiện trong thẻ unit

Quyết định lúc dựng:

  • ✍️ Người lạ nhận 401, không phải 403. Ca test ở §15.4 ghi "người lạ 403", nhưng luật chung của errors.md là 401 cho mọi ai không có quyền với dữ liệu trẻ em, vì 403 lộ rằng learner ấy có thật. NOT_LEARNER 403 chỉ trả cho người ĐÃ đọc được learner (phụ huynh, mentor, staff), nên không lộ thêm gì.
  • ✍️ Bước self xong CHỈ khi được tick. Trước đây question tự "xong" khi qua phần đọc 1, output / next khi lesson đã qua; bảng §15.1 nói self xong khi learner tick, nên các luật suy đoán ấy bỏ hẳn, để không có hai sự thật cho một bước. Hệ quả: learner cũ mở lại lesson đã học sẽ thấy các bước self chưa tick (đúng nghĩa: em chưa từng tự khai).
  • ✍️ q0 (lesson không có câu kiểm) là bước checked: luôn xong, không tick tay.
  • ✍️ N của Dolphin là số bước self ("k/N bước đã tự đánh dấu xong"): server chỉ biết tick và bản kê, còn "k/N bước" của learner trong card đếm MỌI bước theo lessonStepState. Hai con số đo hai thứ khác nhau và chữ nói rõ cái nào là cái nào.
  • ✍️ Bản trình duyệt có dấu pending. Bản sao trình duyệt còn làm gương cho server (tải lại khi mất mạng vẫn thấy tick), nên chỉ tick làm lúc CHƯA ghi danh mới được gửi lên khi ghi danh; không có dấu ấy thì một tick đã bỏ ở máy khác sẽ sống lại từ bản sao của máy này.
  • Bước có cổng / câu kiểm hiện ô viền đứt (không bấm được, title nói cách xong), tick đặc khi xong; ô tick của bước self là role="checkbox" đứng CẠNH nút bước (control lồng trong button là HTML sai và không tới được bằng bàn phím), vùng chạm 40px.

Lịch sử quyết định ​

16. Vòng duyệt nội dung 08.10.2026 (SRC-1297) ​

Chủ dự án 08.10.2026 uỷ quyền duyệt toàn bộ nội dung đã soạn ("Bạn quyết toàn bộ và làm hết đi"). Vòng này chỉ sửa CHỮ: không đổi số lesson, slot, phần, câu, phương án hay khoá cổng.

  • Cổng đọc và câu kiểm (18 unit, gates/*, lessons/*): soát theo CD-8c và skill course-design §5b-§5g. Đáp án dài nhất (tính theo chữ, dài hơn cả hai nhiễu): sửa 250 câu cổng và 246 câu kiểm, nay không còn ca nào. Mâu thuẫn: 6 (AI Teen 1 U1: 2; AI Teen 3: 4 về số liệu và luồng), cộng 1 câu đáp không khớp dạng câu hỏi. Nhiễu nửa đúng: 1 (AI Teen 3 U4). Tham chiếu cũ "bài trước"/"lesson đầu": 4. Ký tự cấm: không còn ca nào; một dấu ngoặc thừa ở AI Teen 1 U1 đã gỡ.
  • Phát biểu kỹ thuật được làm cho chính xác và có rào: phím tắt DevTools (tuỳ trình duyệt và hệ điều hành, Safari phải bật menu Develop); vị trí trong ảnh (chỉ khi camera có quyền vị trí, nhiều mạng xã hội gỡ khi tải lên, gửi dạng file hay đặt trên web riêng thì thường còn); nslookup (IP mẫu thuộc dải tài liệu/riêng, ghi "máy em sẽ khác"); chữ hoa chữ thường trong tên file (nhiều máy chủ web phân biệt); cảnh báo chứng chỉ (chữ tuỳ trình duyệt, https chỉ là kết nối được mã hoá, không chứng minh trang đáng tin); CNAME ở tên miền gốc; giới hạn tuổi tài khoản dịch vụ; Teachable Machine (huấn luyện trong trình duyệt, dữ liệu chỉ rời máy khi lưu hoặc tải mô hình lên).
  • Nhãn khung tiếng Anh: U2 "Question / Size / Check / Spark" đổi thành Question / Size / Check / Hook (Hook là từ quen cho "điều kéo người đọc vào"); U4 giữ Fixed parts / Slots, đổi "Slot notes" thành Slot hints (gợi ý cho chỗ trống), áp đồng bộ ở bài đọc, cổng, câu kiểm và outcome.
  • Outcome (CD-6): bỏ mọi dấu "drafted / chờ chủ dự án duyệt" ở course, unit, lesson. Sửa 9 Lesson Outcome: gọn lại câu ba vế, bỏ khẳng định tuyệt đối ("chỉ ... mới", "ngay lập tức", "mất tác dụng"), chữa outcome Feedback loop mâu thuẫn với lesson kế, đồng bộ nhãn Slot hints.
  • Chỉ báo skill (§13.5): source đổi từ "nemo-draft" thành "nemo"; chỉ báo Level 1 của "Prompt AI effectively" đổi thành bốn phần mục tiêu, bối cảnh, yêu cầu, giới hạn cho khớp Unit 1.
  • Seed nội dung sinh lại bằng scripts/aiteen/export-content.mjs; nạp qua seed-data (lệnh ở đầu từng file scripts/aiteen/seed-content-ai-teen-*.sql).

Nemo12