Nâng cấp Trung tâm điều hành

Tám hạng mục bạn nêu chia làm hai khối. Khối A — giao diện & trải nghiệm (mục 1, 2, 3, 6 và toàn bộ phản hồi trực tiếp tối nay): chủ yếu là sửa template + CSS, làm được nhanh, ít rủi ro. Khối B — nền tảng (mục 4 phân quyền, mục 5 + 8 tốc độ, mục 7 cấu trúc học sinh): đụng dữ liệu và hạ tầng, cần làm cẩn thận theo bước.

Tình trạng triển khai · cập nhật 11/06/2026

Toàn bộ mã của Đợt 1–4 đã DỰNG, MERGE và XANH trên nhánh claude/website-redesign (575 bài kiểm thử đạt; đã rà soát bảo mật & tường lửa). Năm việc xây-thêm hôm nay cũng xong dưới dạng 5 PR nháp (#35–#39). Phần còn lại CHỈ là các bước vận hành thật cần bạn quyết: merge PR → deploy → bật phân quyền (cần danh sách người dùng) → nạp dữ liệu thật (có giám sát).

1Thiết kế, bố cục, phông & cỡ chữ

Mục tiêu: gọn, thoáng, bớt chữ in đậm, trông chuyên nghiệp như một tổ chức quốc tế. Hub hiện dùng phông serif Playfair Display cỡ lớn và in đậm cho mọi tiêu đề, cộng nhiều chữ đậm trong thân — tạo cảm giác "nặng" và "căng".

Vấn đề quan sát được

• Tiêu đề H1 serif quá lớn và đậm (vd. "Bài đợi duyệt", "Danh sách em" chiếm cả màn hình).
• Dùng chữ đậm tràn lan trong thân bài → mất điểm nhấn, đọc mỏi.
• Một tiêu đề lặp 3 lần trên cùng trang (tên mô-đun + breadcrumb + H1).
• Bảng kẻ đậm, chip trạng thái to, khoảng trắng chưa đều.

Đề xuất (chỉ sửa hmt.css + base.html, không đổi logic)

Đây là "đợt làm trước" — toàn bộ là CSS & template. Cần xem-bằng-mắt sau khi sửa (theo ghi nhớ design-system-source: CSS đã có, việc còn lại là markup + render rồi soi).

2Giao diện tiếng Việt toàn phần

Rà toàn bộ template, dọn hết chữ Anh còn sót, dùng tiếng Việt chuẩn. Danh sách dưới đây là đầy đủ các điểm tìm thấy (kèm vị trí tệp), để thi công một lượt.

Cách làm bền vững: tập trung mọi nhãn trạng thái & tên chương trình vào một bộ ánh xạ tiếng Việt (một dict trong report_common.py đã có sẵn nhãn petal/status — mở rộng nó), để template gọi chung thay vì rải chuỗi khắp nơi. Khi đó "dọn tiếng Anh" không bị tái diễn mỗi lần thêm trang.

3Trình bày tên & liên kết — ẩn vận hành kỹ thuật

Nguyên tắc: người dùng không bao giờ thấy chi tiết kỹ thuật — không tên tệp/script, không slug, không mã nội bộ, không thuật ngữ giai đoạn. Trang đọc-để-hiểu, không phải log hệ thống.

Các rò rỉ kỹ thuật phải bỏ (đã xác định vị trí)

Tên thẻ bài đợi duyệt — phản hồi tối nay

Khi phiếu thông tin chưa có tiêu đề, dùng quy tắc dựng tên: tên sự kiện (nếu có) → hoặc "Hoạt động tại [trường]" → ngày. Không bao giờ phơi slug làm tiêu đề.

4Phân quyền theo 3 mô-đun

Hiện tại đăng nhập là một mật khẩu dùng chung, được tất-cả-hoặc-không (care_auth.py: PBKDF2 + cookie ký HMAC; chưa có bảng người dùng, chưa có vai trò). Định tuyến đã chia sẵn theo tiền tố đường dẫn, nên việc chặn theo mô-đun là khả thi, gọn.

Ba mô-đun đề xuất

Mô hình thiết kế (giữ tối giản — đúng kỷ luật "không trừu tượng hoá sớm")

• Bảng user: username, display_name, password_hash, role, modules, active. role ∈ {admin, staff}; modules là danh sách trong {care, content, finance}.
• Admin = thấy & vào tất cả + có trang quản lý người dùng. Staff = chỉ các mô-đun được cấp.
• Phiên đăng nhập mang danh tính + danh sách mô-đun. Middleware ánh xạ tiền tố đường dẫn → mô-đun; chặn nếu không được cấp (303 về trang "không có quyền"), giữ nguyên cơ chế fail-closed hiện có.
• Thanh điều hướng & ô tổng quan chỉ hiện mô-đun người dùng có quyền (không treo cửa khoá).
• Thêm/sửa người dùng & đặt lại mật khẩu qua trang admin /quan-tri/nguoi-dung — không qua dòng lệnh (theo đúng tinh thần "không phơi vận hành").

Lưu ý an toàn: middleware phân quyền phải fail-closed — không có mô-đun nào ⇒ chặn, không phải mở. (Ghi nhớ review-depth-auth-failpath: lần trước cổng auth từng fail-OPEN; phải thử đường thất bại, không tin "đã đóng" trên giấy.)

5Vì sao chậm — nguyên nhân, lựa chọn & chi phí

Nguyên nhân (theo mức tác động)

Lựa chọn & chi phí

6Tìm kiếm — có cần không?

Ô tìm kiếm trên thanh đầu (topbar__search) hiện bị tắt, ghi "sắp có" — một tính năng chưa xây, đang chiếm chỗ và lộ ý "đang dở".

Khuyến nghị: bỏ hẳn ô tìm kiếm toàn cục. Lý do:

• Mỗi mô-đun đã có lọc/tìm riêng đúng ngữ cảnh (danh sách học sinh lọc theo tên/trường/trạng thái; danh sách nhà tài trợ tương tự).
• Một ô "tìm tất cả" mơ hồ ít giá trị mà tốn công xây + bảo trì chỉ mục.
• Bỏ đi làm thanh đầu sạch, đúng tinh thần "không phơi việc đang dở".

Nếu sau này muốn tìm-nhanh-một-học-sinh xuyên mô-đun, sẽ làm như một hộp "Tra cứu học sinh" trong mô-đun Chăm sóc (theo mã hoặc tên) — không phải ô toàn cục trên thanh đầu.

7Quản lý học sinh có cấu trúc

Đây là phần nền tảng và là gốc của các "lệch dữ liệu" trong báo cáo. Hiện mọi thứ móc vào journey-NNNN (cấp theo block từng trường, vô nghĩa với người đọc, lộ trên màn). Đề xuất một mô hình danh tính rõ ràng, ổn định, truy nguồn được.

7.1 · Hai loại mã, hai vòng đời

7.2 · Hai chương trình, tách rõ "người" và "lượt tham gia"

Mấu chốt để dữ liệu nhất quán: mã học sinh là cấp-người (ổn định), còn chương trình là một "lượt ghi danh" (có thể nhiều lượt theo thời gian).

Vì sao tách: hiện programme_slugs là chuỗi nối bằng dấu phẩy trên hàng child + lịch sử nằm trong YAML hồ sơ — khó truy vấn, dễ lệch. Tách thành bảng ghi_danh cho phép báo cáo theo chương trình, theo lứa, theo trường chính xác và xử lý đúng việc chuyển CETB→NBTL.

Hành động chuyển giai đoạn — dựng riêng cho từng bước (phản hồi tối nay)

7.3 · Sổ tay trên Drive (7f) — bản Google Doc + tài liệu nguồn có tổ chức

Thư mục của mỗi em đặt tên theo mã kèm tên em — vd. HS2026-0001 — Nguyễn Văn A: mã đứng trước để sắp xếp & tra cứu ổn định, tên theo sau cho dễ tìm bằng mắt trên Drive. Mã là khoá tra cứu; nếu tên đổi thì đổi tên thư mục, mã giữ nguyên. Khi ứng viên được nhận, tài liệu khảo sát (ở Khao-sat/<mã ứng viên> — Tên/) chuyển tiếp vào sổ tay học sinh để cuốn sổ liền mạch từ lúc khảo sát. Điểm vào là cuốn sổ tay:

7.4 · Công cụ OCR (7g) — quét → máy đọc được

Tận dụng đúng khuôn đã có: school_doc_extract.py đã dùng Opus-thị-giác đọc PDF học bạ/sổ điểm và trả dữ liệu có cấu trúc (Pydantic, messages.parse). Mở rộng thành công cụ chung tools/ocr_intake.py:

• Đầu vào: PDF hoặc ảnh quét (học bạ, sổ điểm, bài viết của em, phiếu đánh giá cảm xúc-xã hội).
• Đầu ra (3 thứ): (1) dữ liệu có cấu trúc cho hệ thống dùng (vào school_report khi là tài liệu học tập; văn bản + cấu trúc nhẹ cho bài viết); (2) một Google Doc đọc được nộp vào 2_Hoc-sinh/Tai-lieu-so-hoa-OCR/<mã>/; (3) một dòng nhật ký hồ sơ (xem 7.5) ghi rõ nguồn.
• Giữ khuôn *Engine Protocol + Fake*Engine để test offline; không đặt temperature/top_p; dùng messages.parse (theo kỷ luật Opus đã ghi).

Tách trường dữ liệu — KHÔNG dồn cục (phản hồi tối nay)

7.5 · Tài liệu cho nhiều học sinh (7h)

Engine trích đã hỗ trợ trả danh sách bản ghi (mỗi em một bản, đè journey_id riêng). Bổ sung bước khớp tên với danh bạ: nâng "bộ khớp tên kép" từ script backfill thành tools/roster_match.py dùng lại được. Một tài liệu phủ nhiều em ⇒ tách, định tuyến phần dữ liệu liên quan về đúng hồ sơ từng em.

7.5 · Nhật ký & truy nguồn (7i) — phần quan trọng nhất cho "hết lệch dữ liệu"

Bảng profile_entry đã là nhật ký theo em: có entry_date, source, by_person, petal, summary_line, detail, raw_link. Cần siết và phơi ra:

• Bắt buộc nguồn: mỗi lần đăng ký một dữ kiện cho em ⇒ tạo một dòng nhật ký với nguồn gốc thật (raw_link trỏ tới tài liệu gốc đã nộp trên Drive).
• Thêm source_ref: chỗ cụ thể trong tài liệu (trang/mục/dòng) để khi có câu hỏi "con số này ở đâu ra" thì bấm vào dòng nhật ký là tới đúng nguồn.
• Trình bày dòng thời gian trên trang hồ sơ: mỗi mục ghi "Nguồn: [tên tài liệu] · [ngày] · [người ghi]", liên kết tới bản số hoá.

Đây chính là cơ chế trả lời "chi tiết X trong báo cáo lấy từ đâu" — không cần đoán, bấm là thấy nguồn.

7.6 · Đặt tên báo cáo dễ hiểu bằng tiếng Việt (7j)

7.7 · Thiết kế & thương hiệu cho báo cáo (phản hồi tối nay)

Áp dụng cho cả ba loại báo cáo (cá nhân · theo trường · theo chương trình), ở cả bản xem trong hub (HTML) và bản tải về (.docx):

Cách làm: một mẫu báo cáo dùng chung — bộ style .docx có sẵn header/footer + logo cho markdown_to_docx, và một CSS báo cáo dùng chung cho bản HTML — để cả ba loại báo cáo đồng bộ một diện mạo, sửa một nơi áp dụng mọi nơi.

7.8 · Thứ tự hiển thị học bạ & tiến triển điểm (phản hồi tối nay)

7.9 · Backfill (7a, 7e) — đưa dữ liệu cũ vào khuôn mới

1. Cấp HSYYYYNNNN cho ~142 em hiện có (từ năm vào Quỹ + số thứ tự), giữ journey-NNNN nội bộ.
2. Chuyển programme_slugs + trạng thái hiện tại → mỗi em một (hoặc nhiều) dòng ghi_danh.
3. Tạo hồi tố hồ sơ ứng viên UV… cho các em có dữ liệu khảo sát; phần thiếu đánh dấu "không rõ giai đoạn ứng viên".
4. Gắn tài liệu OCR đã có (đang ở Tai-lieu-so-hoa-OCR/) về đúng thư mục từng em, kèm dòng nhật ký nguồn.
5. Tạo sổ tay cho tất cả ~142 em hiện có (không chỉ em mới): tạo thư mục 2_Hoc-sinh/Ho-so/<mã>/ cho từng em rồi dựng Google Doc sổ tay từ dữ liệu đã có (hồ sơ + nhật ký + điểm + phúc lợi). Chạy hàng loạt một lần, sau đó nút "Cập nhật sổ tay" giữ cho mới.

Lưu ý vận hành: mọi nạp dữ liệu vào bucket chăm sóc phải chạy một lần một, chốt WAL trước khi tải lên, và làm yên hub trước (ghi nhớ gcsfuse-db-write-race + va chạm đa-agent). Dữ liệu thật là bản sao duy nhất — sao lưu trước mỗi lần đụng.

8Báo cáo chạy nhanh / chạy nền

Hiện tạo báo cáo là đồng bộ trong handler ⇒ khoá worker 3–5s (đôi khi 2 lần gọi Opus), hub đứng với mọi người.

Đề xuất: tách việc tạo báo cáo ra chạy nền

• Bấm "Tạo báo cáo" ⇒ trả ngay "Đang tạo, sẽ báo khi xong" (HTTP 202), không bắt người dùng đợi.
• Việc tạo chạy ở Cloud Run Job riêng (khuôn này đã có cho việc "yêu cầu viết bài" — request_story kích Job ở nền). Dùng lại cho báo cáo.
• Xong ⇒ ghi tệp + một dòng vào chỉ mục báo cáo; trang Báo cáo hiện trạng thái "đang tạo / đã xong" và tự cập nhật (poll nhẹ) — hub không bao giờ treo.
• Giai đoạn sau (khi có đường email): gửi liên kết báo cáo khi xong (đáp ứng "gap email-link-back" đã ghi nhận).

Kết hợp với gói tốc độ ở mục 5 (giữ máy ấm + 2 worker), trải nghiệm sẽ "tức thì khi xem, không đứng khi tạo".

Danh sách lỗi giao diện từ buổi soi tối nay

Tổng hợp các điểm bạn chỉ trực tiếp, ánh xạ về hạng mục & đợt thi công.

Thứ tự thi công & ước lượng

Hai hạng mục trong kế hoạch chưa thành task riêng & vẫn còn: nhóm/gập danh sách ~1000 em (bộ chọn nhóm + phân trang) và backfill hồ sơ ứng viên UV hồi tố. Báo cáo theo trường/lứa đã có (đang ở PR #35, chờ hoà giải).

Bước tiếp theo cho quản trị viên: (1) duyệt hướng đi tổng thể; (2) trả lời 4 câu quyết định ở trên; (3) cho phép bắt đầu Đợt 1 (giao diện) ngay — đây là phần an toàn nhất và đem lại cảm giác "mới" rõ nhất. Mọi thay đổi nằm trong nhánh claude/website-redesign; không đụng Giai đoạn A (mọi bài vẫn cần duyệt tay, không đăng tự động). · HMT · 11/06/2026