SDD-023 · Lịch sử tiếp xúc, trang chủ cổng và quyền mentor qua Access
Một phần của SDD-023. Lịch sử tiếp xúc và phát hiện im lặng, trang chủ cổng sáu cụm gập lại, ai qua Cloudflare Access thì là mentor.
25. Lịch sử tiếp xúc, và việc phát hiện im lặng (SRC-691)
Chỉ đạo 2026-09-08: cần biết bố mẹ nào đã gặp trực tiếp, gặp mấy lần, lần gần nhất cách đây bao lâu, và lần trao đổi qua chat gần nhất là khi nào. Lý do nêu kèm mới là thứ định hình thiết kế: "khi ko trao đổi với phụ huynh, thì dần dần phụ huynh và con của họ nghỉ học hết."
Câu đó biến việc này từ một sổ ghi chép thành một cái cảnh báo. Một cái sổ trả lời "chuyện gì đã xảy ra"; nó được đọc khi người ta đã nghĩ tới việc mở nó ra. Nhưng gia đình sắp nghỉ học đúng là gia đình không ai còn nghĩ tới — nên cái sổ ấy sẽ không được mở đúng lúc nó có ích nhất. Vì vậy đợt này làm hai phần, và phần thứ hai mới là phần trả nợ cho lý do trên.
25.1 Hai cột, không phải một bảng mới
family_notes nhận thêm channel và happened_on (migration 0208), thay vì dựng bảng family_meetings riêng. Một lần gặp đã là một ghi chú: mentor gặp phụ huynh xong thì viết lại nội dung, và tag event đã mang nghĩa "có chuyện xảy ra". Tách ra bảng riêng nghĩa là mentor phải ghi hai chỗ cho một lần gặp — và chỗ thứ hai là chỗ sẽ bị quên. Đây đúng là cách phần lớn CRM chết dữ liệu: cái log tách khỏi nội dung, rồi không ai điền log.
channel không phải một tag, dù danh sách tag đã có sẵn và thêm vào đó thì rẻ hơn. Tag là nghĩa của nội dung (pain · jtbd · goal…); kênh là đường mà nội dung đó tới. Hai trục vuông góc — một ghi chú vừa là pain vừa xảy ra khi gặp trực tiếp. Nhét kênh vào tag thì danh sách đóng phình gấp đôi, và mọi câu đếm phải quét tags_json LIKE '%…%', đúng thứ Audit #005 đã phải gỡ ra một lần vì nó không dùng được chỉ mục.
happened_on tách khỏi created_at vì hai ngày đó khác nhau trong đời thật: mentor gặp thứ Bảy, tối Thứ Ba mới ngồi viết. Đếm theo created_at thì "gặp cách đây bao lâu" sai đúng bằng khoảng mentor còn nợ việc ghi chép — và với một chỉ số dùng để phát hiện im lặng, sai theo hướng lạc quan là kiểu sai tệ nhất: nó giấu đúng những nhà cần gọi.
Năm kênh: in_person · video · call · chat · email. video đứng riêng khỏi cả in_person lẫn chat có chủ đích — chỉ đạo hỏi riêng về "gặp trực tiếp" nên số đếm đó không được lẫn một cuộc Meet vào, nhưng gộp video vào nhắn tin cũng sai: ngồi nhìn mặt nhau nửa tiếng không cùng hạng với vài câu nhắn.
25.2 Thang im lặng, và vì sao "chưa bao giờ" khác "đã lâu"
silenceLevel() xếp bốn mức: ok → watch (>30 ngày) → alarm (>60 ngày), và never đứng riêng. Hai ngưỡng là phỏng đoán — chưa có dữ liệu bỏ học nào của Nemo12 được đối chiếu để rút ra chúng, và điều đó được ghi thẳng trong contactLog.ts để không ai đọc chúng như một kết luận. Khi đã đủ số ca nghỉ để đối chiếu thì phải đo lại: nếu phần lớn ca nghỉ có khoảng im lặng cuối cùng ngắn hơn 60 ngày, ngưỡng này đang báo động quá muộn, tức là vô dụng đúng lúc cần nhất.
never tách khỏi alarm vì việc phải làm khác nhau: alarm là nối lại một quan hệ đã có, never là bắt đầu từ đầu.
Một luật nhỏ nhưng quyết định việc màn này có được dùng hay không: nhà vừa được tạo, chưa tiếp xúc lần nào, KHÔNG phải báo động — nó là nhà chưa ai kịp làm gì. Không phân biệt hai thứ đó thì mỗi lần nhập liệu đẻ ra một báo động giả, và một danh sách cảnh báo đầy báo động giả sẽ bị bỏ qua toàn bộ, kể cả những dòng đúng. Vì vậy silenceLevel() nhận thêm tuổi của gia đình.
25.3 Lọc trong SQL, không lọc mảng kết quả
Ô lọc "lâu rồi không ai trao đổi" chạy trong WHERE, không lọc mảng sau khi đã LIMIT 200. Lọc sau thì nhà im lặng nằm ở vị trí 201 không bao giờ hiện ra — mà đó đúng là nhà cần tìm nhất: im lặng lâu đồng nghĩa updated_at cũ, tức là bị chính câu ORDER BY đẩy xuống cuối. Điều kiện SQL phải khớp đúng silenceLevel() !== "ok"; hai chỗ lệch nhau thì danh sách lọc ra một tập còn phù hiệu trên từng dòng nói một tập khác, và không ai biết bên nào đúng.
Cùng lý do "đếm phải đếm đủ": ở màn chi tiết, tóm tắt lấy từ truy vấn riêng, không suy ra từ danh sách ghi chú đang hiển thị — danh sách đó có LIMIT 200, nên với một nhà theo lâu năm thì "đã gặp mấy lần" sẽ đếm thiếu mà không có dấu hiệu nào.
25.4 Vẽ ở đâu — hai màn, hai luật khác nhau
| Màn | Hiện gì | Vì sao |
|---|---|---|
| Danh sách | chỉ phù hiệu im lặng, khi khác ok | Nhà đang liên lạc bình thường là đa số; một dấu hiệu hiện ở mọi dòng thì không phân biệt được gì (luật §Ký hiệu, SRC-649) |
| Chi tiết | luôn hiện đủ: gặp mấy lần · gần nhất · chat gần nhất | Đây là nơi người ta vào để biết về đúng nhà này |
Phù hiệu dùng chữ chứ không dùng icon, dù chỉ đạo chung là ưu tiên icon: "47" là thông tin, mà không hình vẽ nào nói được một con số — icon ở đây chỉ nói được "có gì đó", đúng loại dấu hiệu vô dụng mà SRC-649 vừa dọn đi.
Ô lọc mặc định tắt. Bật sẵn thì màn chính chỉ còn các nhà đang có vấn đề, và mentor mất đường vào những nhà mình vẫn đang chăm bình thường.
25.5 Giới hạn, nói thẳng
"Chat" là số liệu ghi tay. Nemo12 không có hệ nhắn tin hai chiều — trao đổi thật diễn ra trên Zalo/Messenger, ngoài hệ thống. Hệ email hiện có (email_sends, email_opens) là một chiều: mình gửi đi, và một bản tin đã gửi không phải một cuộc trao đổi. Nghĩa là con số "chat gần nhất" chỉ đúng bằng mức mentor chịu ghi lại, và các lần gặp trực tiếp — vốn hiếm và đáng nhớ — sẽ được ghi đầy đủ hơn hẳn các lần nhắn tin. Đọc chỉ số này mà quên điều đó sẽ dẫn tới kết luận sai theo hướng bi quan ở cột chat. Nối Zalo để đếm tự động là việc riêng, chưa làm.
26. Trang chủ của cổng: sáu cụm gập lại (SRC-1176)
Chỉ đạo 01.10.2026: "Từ trang HOME của dolphin.nemo12.com, vào đó thì nhìn thấy 6 cụm menu-item. Mỗi cụm, bên trong chúng có vài menu items nhỏ hơn. Mặc định thì có 6 card được collapsed."
26.1 Cổng này chưa từng có trang chủ
Trước đợt này / đưa thẳng về danh sách gia đình. Đó là lựa chọn đúng của SRC-585, khi cổng chỉ có năm khu và danh sách gia đình đúng là việc chính. Nhưng cổng nay có mười ba khu, và cái dropdown ở header (SRC-649) đã thành một danh sách mười ba dòng phẳng.
Mười ba dòng phẳng không có cấu trúc thì người mới phải đọc hết mới biết cổng này làm được những gì. Sáu cái tên thì đọc được trong một nhịp.
Dropdown vẫn ở đó và vẫn đúng việc của nó: chuyển khu khi đã biết mình muốn đi đâu. Trang chủ trả lời câu hỏi khác — ở đây có những gì.
26.2 Sáu cụm chia theo CÂU HỎI, không theo loại dữ liệu
Mentor không mở cổng này để "xem bảng families"; họ mở nó với một câu hỏi trong đầu. Nên tên cụm là câu hỏi ấy, và hai khu nằm cùng cụm khi chúng trả lời hai nửa của cùng một việc.
| Cụm | Khu bên trong | Vì sao chúng đi cùng nhau |
|---|---|---|
| Learners and families | Families · Desk | Cùng một đối tượng, hai đường vào: từ một gia đình, và từ việc hôm nay phải chạm vào ai |
| Teaching | Calendar · Slots · Live Session | Ba mốc của cùng một buổi dạy: buổi nào SẼ có, buổi nào ĐÃ có, và sáu mươi phút đang diễn ra |
| What we teach | Curriculum · Events | Nội dung và cách tổ chức nội dung |
| Reviewing the whole cohort | Dashboards · Where learners are | Cả hai trả lời "cả nhóm đang thế nào", khác nhau ở chỗ cái sau trả lời bằng ĐỊA ĐIỂM |
| People and schools | Team · Schools | Sổ tra cứu về người và tổ chức bên ngoài một gia đình |
| What the public sees | Testimonials · Albums | Sửa ở đây là đổi thứ người ngoài đang xem trên nemo12.com |
Đường may yếu nhất là "People and schools", và nói ra thì tốt hơn giả vờ nó sạch: Team là mentor của mình, Schools là các trường mình theo dõi. Chúng chung nhau đúng một điều, và không khu nào đủ lớn để đứng riêng một thẻ. Khi một trong hai mọc thêm vài khu nữa thì tách ra.
26.3 NHÓM là nguồn, danh sách phẳng suy ra từ nó
apps/mentors/src/sections.ts khai GROUPS; SECTIONS là GROUPS.flatMap(g => g.items).
Giữ hai danh sách song song sẽ mở ra đúng một cách hỏng: một ngày nào đó một khu mới được thêm vào định tuyến mà không có mặt ở trang chủ — nó không sai ở đâu cả, nó chỉ không ai tìm thấy. Loại hỏng im lặng, không màn hình nào báo gì. Nay thêm một khu thì bắt buộc phải chọn cụm cho nó, vì không có chỗ nào khác để khai. sections.test.ts chốt lại điều đó.
26.4 Ba quyết định nhỏ
Accordion của shadcn, không tự viết. Gập/mở là chỗ rất dễ hỏng ở phần không nhìn thấy: aria-expanded, liên kết nút với vùng nội dung, mũi tên lên xuống, focus rơi vào vùng đang ẩn. Radix làm sẵn cả bốn — đúng phân vai DS-001 §5d: shadcn lo HÀNH VI, token lo hình thức.
Mở được nhiều cụm cùng lúc. Accordion một-lúc-một-cái sẽ tự đóng cụm đang mở khi bấm cụm khác, mà đây là trang dùng để SO SÁNH xem nên đi đâu; tự đóng là việc người dùng không yêu cầu.
KHÔNG nhớ cụm nào từng mở. Chỉ đạo nói rõ "mặc định thì có 6 card được collapsed"; nhớ lại trạng thái cũ sẽ phá đúng câu đó ở mọi lần vào sau. Cái giá là mỗi lần vào là một lần bấm.
26.5 Hai thứ suýt hỏng âm thầm, bắt được vì mở trình duyệt ra xem
- Thẻ gập bị kéo cao bằng thẻ đang mở. Mặc định của CSS grid là
stretch, nên một thẻ còn gập nằm cạnh một thẻ đang mở biến thành một ô trống to tướng — trông đúng như một thẻ hỏng.items-startchữa. Typecheck, lint và test đều không nói gì về chuyện này. - Hai lối tắt của SRC-892 suýt bị bỏ lại. Chỉ đạo 20.09.2026 nói "từ trang HOME cần có link tới trang này", và lúc ấy "trang chủ" chính là danh sách gia đình, nên
HomeLinksnằm ở đó. Dựng một trang chủ thật mà không chuyển chúng sang thì link vẫn còn, chỉ là không còn ở trang chủ nữa — chỉ đạo cũ bị phá mà không có dấu hiệu nào. Nay chúng đứng TRÊN sáu cụm, không nằm trong cụm nào: hai việc thường xuyên nhất của cả cổng không nên nằm sau một cú bấm mở cụm.
26.6 Đường lạ nay về trang chủ, không về Families
sectionFor() trả null cho cả / lẫn đường dẫn không khớp khu nào. Trước đợt này đường lạ rơi về Families, nên một URL gõ sai hiện ra một danh sách trông hoàn toàn bình thường và người dùng không hề biết mình đã không tới được chỗ mình nhắm.
Phép khớp cũng chặt lại: path === s.path || path.startsWith(s.path + "/") thay cho startsWith suông — startsWith("/team") nuốt cả /teamwork.
26.7 Icon và một dòng mô tả cho mỗi cụm (SRC-1177)
Thẻ gập chỉ còn một cái tên, mà một cái tên như "What we teach" không nói được bên trong có gì. Mỗi cụm nay có icon và một dòng mô tả câu hỏi mà cụm ấy trả lời, khai cùng chỗ với cụm trong apps/mentors/src/sections.ts (trường icon, blurb). Đây là chữ thêm vào, trái chiều luật tối giản (SRC-048), nhưng nó trả lại nhiều hơn chỗ nó chiếm: không có nó thì cách duy nhất để biết bên trong là bấm thử từng cụm.
Icon là emoji, không phải N12Art: DS-001 §2c cấm emoji làm icon chính của sản phẩm mà learner và phụ huynh nhìn thấy, còn đây là cổng nội bộ và HomeLinks đã dùng đúng lối này từ SRC-892.
Kèm một lỗi có sẵn: cardClass nay mang flex flex-col, nên hai thẻ lối tắt nối thêm flex items-center vào cuối chuỗi KHÔNG đè được — thẻ xếp theo cột, icon rơi xuống dòng riêng và bị căn giữa. Sửa bằng flex-row qua cn().
27. Ai qua Cloudflare Access của dolphin thì là mentor (SRC-1262)
Chỉ đạo 06.10.2026: "Mọi tài khoản vào được dolphin.nemo12.com qua Cloudflare Access, thì đều có Role là mentor. Email nào cũng là mentor hết, miễn là vượt qua Cloudflare Access."
Trước đây có hai danh sách phải giữ khớp tay: policy của Access (ai được mở trang) và role_assignments (vào rồi được xem gì). Người mới được thêm vào Access mà quên gán vai thì đăng nhập xong gặp một màn rỗng, trông như lỗi hệ thống. Nay danh sách duy nhất là policy của Access; vai mentor đi theo nó.
Đường đi. Sau khi đăng nhập Google, trang gọi POST /auth/mentor-grant trên chính dolphin.nemo12.com. Worker của dolphin (apps/mentors/worker.ts, mới) đứng sau Access nên cầm được header Cf-Access-Jwt-Assertion; nó chuyển header ấy cùng cookie phiên xuống POST /v1/auth/mentor-grant. Cùng khuôn với admin.nemo12.com (SRC-129).
Ba điều kiện ở API (workers/api/src/modules/auth/mentorGrant.ts), thiếu một là không cấp:
- Có phiên đăng nhập hợp lệ.
- JWT của Access có chữ ký hợp lệ và cấp cho đúng app Nemo12 Dolphin (
ACCESS_AUD_DOLPHIN, khác AUD của admin). Test chứng minh JWT của admin không lấy được vai mentor, và JWT của dolphin không mở được cửa admin. - Email trong JWT trùng email của tài khoản đang đăng nhập. Không có điều này thì một người qua Access bằng email A rồi đăng nhập Google bằng email B sẽ cấp vai cho B.
Vì sao không dựa vào header Origin: api.nemo12.com không nằm sau Access, và Origin thì ai gửi request ngoài trình duyệt cũng tự đặt được. Mentor xem được dữ liệu của mọi học viên, nên vai này phải đứng trên một thứ có chữ ký.
Người đã là mentor thì endpoint trả về ngay, không kiểm JWT và không tính vào giới hạn đăng nhập. Mỗi lần cấp hoặc từ chối vì lệch email đều ghi nhật ký truy cập.
Không tự gỡ vai. Bỏ một email khỏi policy Access là người ấy không mở được dolphin nữa, nhưng vai mentor trong ứng dụng vẫn còn (và vẫn đọc được API nếu còn phiên). Muốn thu hồi hẳn thì gỡ vai bằng seed-data. Đồng bộ chiều gỡ là việc riêng, chưa làm.
28. Thanh bên trái và breadcrumb (SRC-1320)
Chủ dự án 10.10.2026: tìm skill UI/UX cho admin trên GitHub rồi chỉnh thanh điều hướng và các trang Dolphin theo tiêu chuẩn mới, chia đợt. Tiêu chuẩn ghi ở .claude/skills/dolphin-ui/SKILL.md, chắt từ skill shadcn (shadcn-ui/ui) và web-design-guidelines (vercel-labs); hai skill ấy không cài vào repo vì một cái tự chạy npx shadcn@latest (trái luật ghim số), một cái tải luật từ mạng mỗi lần chạy.
Đợt 1 (đợt này) là khung trang:
- Thanh bên trái
apps/mentors/src/Sidebar.tsxtừlgtrở lên, thay dropdown của §SRC-649. Sáu cụm của §26 làm tiêu đề nhóm; gập được còn một cột chữ tắt (hai chữ đầu tên khu), nhớ lựa chọn trong trình duyệt. Dướilgvẫn là dropdown, vì không đủ chỗ cho một cột cố định. - Breadcrumb Home › Cụm › Khu trên đầu mọi trang con; mục cuối không phải link.
- Mỗi cụm mặc định đóng (chủ dự án 10.10.2026), dựng bằng
Accordioncủa bộ shadcn chung; bấm vào cụm mới mở. Riêng cụm chứa trang đang mở thì mở sẵn, để mục đang chọn không bị giấu. - Icon là Heroicons (
@heroicons/react2.2.0, bản outline 24px, chủ dự án 10.10.2026), thay emoji ở Home, sáu cụm và nút thu gọn. Ánh xạ cụm sang icon nằm ởGROUP_ICONStrongSidebar.tsx.
Các đợt sau làm từng nhóm trang theo bốn loại của skill (danh sách, xem, sửa tại chỗ, tạo mới), mỗi đợt vài trang, để không xung đột với các phiên khác đang sửa Dolphin. Trang Events (SRC-1312) là trang mẫu đầu tiên đã theo đúng bốn loại.
Đợt 2 (cụm People and schools, phần Team): /team mỗi thẻ là link thật; "Add person" mở trang riêng /team/new, tạo xong chuyển tới hồ sơ vừa tạo; /team/:id chỉ đọc, nút Edit ở góc trên phải, Save/Cancel thay đúng chỗ ấy; bỏ nút Delete hồ sơ (muốn rút thì Unpublish). Schools để đợt sau.
Rà design system so với nemo12.com (10.10.2026). Chủ dự án chốt: design system của nemo12.com là chuẩn. Kết quả rà: Dolphin khớp MỘT PHẦN. Cùng token màu, cùng file CSS nền, cùng bản sao component shadcn (accordion, badge, button, card, dialog, input, label, table, tabs, textarea trùng canonical; select là fork có lý do ghi ở copies.json). Lệch ở lớp trên:
- Chưa nạp
soft.cssvà chưa gắntheme-soft n12-v1ở gốc trang, nên bo góc, đổ bóng và kiểu nút khác www. Đã sửa ở đợt này:apps/mentors/src/index.cssnạpsoft.css,index.htmlgắn hai lớp lên body, nềnbg-sandriêng đổi sang tokenbg-background. - Còn khoảng 150 chỗ dùng lớp cũ
n12-*(30 chỗ trong nhóm cổng SRC-570 đếm, phần còn lại nhưn12-section-title,n12-empty,n12-chip,n12-tabcổng chưa đếm), 73 thẻbuttonvà 21 thẻinputtrần thay vì component, 36 emoji làm icon,text-ocean-90060 chỗ. - Header là bản dựng riêng, không phải
SiteNavcủa www.
Việc tiếp, theo thứ tự: chuyển lớp n12-* và thẻ trần sang component theo từng nhóm trang (hạ trần SRC-570 mỗi đợt); mở rộng cổng SRC-570 để đếm cả các lớp chưa đếm; thay emoji bằng icon chung; đưa phần .theme-www dùng chung được vào packages/design-system; thêm cổng bắt mọi cổng nội bộ nạp soft.css và gắn lớp theme ở gốc.
Lịch sử quyết định
Trang này chỉ chứa đặc tả đang hiệu lực; các vòng sửa của mảng này nằm ở những trang khác trong cùng thư mục, xem mục lục.