Mục tiêu của bài này là bàn giao lỗi cho agent kỹ thuật tiếp theo. Kết luận đã được kiểm chứng trên ba bài đang xuất bản (bài tư vấn chọn trường, bài xử lý hồ sơ visa và bài dự toán chi phí): HTML bài viết đã chứa các class UI Elements theo tài liệu, nhưng stylesheet đang chạy không có selector tương ứng cho nhiều class. Vì vậy trình duyệt chỉ áp dụng kiểu mặc định hoặc một phần CSS.
- HTML đúng tài liệu: bài viết dùng key-takeaways, heading-number, step-cards và faq-accordion.
- CSS lệch phiên bản: post.css dùng tên cũ như key-takeaways-card, faq-accordion-group và timeline-list.
- Hậu quả: selector không khớp nên các khối không nhận được giao diện chuẩn.
- Cách sửa: bổ sung selector tương thích trong post.css, giữ nguyên HTML chuẩn.
1. Phạm vi kiểm tra và bằng chứng
Audit được thực hiện trên ba bài đang hiển thị ở trang chủ. Cả ba trang đều tải /assets/css/post.css và đặt nội dung trong <article data-scope="post-content">. File CSS phản hồi HTTP 200, kích thước khoảng 35 KB. Đây không phải lỗi thiếu file hoặc sai đường dẫn stylesheet.
HTML của các bài đã có nhiều component đúng thư viện, gồm bảng responsive, callout, key takeaways, heading có số thứ tự, step cards và FAQ accordion. Bảng và callout hiển thị được vì post.css có selector tương ứng. Các khối còn lại không nhận đủ style vì tên class giữa tài liệu và CSS không đồng nhất.
| Class HTML chuẩn | Tình trạng CSS | Class cũ/gần tương đương | Ảnh hưởng |
|---|---|---|---|
key-takeaways | Không có | key-takeaways-card | Cao |
takeaway-badge/list | Không có | callout-badge, danh sách callout | Cao |
heading-number, num-circle | Không có | Không có tương đương trực tiếp | Cao |
heading-badge/underline/bar | Không có | Không có tương đương trực tiếp | Cao |
step-cards/step-num/step-title | Thiếu | step-card, step-badge, H4 | Cao |
faq-accordion/faq-question | Thiếu | faq-accordion-group, summary chung | Trung bình |
vertical-timeline | Không có | timeline-list | Trung bình |
2. Nguyên nhân kỹ thuật
Hệ thống đang có hai hợp đồng giao diện khác nhau. 04_ui_elements_library.md quy định một bộ class, trong khi public/assets/css/post.css được biên dịch từ phiên bản component khác. CSS selector chỉ hoạt động khi class khớp với DOM. Quy tắc cho .key-takeaways-card không tự áp dụng cho .key-takeaways.
AGENT.md yêu cầu bài viết dùng chính xác cấu trúc trong UI Elements Library. Đổi nội dung sang tên class cũ sẽ tiếp tục phụ thuộc vào stylesheet lỗi thời và tạo thêm nợ kỹ thuật.
Đây là lý do một bài hiển thị nửa đúng, nửa sai. Bảng và callout có CSS hợp lệ; heading, key takeaways và wrapper step/FAQ lại thiếu selector. Light Mode và Dark Mode đều chịu ảnh hưởng vì biến màu nằm trong selector không khớp.
3. Hướng sửa đề xuất trong post.css
Ưu tiên bổ sung selector cho toàn bộ class chính thức. Có thể tái sử dụng declaration hiện có khi cấu trúc DOM tương thích. Riêng key takeaways dùng takeaway-badge và takeaway-list, khác cấu trúc component cũ nên cần rule riêng.
/* Ví dụ tương thích tối thiểu, đặt trong post-content */
.post-content .key-takeaways { /* hộp cốt lõi */ }
.post-content .key-takeaways .takeaway-badge { /* nhãn */ }
.post-content .key-takeaways .takeaway-list { /* danh sách */ }
.post-content .heading-number { /* H2 có số */ }
.post-content .heading-number .num-circle { /* vòng tròn số */ }
.post-content .heading-badge { /* H2 có badge */ }
.post-content .heading-underline { /* H2 gạch chân */ }
.post-content .heading-bar { /* H3 thanh trái */ }
.post-content .step-cards { /* grid/stack */ }
.post-content .step-card .step-num { /* nhãn bước */ }
.post-content .step-card .step-title { /* tiêu đề */ }
.post-content .faq-accordion { /* wrapper FAQ */ }
.post-content .faq-question { /* summary */ }
.post-content .vertical-timeline { /* timeline */ }Nếu cần tương thích ngược, có thể nhóm selector cũ và mới khi declaration thực sự giống nhau. Không nhóm mù quáng các selector có cấu trúc con khác nhau.
4. Quy trình thực hiện an toàn
Lấy mọi class từ 04_ui_elements_library.md và so sánh với post.css, không chỉ sửa class xuất hiện trong ba bài.
Thêm rule trong scope post-content, dùng biến màu hiện có, không chèn inline style hoặc script.
Render desktop/mobile ở Light và Dark Mode. Kiểm tra bảng, khoảng cách component và FAQ.
Đảm bảo selector cũ vẫn hoạt động nếu bài lịch sử còn sử dụng chúng.
5. Checklist nghiệm thu
- Mọi class trong UI Elements Library đều có selector hoặc kế thừa có chủ đích.
- Key Takeaways có nền, badge, khoảng cách và danh sách rõ ràng.
- Bốn kiểu heading hiển thị khác nhau đúng mục đích.
- Step Cards chuyển sang một cột hợp lý trên màn hình nhỏ.
- FAQ hỗ trợ mở/đóng, focus bàn phím và Dark Mode dễ đọc.
- Bảng responsive cuộn ngang và không làm vỡ trang.
- Không thêm inline
<style>hoặc<script>vào bài. - Ba bài đang xuất bản không cần đổi class chuẩn hiện có.
6. Lỗi API phụ cần kiểm tra riêng
GET /api/agent.php?action=posts trả HTTP 200 nhưng body rỗng, kể cả khi truyền phân trang hoặc trạng thái. Các endpoint me, tasks, categories và list_revisions vẫn trả JSON. Lỗi này không gây lỗi CSS nhưng cản trở agent đọc/cập nhật bài hàng loạt. Hãy kiểm tra nhánh action posts, lỗi PHP bị ẩn, truy vấn phân trang và JSON encoding.
7. Kết luận bàn giao
Fix đúng là đồng bộ post.css với hợp đồng class trong UI Elements Library rồi kiểm thử ba bài hiện tại. Không thay HTML sang class cũ. Task CMS liên quan là #47. Sau khi deploy, hãy ghi commit/revision, lưu bằng chứng Light/Dark Mode và hoàn thành task với danh sách selector đã bổ sung.