Plugin WordPress: Hệ Thống Cửa Hàng

Version: 1.0.2
Requires at least: WordPress 6.0
Tested up to: WordPress 6.5
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

---

1. Mục tiêu

Xây dựng một plugin WordPress độc lập với theme, dùng để quản lý và hiển thị hệ thống cửa hàng (store locator) cho website.

Plugin cho phép:

• Quản trị Tỉnh/Thành phố → Xã/Phường → Cửa hàng trong Admin
• Lưu dữ liệu trong bảng riêng (không dùng post / taxonomy mặc định)
• Hiển thị frontend dạng bộ lọc + bản đồ (map miễn phí, không dùng Google Maps)
• Dễ mở rộng: API, đa ngôn ngữ, tối ưu SEO

---

2. Phạm vi chức năng

2.1 Backend (Admin)

2.1.1 Cấu trúc dữ liệu

Tạo các bảng riêng trong database:

wp_echbay_store_provinces
- id (int, PK, AUTO_INCREMENT)
- name (varchar 255)
- slug (varchar 255, UNIQUE)
- ordering (int, DEFAULT 0)
- status (tinyint, DEFAULT 1)
- created_at (datetime)
- updated_at (datetime)

wp_echbay_store_wards
- id (int, PK, AUTO_INCREMENT)
- province_id (int, FK)
- name (varchar 255)
- slug (varchar 255)
- ordering (int, DEFAULT 0)
- status (tinyint, DEFAULT 1)
- created_at (datetime)
- updated_at (datetime)

wp_echbay_store_locations
- id (int, PK, AUTO_INCREMENT)
- province_id (int, FK)
- ward_id (int, FK, NULL)
- store_name (varchar 255)
- address (text)
- phone (varchar 20)
- email (varchar 100)
- open_time (varchar 255)
- lat (decimal 10,7)
- lng (decimal 10,7)
- description (text)
- image_url (varchar 500, NULL)
- ordering (int, DEFAULT 0)
- status (tinyint, DEFAULT 1)
- created_at (datetime)
- updated_at (datetime)

Lý do dùng bảng riêng: dữ liệu lớn, truy vấn nhanh, không phụ thuộc WP Query

---

2.1.2 Trang quản trị (Admin Menu)

Menu chính: Hệ thống cửa hàng

• Tỉnh / Thành phố
• Xã / Phường
• Cửa hàng
• Cài đặt

a. Quản lý Tỉnh / Thành

• Thêm / sửa / xóa
• Sắp xếp thứ tự
• Bật / tắt hiển thị

b. Quản lý Xã / Phường

• Chọn Tỉnh / Thành tương ứng
• Thêm / sửa / xóa
• Sắp xếp thứ tự
• Bật / tắt hiển thị

c. Quản lý Cửa hàng

Các trường dữ liệu:

• Tên cửa hàng
• Tỉnh / Thành phố
• Xã / Phường
• Địa chỉ chi tiết
• Số điện thoại
• Email
• Thời gian hoạt động
• Tọa độ (lat, lng)
• Mô tả ngắn
• Trạng thái hiển thị

Hỗ trợ:

• Nhập tay tọa độ
• Hoặc click trên bản đồ để lấy lat/lng

---

2.2 Frontend

2.2.1 Giao diện tổng thể

Chia layout 2 cột:

• Cột trái (Filter):

  • Dropdown Tỉnh / Thành phố
  • Dropdown Xã / Phường (load động theo tỉnh)
  • Danh sách cửa hàng

• Cột phải (Map):

  • Bản đồ miễn phí
  • Marker hiển thị vị trí cửa hàng
  • Popup khi click marker

---

2.2.2 Bản đồ (Map miễn phí)

Khuyến nghị:

Leaflet.js + OpenStreetMap

• Hoàn toàn miễn phí
• Không cần API key
• Nhẹ, dễ custom

Stack:

Leaflet.js
OpenStreetMap Tile

Tính năng map:

• Load tất cả cửa hàng theo bộ lọc
• Marker clustering với Leaflet.markercluster (nhóm nhiều cửa hàng gần nhau)
• Click marker → popup:
  • Tên cửa hàng
  • Địa chỉ đầy đủ
  • Điện thoại
  • Email
  • Giờ mở cửa
  • Nút "Chỉ đường" (Google Maps/Apple Maps)

---

2.2.3 Tương tác Frontend

• Chọn Tỉnh/Thành phố → load Xã/Phường bằng AJAX
• Chọn Xã/Phường (hoặc để trống) → load danh sách cửa hàng + marker
• Click cửa hàng trong danh sách → focus và mở popup marker trên map
• Responsive: mobile thân thiện với bottom sheet cho danh sách

AJAX endpoint:

/wp-admin/admin-ajax.php
?action=store_filter

---

3. Kiến trúc Plugin

echbay-store-system/
│
├─ echbay-store-system.php        (file chính plugin)
├─ uninstall.php
├─ README.md
│
├─ includes/
│  ├─ class-db.php                (tạo bảng, query DB)
│  ├─ class-admin.php             (menu admin, pages)
│  ├─ class-frontend.php          (shortcode, enqueue assets)
│  ├─ class-ajax.php              (ajax handlers)
│  └─ helpers.php                 (utility functions)
│
├─ admin/
│  ├─ views/
│  │  ├─ provinces.php            (CRUD tỉnh/thành phố)
│  │  ├─ wards.php                (CRUD xã/phường)
│  │  ├─ stores.php               (CRUD cửa hàng)
│  │  └─ settings.php             (cài đặt chung)
│  └─ partials/
│     ├─ form-province.php
│     ├─ form-ward.php
│     └─ form-store.php
│
├─ assets/
│  ├─ css/
│  │  ├─ admin.css
│  │  └─ frontend.css
│  ├─ js/
│  │  ├─ admin.js
│  │  └─ frontend.js
│  └─ libs/                       (thư viện bên thứ 3)
│     ├─ leaflet/
│     └─ leaflet.markercluster/
│
└─ languages/                     (đa ngôn ngữ - tương lai)
   └─ echbay-store-system.pot

---

4. Hiển thị Frontend

4.1 Shortcode

[store_locator]

Tham số shortcode (optional):

• province_id - Hiển thị chỉ cửa hàng của tỉnh cụ thể
• limit - Giới hạn số lượng cửa hàng hiển thị (mặc định: không giới hạn)
• map_height - Chiều cao bản đồ (mặc định: 600px)

Ví dụ:

[store_locator province_id="1" limit="20" map_height="800px"]

Hoặc hỗ trợ Gutenberg Block (phase 2)

---

4.2 Hướng dẫn sử dụng

Bước 1: Cài đặt Plugin

1. Upload folder echbay-store-system vào /wp-content/plugins/
2. Kích hoạt plugin trong WordPress Admin
3. Plugin tự động tạo các bảng cần thiết trong database

Bước 2: Thêm dữ liệu

1. Vào Hệ thống cửa hàng → Tỉnh/Thành phố → Thêm các tỉnh/thành phố
2. Vào Xã/Phường → Thêm xã/phường/thị trấn cho mỗi tỉnh
3. Vào Cửa hàng → Thêm thông tin cửa hàng (có thể click vào map để lấy tọa độ)

Bước 3: Hiển thị Frontend

1. Tạo một trang mới (ví dụ: "Hệ thống cửa hàng")
2. Thêm shortcode [store_locator] vào nội dung trang
3. Xuất bản và xem kết quả

---

5. Hiệu năng & Tối ưu

• Database optimization:
  • Index cho province_id, ward_id
  • Index cho slug và status
  • Index composite cho query phức tạp
• Frontend optimization:
  • Lazy load marker (chỉ load khi viewport)
  • Chỉ enqueue Leaflet.js khi shortcode tồn tại
  • Minify CSS/JS trong production
  • Defer non-critical JavaScript
• AJAX optimization:
  • Debounce cho filter dropdown
  • Load on-demand cho hierarchical data

---

6. Bảo mật

• Input validation:
  • Nonce verification cho mọi form admin
  • Sanitize input với sanitize_text_field(), sanitize_email(), etc.
  • Validate lat/lng trong khoảng hợp lệ
  • SQL injection protection với prepared statements
• Output security:
  • Escape output với esc_html(), esc_attr(), esc_url()
  • JSON encode an toàn cho AJAX responses
• Access control:
  • Phân quyền manage_options cho admin pages
  • Check capabilities trước khi CRUD
  • AJAX action chỉ cho logged-in users (nếu cần)
• Data protection:
  • XSS prevention
  • CSRF protection
  • Rate limiting cho AJAX requests (nếu cần)

---

7. Mở rộng trong tương lai (Khuyến nghị)

7.1 API

• REST API endpoint để mobile app dùng chung

7.2 Import dữ liệu

• Import CSV / Excel danh sách cửa hàng

7.3 SEO

• Schema LocalBusiness
• Trang chi tiết cửa hàng riêng (slug)

7.4 UX

• Tìm kiếm theo tên cửa hàng
• Định vị người dùng (HTML5 Geolocation)

---

8. Công nghệ đề xuất

• PHP 8.x
• WordPress 6.x
• Leaflet.js
• OpenStreetMap
• jQuery hoặc Vanilla JS

---

9. Ghi chú

Plugin được thiết kế để:

• Không phụ thuộc theme
• Phù hợp website nhiều cửa hàng
• Dễ maintain lâu dài

---

10. Changelog

Version 1.0.2

• Loại bỏ cache system (không cần thiết vì query trực tiếp bảng riêng với index tối ưu)
• Xóa class-cache.php
• Xóa các cài đặt cache trong admin
• Đơn giản hóa code, giảm phức tạp

Version 1.0.1

• Sửa lỗi AJAX response double-wrapping
• Cập nhật helpers.php, frontend.js, admin.js
• Thêm DEBUG.md với hướng dẫn debug chi tiết

Version 1.0.0

• Khởi tạo plugin
• Tạo cấu trúc database với 3 bảng chính (provinces, wards, locations)
• Admin interface cho CRUD đầy đủ
• Frontend với Leaflet.js + OpenStreetMap
• AJAX filter theo tỉnh/xã-phường
• Marker clustering
• Cache với Transient API
• Responsive mobile-friendly

---

11. Đóng góp & Phát triển

Yêu cầu môi trường dev:

• PHP >= 8.0
• WordPress >= 6.0
• MySQL >= 5.7 hoặc MariaDB >= 10.3
• Node.js (nếu cần build assets)

Roadmap tương lai:

• [ ] Gutenberg Block thay thế shortcode
• [ ] REST API endpoints
• [ ] Import/Export CSV
• [ ] Multi-language support (WPML/Polylang)
• [ ] Schema.org LocalBusiness markup
• [ ] Trang chi tiết cửa hàng riêng
• [ ] Tìm kiếm theo tên/địa chỉ
• [ ] Geolocation - tìm cửa hàng gần nhất
• [ ] Widget sidebar
• [ ] Integration với WooCommerce

---

✌️ Next Steps:

• ✅ Viết schema SQL chi tiết
• ✅ Thiết kế cấu trúc plugin đầy đủ
• 🔄 Code khung plugin
• 🔄 Code mẫu Leaflet frontend
• 🔄 Thiết kế UI/UX admin interface