Kiến trúc và danh mục module - Hướng dẫn sử dụng

iSPA CMS tổ chức chức năng theo module Laravel trong thư mục cms/. Ảnh chụp mã nguồn ngày 26/08/2026 có 40 module. Con số này lấy trực tiếp từ 40 tệp cms/*/module.json, không lấy từ menu admin hoặc danh sách module đang bật của một dự án cụ thể.

Phân biệt module có sẵn và module đang bật

cms/*/module.json cho biết module có trong mã nguồn. GET /api/v2/admin/utilities/modules mới cho biết module nào đang bật ở runtime hiện tại. Menu admin còn phụ thuộc quyền người dùng và cấu hình điều hướng.

Nguồn kiểm chứng

Nội dung	Nguồn chuẩn
Module backend có trong mã nguồn	`ispa-cms/cms/*/module.json`
Tên, alias, mô tả, dependency, provider	Từng tệp `module.json`
Trạng thái bật/tắt ở runtime	`GET /api/v2/admin/utilities/modules`
Module admin được nạp	`base-admin/src/config/admin-modules.js`
Route và menu admin theo module	`admin/route-config.js` và `admin/navigation-config.js`
Lệnh Artisan đã đăng ký	`ispa-cms/docs/module-artisan-command-inventory.md`

Mô hình sở hữu admin hiện tại

Admin vẫn được build thành một ứng dụng Vue duy nhất, nhưng source có hai nhóm sở hữu:

Shell và module lõi trong base-admin: Education, Game, CmsManagement, Inventory, DigitalLibrary và Site Layout.
Admin do backend module sở hữu: source đặt tại ispa-cms/cms/<Module>/admin, sau đó được base-admin tìm bằng import.meta.glob.

Một số màn hình cũ như bài viết, sản phẩm, đơn hàng, bất động sản và cài đặt vẫn được lắp vào shell bằng các route/page dùng chung. Vì vậy, “không có admin/module.js” không đồng nghĩa module không có giao diện quản trị.

Danh mục 40 module

Phạm vi tài liệu chi tiết

Game*, GuuXe*, Auto* và các module riêng cho ứng dụng mobile chỉ được ghi trong danh mục kỹ thuật này. Tài liệu hướng dẫn người dùng ưu tiên Bài viết, Giáo dục, Sản phẩm, Đơn hàng, Media, Người dùng, Nhóm tài khoản, Phân quyền và Cài đặt.

Nền tảng và nội dung dùng chung

Module	Alias	Phụ thuộc khai báo	Trách nhiệm chính
`Core`	`core`	—	Xác thực admin, phân quyền, cấu hình, upload, i18n, workflow và hạ tầng dùng chung.
`Account`	`account`	`core`	Năng lực tài khoản dùng lại cho các module và ứng dụng.
`Content`	`content`	`core`	Bài viết, trang, media và các khối nội dung cho front office.
`Product`	`product`	`core`	Catalog sản phẩm, SKU, thương hiệu, thuộc tính và API storefront.
`Ecommerce`	`ecommerce`	`core`, `product`	Giỏ hàng, checkout, đơn hàng và thanh toán.
`Inventory`	`inventory`	`core`	Tồn kho, lô hàng, giữ chỗ, điều chuyển, cảnh báo và điểm đặt lại.
`Widget`	`widget`	`core`	Site Layout: widget instance, placement, draft/release và render.
`CmsManagement`	`cmsmanagement`	—	Quản lý domain, khách hàng, thanh toán, nhắc việc và nhật ký vận hành CMS.
`SocialAuth`	`socialauth`	—	Tích hợp đăng nhập xã hội; manifest hiện chưa khai báo mô tả chi tiết.
`PushNotification`	`pushnotification`	—	Gửi và quản lý thông báo đẩy cho mobile/admin.
`Automation`	`automation`	`core`	Điều phối nhóm Telegram, ClickUp, coding agent, review, smoke test và cổng deploy.
`AutoDiscover`	`auto-discover`	—	Hàng đợi khám phá nguồn dùng chung cho các crawler module.
`CustomAds`	`customads`	—	Quản trị quảng cáo tùy chỉnh; manifest hiện chưa khai báo mô tả chi tiết.
`AffiliateRecommendation`	`affiliate-recommendation`	`core`	Danh mục affiliate, target, product và rule gợi ý theo cấu hình.
`Achievements`	`achievements`	—	Badge, title, award và thao tác cấp/thu hồi thành tích.
`GuidedResolution`	`guided-resolution`	`core`	Hướng dẫn thủ tục hành chính có nguồn, theo rule xác định.
`Journal`	`journal`	`core`	Xuất bản tạp chí first-party dùng lại giữa nhiều dự án.
`DigitalLibrary`	`digital-library`	`core`, `content`	Sách, chương, phân loại, tài sản riêng tư và rule truy cập.

Giáo dục, dữ liệu địa phương và nội dung chuyên ngành

Module	Alias	Phụ thuộc khai báo	Trách nhiệm chính
`Education`	`education`	`core`	Học viên, giảng viên, môn học, lớp, lượng giá, bài học và quiz.
`QuestionBank`	`questionbank`	—	Ngân hàng câu hỏi và các màn hình quản trị câu hỏi dùng chung.
`RealEstate`	`real-estate`	`core`	Dự án, sản phẩm, chủ đầu tư, tiện ích và luồng môi giới bất động sản.
`CatholicHandbook`	`catholic-handbook`	`account`	Địa điểm Công giáo, lịch, phụng vụ, báo cáo và nội dung tin cậy.
`CivicDirectory`	`civic-directory`	`account`, `geoplaces`	Danh bạ hành chính độc lập và API công khai đã xác minh.
`GeoPlaces`	`geoplaces`	`core`	Thu thập POI chậm, có provenance, phục vụ showroom và dịch vụ ô tô.

Xe, crawl và gợi ý nội dung

Module	Alias	Phụ thuộc khai báo	Trách nhiệm chính
`VehicleCatalog`	`vehiclecatalog`	`core`	Cây Make → Model → Generation → Trim → Engine, tách khỏi catalog Product.
`GuuXeCrawler`	`guuxescrapling`	`core`, `product`	Fetch, parse, staging và đẩy dữ liệu xe từ nguồn ngoài.
`GuuXeContentPipeline`	`guuxecontentpipeline`	`core`, `content`, `vehiclecatalog`	Pipeline biên tập nội dung xe và các extension cho trình soạn bài.
`GuuXeShowroomModeration`	`guuxeshowroommoderation`	`core`, `content`	Kiểm duyệt showroom và dữ liệu liên quan trước khi công khai.
`FengShui`	`fengshui`	`core`	Dữ liệu phong thủy, chấm biển số, diễn giải và lịch sử tra cứu.
`SaleHunting`	`salehunting`	—	Quản trị săn sale/deal; manifest hiện chưa khai báo mô tả chi tiết.

Game authority

Module	Alias	Trách nhiệm chính
`GameAdmin`	`gameadmin`	Shell quản trị authority, dashboard và migration.
`GameAuth`	`gameauth`	Đăng nhập, đăng ký và xác thực người chơi.
`GameCore`	`gamecore`	Contract và logic nền dùng chung cho game.
`GameEconomy`	`gameeconomy`	Tiền tệ, ví và đối soát kinh tế.
`GameInventory`	`gameinventory`	Kho vật phẩm của người chơi.
`GameLeaderboard`	`gameleaderboard`	Bảng xếp hạng và quy trình xét/promote.
`GameLiveOps`	`gameliveops`	Cấu hình runtime, season, mission, shop và catalog vận hành.
`GameMarketplace`	`gamemarketplace`	Chợ P2P, listing, giao dịch, phí và fraud queue.
`GamePlayer`	`gameplayer`	Hồ sơ, tìm kiếm và thống kê người chơi.
`GameRun`	`gamerun`	Phiên chơi, run authority và trace liên quan.

Các module game có route/menu admin riêng theo đúng tên backend, ví dụ GameRun, GamePlayer, GameLiveOps, GameLeaderboard và GameMarketplace. Không có module backend tên Game.

Cấu trúc tối thiểu của một module backend

cms/<Module>/
├── app/                  # Controller, model, service, provider, command
├── config/               # Cấu hình và binding của module
├── database/             # Migration, factory, seeder
├── routes/               # Route API/web nếu module cung cấp endpoint
├── tests/                # Kiểm chứng contract theo module
├── admin/                # Source admin module-owned, nếu có
├── composer.json
└── module.json           # Tên, alias, dependency, provider

Không phải module nào cũng cần đủ mọi thư mục. module.json và service provider mới là điểm bắt đầu để xác định module có tồn tại và được bootstrap như thế nào.

Contract cần giữ khi viết hoặc cập nhật tài liệu

Dùng tên module chuẩn, đúng chữ hoa/thường như CivicDirectory hoặc GameLiveOps.
Ghi route admin đầy đủ với prefix /api/v2/admin/... khi nói về HTTP API.
Phân biệt source admin trong base-admin với source module-owned trong ispa-cms/cms/<Module>/admin.
Không suy ra module đang bật chỉ từ việc source tồn tại.
Không suy ra quyền thao tác từ việc menu hiển thị; permission backend vẫn là nguồn quyết định.
Không coi module.json là nguồn duy nhất cho mọi chức năng: route, controller, service, command và UI thực tế mới chứng minh behavior.

Cách kiểm tra nhanh

# Đếm module có trong source
find cms -mindepth 2 -maxdepth 2 -name module.json | wc -l

# Xem module và trạng thái runtime qua API admin
php artisan route:list --path=api/v2/admin/utilities/modules

# Xem command do module đăng ký
php artisan list --raw

Kết quả đếm source của snapshot tài liệu này là 40.