⌨️ Thế Giới Keycap Docs Architecture
📊 Dashboard Hub Kiến Trúc Registry Protocol Môi Trường Vận Hành Tích Hợp

PROJECT_MAP.md — thegioikeycap.vn

Bản đồ kiến trúc, thư mục và module. Đọc phần liên quan trước khi sửa code.

Tổng quan kiến trúc

Khách  ──►  nginx (host)  ──►  PHP-FPM  ──►  WordPress + WooCommerce
                                              │
                                              ├─► MySQL 8.4 (keycap_mysql)
                                              ├─► SePay      (QR chuyển khoản)
                                              ├─► Brevo      (gửi email, qua FluentSMTP)
                                              └─► Meta CAPI  (plugin tgk-tracking)

Pancake POS  ──WC REST key──►  WooCommerce     (đẩy sản phẩm, giá, tồn kho)
WooCommerce  ──3 webhook────►  Pancake POS     (đẩy đơn hàng)
Pancake POS  ──feed────────►  Facebook Catalog (Content ID = SKU)

Điểm cần nhớ: WooCommerce không phải nguồn dữ liệu sản phẩm. Pancake đẩy sang. Sửa giá/tồn ở Woo sẽ bị ghi đè.

Bảng thư mục chính

Đường dẫn Vai trò Trong git?
docker/docker-compose.yml Định nghĩa 2 service: php, mysql ✅
docker/nginx-thegioikeycap.vn.CUTOVER.conf vhost đang chạy; đầu file có quy trình rollback về Astro ✅
docker/php/, docker/mysql/ Cấu hình image ✅
docker/setup-brevo-dns.sh Script tạo bản ghi DNS xác thực Brevo ✅
docker/.env Symlink trỏ về ../.env ❌
.secrets.env Symlink trỏ về .env (tương thích script cũ) ❌
.env Source of truth biến môi trường (chmod 600, www-data) ❌
.env.example File mẫu môi trường chuẩn (không chứa secret) ✅
logs/nginx/, logs/php/ Log, có logrotate ❌
www/ Webroot WordPress một phần
www/wp-config.php Secret WP + hằng số TGK_* ❌
www/wp-content/themes/thegioikeycap/ Theme tự viết ✅
www/wp-content/plugins/tgk-tracking/ Plugin tự viết ✅
www/wp-content/uploads/ Ảnh sản phẩm ❌
www/wp-admin/, www/wp-includes/ WP core ❌

.gitignore theo kiểu whitelist — mặc định bỏ qua tất cả, chỉ thêm những đường dẫn của mình. Thêm thư mục mới phải khai vào đó.

Module: Theme thegioikeycap

Classic template hierarchy. functions.php nạp 12 file inc/ theo đúng thứ tự dưới đây (thứ tự có ý nghĩa: site-config và helpers phải trước).

Lớp nền

File Dòng Vai trò
functions.php 345 Nạp inc/, theme support, đăng ký menu/sidebar, thiết lập permalink và trang mặc định
inc/site-config.php 81 Source of truth thông tin shop: SĐT, địa chỉ, mạng xã hội, ngưỡng freeship
inc/helpers.php 116 Icon SVG inline, đọc data/*.json, breadcrumb, danh sách danh mục
inc/nav.php 89 Menu chính + link sản phẩm ở chân trang

Lớp thương mại

File Dòng Vai trò
inc/woocommerce.php 286 Hook WooCommerce: lưới 5 cột, badge giỏ, breadcrumb, hộp SEO danh mục, upsell trang cảm ơn
inc/notices.php 101 Thông báo WooCommerce: mặc định TẮT success+notice, giữ error; có allowlist bật lại từng cái
inc/product-buybox.php 108 Hàng mua trên trang sản phẩm: [số lượng] [Thêm vào giỏ] [Mua ngay]; đổi hướng Mua ngay sang thanh toán
inc/checkout.php 240 Địa chỉ VN 2 cấp (tỉnh/phường), sắp lại thứ tự trường, ô nhập mã giảm giá, chặn mạo danh email tài khoản đã có, native select cho iOS
inc/shipping.php 435 Bảng giá cước vận chuyển SPX Express theo cân nặng nội bộ (AllinGo làm dự phòng)
inc/account.php 692 Đăng nhập/đăng ký, xác thực email, quy tắc mật khẩu, nút social login
inc/captcha.php 185 Cloudflare Turnstile trên form đăng nhập/đăng ký/quên mật khẩu và checkout login form

Lớp nội dung & SEO

File Dòng Vai trò
inc/seo.php 341 Meta danh mục, 301 từ bài viết cũ, noindex trang tiện ích, OG tag sản phẩm
inc/category-content.php 218 Nới bộ thẻ kses cho mô tả danh mục, chuyển mô tả xuống dưới lưới, quy tắc index

Lớp email

File Dòng Vai trò
inc/emails.php 394 Thương hiệu hoá email WooCommerce; tgk_email_html() là khung HTML dùng chung
inc/emails-system.php 314 Email hệ thống WordPress (tài khoản mới, đổi mật khẩu, đổi email) + 3 email tồn kho

Template

  • Template WordPress: index.php, front-page.php, single.php, page.php, archive.php, search.php, 404.php, header.php, footer.php, searchform.php, page-tin-tuc.php, page-test-ban-phim.php
  • Template part: template-parts/post-card.php, floating-contact.php
  • Override WooCommerce (19 file): thêm notices/success.php, notices/notice.php, notices/error.php — chỉ lọc rồi giữ nguyên markup gốc; quy tắc nằm ở inc/notices.php.
  • (cũ) Override WooCommerce (16 file): woocommerce/ — giỏ hàng (3), thanh toán (4), tài khoản (7), content-product.php. Danh sách đầy đủ và lý do override: docs/WP_THEME.md §3b.

Asset & Data

File Ghi chú
assets/css/main.css Một file CSS duy nhất cho toàn site
assets/js/main.js JS chung
data/vn-provinces.json 34 tỉnh (sau sáp nhập)
data/vn-wards.json 123 KB — phường/xã
data/category-meta.json Title/description SEO của danh mục
data/category-seo.json 94 KB — DEAD DATA. Nội dung danh mục đã chuyển sang ô Mô tả trong admin từ 06/09/2026. Giữ làm bản lưu, không code nào đọc.

Module: Plugin tgk-tracking

Meta Pixel (client) + Conversions API (server) chạy song song, chống trùng bằng event_id tất định. Chi tiết thiết kế: docs/TRACKING.md.

File Dòng Vai trò
tgk-tracking.php 55 Bootstrap, nạp class, khởi tạo
includes/class-config.php 91 Đọc hằng số TGK_* từ wp-config.php
includes/class-events.php 607 Trái tim plugin. Bắt sự kiện, dựng payload, quyết định Content ID, lọc bot
includes/class-user-data.php 347 Hash PII theo chuẩn Meta, sinh _fbp, đọc _fbc, lấy IP thật
includes/class-capi.php 125 Gọi Conversions API
includes/class-pixel.php 140 In mã pixel + hàng đợi sự kiện phía client
includes/class-event-id.php 107 Sinh event_id tất định để client và server trùng nhau
includes/class-queue.php 122 Hàng đợi gửi CAPI qua cron
includes/class-store.php 221 Lưu sự kiện vào DB để đối chiếu
includes/class-rest.php 107 REST endpoint nhận báo cáo "client đã bắn"
includes/class-admin.php 303 Metabox "Nguồn đơn hàng" (UTM + trạng thái _fbp/_fbc)
assets/js/tracking.js 80 Bắn pixel phía client, báo ngược về REST

Plugin bên thứ ba đang bật

Plugin Version Vai trò
woocommerce 10.5.3 Nền thương mại
seo-by-rank-math 1.0.277 SEO, sitemap, schema
fluent-smtp 2.3.1 Cầu nối Brevo
sepay-gateway 1.1.20 Cổng thanh toán QR
send-app 1.6.2 Đẩy đơn sang Pancake POS. Tắt trước khi test đơn.
nextend-facebook-connect 3.1.23 Social login (chỉ dùng Google; Facebook đã bỏ)
woo-variation-swatches 2.2.3 Chọn biến thể bằng ô màu

Nơi tuyệt đối không duplicate logic

Việc Dùng cái đã có
Lấy SĐT / địa chỉ / freeship tgk_site()
In icon tgk_icon() / tgk_the_icon()
Đọc file JSON trong data/ tgk_data()
Dựng HTML email tgk_email_html()
Lấy số đơn hiển thị tgk_email_order_no()
Xác định Content ID gửi Meta TGK_Events::content_id()
Hash PII cho Meta TGK_User_Data::hash()
Sinh event_id chống trùng TGK_Event_ID::*
Kiểm tra CAPTCHA tgk_captcha_verify()
Lấy mô tả danh mục đã lọc tgk_category_description_html()