Tổng quan kiến trúc hệ thống PolyCMS cho RISE CRM
PolyCMS cho RISE CRM được xây dựng như một plugin thuần CodeIgniter 4 tuân thủ chặt chẽ kiến trúc Model-View-Controller (MVC) bên trong {rise_crm_root}/plugins/polycms/. Hệ thống kết hợp giao diện Bootstrap 5 và cơ chế hook nguyên bản của RISE CRM cùng lớp tương thích chống xung đột, 19 bảng cơ sở dữ liệu InnoDB độc lập, bộ định tuyến permalink động có cơ chế set404Override an toàn và hệ sinh thái mở rộng theo mô-đun cho sub-plugin, theme, widget và shortcode.
Cấu trúc thư mục Plugin
Toàn bộ mã nguồn PolyCMS nằm gọn trong plugins/polycms/ tuân theo quy ước đặt tên thư mục PascalCase của CodeIgniter 4 (Controllers/, Models/, Libraries/, Helpers/, Views/, Language/):
plugins/polycms/
├── index.php # Tệp khởi động chính, hook RISE, vòng đời plugin & đăng ký sidebar
├── install/
│ └── database.sql # Lược đồ InnoDB lũy đẳng cho đủ 19 bảng blog_*
├── config/
│ └── Routes.php # Định tuyến CI4: /polycms/*, /cms/api/v1/*, SEO, prefix & set404Override
├── Controllers/ # 22 Controller MVC trên CodeIgniter 4
│ ├── Base_admin_controller.php # Kế thừa \App\Controllers\Security_Controller + cầu nối giao diện BS5
│ ├── Base_public_controller.php # Kế thừa \App\Controllers\App_Controller cho trang ngoài & REST API
│ ├── Admin.php # Dashboard tổng quan và chỉ số CMS
│ ├── Api.php # Controller REST API v1 phi trạng thái
│ ├── Api_explorer.php # Sandbox tương tác API Explorer
│ ├── Banner_slider.php # Quản lý Banner Slider
│ ├── Categories.php # CRUD cây chuyên mục đa cấp
│ ├── Comments.php # Quản lý và kiểm duyệt bình luận
│ ├── Frontend.php # Hiển thị trang công khai, sitemap, robots.txt & xử lý 404 catch-all
│ ├── Media.php # Trình quản lý thư viện Media và tải tệp
│ ├── Menus.php # Trình dựng menu điều hướng kéo thả
│ ├── Mtbuilder.php # Trình dựng trang trực quan MTBuilder và Template Parts
│ ├── Pages.php # CRUD trang tĩnh CMS
│ ├── Permalink_settings.php # Cấu hình cấu trúc permalink và bộ đệm tiền tố URL
│ ├── Plugins.php # Quét sub-plugin, cài file ZIP, bật/tắt và cấu hình
│ ├── Posts.php # CRUD bài viết, hẹn giờ xuất bản và trường SEO
│ ├── Settings.php # Cấu hình 5 tab (Reading, General, Performance, Localization, REST API)
│ ├── Tags.php # CRUD thẻ tag và gộp thẻ
│ ├── Theme_options.php # Lưu trữ tùy biến Theme Options
│ ├── Themes.php # Chuyển đổi theme và cài đặt gói ZIP
│ ├── Tools.php # Nhập/Xuất JSON, Sao lưu/Khôi phục SQL & Demo Seeder
│ └── Widgets.php # Quản lý khu vực widget kéo thả
├── Models/ # 10 Model nghiệp vụ + Polycms_Base_Model.php
│ ├── Polycms_Base_Model.php # Lớp nền kết nối CI4 Query Builder
│ ├── Blog_post_model.php
│ ├── Blog_page_model.php
│ ├── Blog_category_model.php
│ ├── Blog_tag_model.php
│ ├── Blog_comment_model.php
│ ├── Blog_media_model.php
│ ├── Blog_menu_model.php
│ ├── Blog_plugin_model.php
│ ├── Blog_theme_model.php
│ └── Blog_widget_model.php
├── Libraries/ # 9 Thư viện dịch vụ lõi
│ ├── Blog_hooks.php # Bộ điều phối Action và Filter hooks
│ ├── Blog_plugin_loader.php # Trình đọc docblock header và nạp sub-plugin
│ ├── Blog_theme_loader.php # Trình đọc theme và phân giải phân cấp template
│ ├── Blog_shortcode.php # Bộ đăng ký và phân tích shortcode đệ quy
│ ├── Blog_widget.php # Lớp cơ sở widget và đăng ký vùng sidebar/footer
│ ├── Polycms_Asset_Manager.php # Quản lý nạp CSS/JS cho quản trị và trang ngoài
│ ├── Polycms_Integration.php # Tích hợp lõi RISE CRM và tùy chọn chuyển hướng trang chủ
│ ├── Polycms_Rate_Limiter.php # Bộ giới hạn tần suất truy cập theo IP lưu trên tệp
│ └── Polycms_Demo_Seeder.php # Bộ khởi tạo dữ liệu hướng dẫn và mẫu giao diện
├── Helpers/ # Lớp tương thích CI3-CI4 và các nhóm hàm hỗ trợ
│ ├── polycms_rise_compat_helper.php # Bộ hàm RISE/CI4 chống xung đột (polycms_ci, polycms_get_option...)
│ ├── CI3_Instance_Compat.php # Cầu nối singleton tương thích CI3 sang CI4
│ ├── CI3_DB_Wrapper.php # Bộ chuyển đổi cú pháp Active Record CI3 sang CI4 Query Builder
│ ├── CI3_Adapters.php # Bộ chuyển đổi Input, URI, Session và Loader
│ └── ... # Nhóm helper lõi, hook, template, bảo mật, media, theme & plugin
├── Views/ # Giao diện quản trị (có rise_layout_bridge.php) & dự phòng trang ngoài
├── Language/ # 16 gói ngôn ngữ tích hợp sẵn
├── plugins/ # 7 sub-plugin đi kèm (mtbuilder, mtoptimize, xml-sitemap, ...)
├── themes/ # Theme Bootstrap 5 mặc định Head Random
├── widgets/ # 9 lớp widget tích hợp sẵn
├── shortcodes/ # 3 bộ xử lý shortcode tích hợp sẵn
├── assets/ & dist/ # TinyMCE, Select2, SweetAlert2 tự lưu trữ và tài nguyên biên dịch
└── vendor/ezyang/htmlpurifier/ # Thư viện HTMLPurifier đóng gói riêng trong plugin
Đường dẫn lưu trữ dữ liệu vận hành
PolyCMS tách bạch tài nguyên media công khai với các tệp bộ nhớ đệm và sao lưu riêng tư trên hai thư mục gốc của RISE CRM:
| Đường dẫn | Phạm vi truy cập | Nội dung lưu trữ |
|---|---|---|
files/polycms/ |
Công khai (bảo vệ bằng .htaccess) |
Tệp media tải lên, ảnh thu nhỏ và tệp đệm định tuyến nhanh files/polycms/.blog_prefix_cache.php. |
writable/polycms/cache/ |
Nội bộ (riêng tư) | Bộ nhớ đệm trang HTML công khai khi bật tối ưu hiệu năng. |
writable/polycms/rate_limit/ |
Nội bộ (riêng tư) | Bộ đếm giới hạn tần suất theo IP cho biểu mẫu công khai và REST API v1. |
writable/polycms/backups/ |
Nội bộ (riêng tư) | Các bản sao lưu SQL (polycms_backup_YYYY-MM-DD_HH-ii.sql). |
writable/polycms/htmlpurifier/ |
Nội bộ (riêng tư) | Bộ nhớ đệm định nghĩa đã tuần tự hóa của HTMLPurifier giúp lọc HTML nhanh hơn. |
Tích hợp CodeIgniter 4 và Lớp tương thích
Để giữ mã nguồn gọn gàng, dễ mở rộng và không bao giờ xung đột tên hàm với các plugin RISE CRM khác (như data_builder), PolyCMS tổ chức ba lớp tích hợp cốt lõi:
- Base Controllers và cầu nối giao diện Bootstrap 5: Toàn bộ controller quản trị kế thừa
Base_admin_controller(kế thừa\App\Controllers\Security_Controller) và nhúng giao diện vào khung Bootstrap 5 của RISE CRM thông quaViews/admin/rise_layout_bridge.phpcùngassets/css/admin/rise-bs5-compat.css. Các trang công khai và REST API kế thừaBase_public_controller(kế thừa\App\Controllers\App_Controller). - Lớp tương thích CI3 sang CI4: Các tệp
polycms_rise_compat_helper.php,CI3_Instance_Compat.php,CI3_DB_Wrapper.php,CI3_Adapters.phpvàPolycms_Base_Model.phpcung cấp bộ hàmpolycms_*an toàn (polycms_ci(),polycms_admin_url(),polycms_site_url(),polycms_get_option(),polycms_update_option(),polycms_staff_can(),polycms_set_alert(),polycms_redirect(),polycms_html_purify()) vận hành trực tiếp trên các dịch vụ của CodeIgniter 4. - Hook vòng đời và Hook lõi RISE CRM: Tệp
index.phpđăng ký đầy đủregister_installation_hook,register_activation_hook,register_deactivation_hook,register_uninstallation_hook(giữ nguyên dữ liệu),register_update_hook, cùng các hook mở rộng phân quyền vai trò (app_hook_role_permissions_extension), menu thanh bên nhân sự và khách hàng (app_filter_staff_left_menu,app_filter_client_left_menu), nạp tài nguyên đúng phạm vi (app_hook_head_extension,app_hook_layout_main_view_extension) và loại trừ CSRF cho API (app_filter_app_csrf_exclude_urisvới mẫucms/api/v1.*+).
Lược đồ Cơ sở dữ liệu (19 bảng chuyên biệt)
Toàn bộ bảng PolyCMS được khởi tạo từ plugins/polycms/install/database.sql theo định dạng InnoDB, bảng mã utf8mb4_unicode_ci và tự động ghép tiền tố bảng hiện hành của RISE CRM qua $db->getPrefix() (mặc định là rise_, tạo thành rise_blog_*):
| Nhóm chức năng | Các bảng ({prefix}blog_*) |
Số lượng |
|---|---|---|
| Nội dung (Content) | blog_posts, blog_pages, blog_page_meta |
3 |
| Phân loại (Taxonomy) | blog_categories, blog_tags, blog_post_categories, blog_post_tags, blog_post_meta |
5 |
| Tương tác (Engagement) | blog_comments |
1 |
| Phương tiện (Media) | blog_media |
1 |
| Điều hướng (Navigation) | blog_menus, blog_menu_items, blog_widgets |
3 |
| Mở rộng (Extensions) | blog_plugins, blog_plugin_options, blog_themes, blog_theme_options |
4 |
| Cấu hình (Configuration) | blog_settings, blog_permalink_settings |
2 |
PolyCMS không bao giờ sửa đổi cấu trúc bảng lõi của RISE CRM. Hệ thống chỉ truy vấn chỉ đọc bảng users (qua App\Models\Users_model) để lấy tên và ảnh đại diện tác giả, đồng thời lưu cấu hình CMS trong {prefix}blog_settings với cơ chế đọc dự phòng từ bảng settings của RISE (app_title, date_format, time_format, timezone, language).
Cơ chế định tuyến và Vòng đời yêu cầu
Bộ định tuyến động (config/Routes.php)
Ngay khi khởi chạy, index.php gọi polycms_register_routes() để đăng ký:
- Tuyến quản trị: Đường dẫn chính
/polycms/*cùng bí danh tương thích/admin/polycms/*. - REST API v1:
/cms/api/v1/{posts,pages,categories,tags,media}hỗ trợGET,POST,PUT,PATCH,DELETE,OPTIONSvà không bị chặn bởi CSRF phiên trình duyệt. - Tuyến SEO tên miền gốc:
/sitemap.xml,/sitemap_index.xml,/post-sitemap.xml,/page-sitemap.xml,/category-sitemap.xml,/sitemap.xslvà/robots.txt. - Tuyến tiền tố blog động: Đọc trực tiếp từ
files/polycms/.blog_prefix_cache.phpkhông cần truy vấn cơ sở dữ liệu, kèm chuyển hướng301tự động từ tiền tố cũ. - Cơ chế
set404Overridean toàn của CI4: Ủy quyền các URL chưa khớp tớiFrontend::catch_all()để xử lý trang tĩnh ở cấp tên miền gốc hoặc chế độ bỏ tiền tố blog, sau đó khôi phục chuẩn mã HTTP404nếu không khớp nội dung CMS nào.
Luồng xử lý yêu cầu Quản trị
- CodeIgniter 4 định tuyến
/polycms/*tới controller kế thừaBase_admin_controller. Security_Controllerxác thực phiên đăng nhập RISE CRM và controller kiểm tra quyền vai trò quapolycms_staff_can().- Controller thao tác dữ liệu qua các
Blog_*_modeldựa trên CI4 Query Builder. rise_layout_bridge.phphiển thị giao diện quản trị PolyCMS đồng bộ trong khung Bootstrap 5 của RISE CRM kèm các thư viện tự lưu trữ TinyMCE, Select2 và SweetAlert2.
Luồng xử lý yêu cầu Trang công khai
config/Routes.phphoặcset404Overridechuyển yêu cầu tớiFrontend.php(kế thừaBase_public_controller).- Hook
polycms_frontend_initkích hoạt, cho phép các sub-plugin như Maintenance Mode hoặc XML Sitemap can thiệp sớm. Frontend.phpkiểm tra bộ nhớ đệm HTML (writable/polycms/cache/) nếu đang bật cache hiệu năng, hoặc truy vấn bài viết, trang tĩnh, chuyên mục, thẻ tag, tác giả, lưu trữ hay kết quả tìm kiếm.Blog_theme_loadernạp theme đang bật từ{prefix}blog_themesvà duyệt theo phân cấp template (single.php->category.php->tag.php->page.php->index.php).polycms_head, trình phân tích shortcode (Blog_shortcode), widget (Blog_widget), bộ lọc nội dung vàpolycms_footerchạy tuần tự để trả về HTML hoàn chỉnh.
Kiến trúc hệ thống mở rộng theo mô-đun
Hệ thống Sub-Plugin
Blog_plugin_loader quét thư mục plugins/polycms/plugins/ để đọc các tệp PHP chứa tiêu đề docblock tiêu chuẩn (Plugin Name:, Description:, Version:, Author:). Những sub-plugin đang ở trạng thái kích hoạt trong {prefix}blog_plugins sẽ được nạp qua polycms_bootstrap_subplugins(), đăng ký hook bằng polycms_add_action() / polycms_add_filter(), và có thể khai báo mục menu thanh bên thông qua tệp menu.json tùy chọn.
Hệ thống Theme, Widget và Shortcode
- Theme: Nằm tại
plugins/polycms/themes/với theme mặc định Head Random (Bootstrap 5), hỗ trợ sẵn 2 vùng widget (sidebar,footer) và Theme Options. - Widget: 9 lớp widget dựng sẵn trong
plugins/polycms/widgets/đăng ký bằngpolycms_register_widget(). - Shortcode: 3 bộ xử lý tích hợp (
[polycms_post],[polycms_category],[polycms_tag]) trongplugins/polycms/shortcodes/, đăng ký quapolycms_register_shortcode()và phân giải bằngpolycms_do_shortcode().
Kiến trúc Bảo mật
- Kiểm soát quyền theo vai trò (RBAC): Mọi hành động quản trị đều kiểm tra 5 quyền vai trò RISE CRM (
polycms_view,polycms_create,polycms_edit,polycms_delete,polycms_settings). - Chống XSS: Nội dung HTML giàu định dạng được làm sạch qua thư viện tự lưu trữ
vendor/ezyang/htmlpurifierthông qua hàmpolycms_html_purify(). - Chống SQL Injection: Toàn bộ truy vấn dữ liệu sử dụng tham số hóa chuẩn của CodeIgniter 4 Query Builder.
- Bảo vệ hệ thống tệp:
polycms_validate_file_path()chặn tấn công dò đường dẫn (directory traversal) vàpolycms_secure_upload_directory()duy trì tệp.htaccessngăn thực thi mã kịch bản trongfiles/polycms/. - Giới hạn tần suất truy cập:
Polycms_Rate_Limiterkiểm soát lưu lượng theo địa chỉ IP cho bình luận công khai và REST API quawritable/polycms/rate_limit/. - Chặn truy cập trực tiếp: Các tệp PHP kiểm tra ngữ cảnh thực thi hợp lệ trước khi chạy.
Tài liệu liên quan
- Tài liệu tham khảo đầy đủ Hooks và Filters - Danh mục đầy đủ các action và filter hook trong PolyCMS.
- Template Tags và Hàm hỗ trợ - Tài liệu hàm helper dành cho phát triển theme và plugin.
- Xây dựng Plugin tùy biến cho PolyCMS - Hướng dẫn từng bước phát triển sub-plugin trên RISE CRM.
- Xây dựng Theme tùy biến cho PolyCMS - Hướng dẫn cấu trúc thư mục, header và phân cấp template theme.