Wprowadzenie

Panel administracyjny jest aplikacją jednostronicową napisaną w Quasarze 2 i Vue 3, komunikującą się z backendem w Laravelu przez REST API zabezpieczone Sanctumem.

W monolicie panel mooncms-frontend jest pobierany przez php artisan mb:install-cms i budowany do public/cms. Trasę serwującą build opisuje architektura monolitu.

Kod dzieli się na moduły. Każdy moduł to samodzielny katalog w src/modules/, zawierający własne trasy, strony, komponenty, warstwę API oraz tłumaczenia. Praca nad pojedynczą funkcjonalnością ogranicza się zwykle do jednego takiego katalogu.

Dokumentacja opisuje trzy projekty naraz

Panel występuje w trzech wariantach — mooncore-frontend, mooncrm-frontend i mooncms-frontend — opartych na tej samej architekturze: module core, generatorze Plop, composables useCoreTable i useFormSubmit oraz konwencji <moduł>.<modele>.<akcja>. Różni je zestaw modułów domenowych. Poniższy opis dotyczy części wspólnej, a przykłady pochodzą z CMS-a. Adresy repozytoriów podają Pierwsze kroki.

Wykorzystane technologie

Warstwa	Technologia
Framework	Quasar v2 (@quasar/app-vite 2.x)
UI	Vue 3 — wyłącznie <script setup>, JavaScript (nie TypeScript)
Routing	Vue Router 4 — tryb history
Dane z serwera	TanStack Vue Query v5
Stan aplikacji	Pinia
Formularze	vee-validate 4 + yup
Tłumaczenia	vue-i18n v11
HTTP	axios (singleton Http)
Generator kodu	Plop — npm run make

Przepływ danych

Wszystkie ekrany CRUD w panelu zbudowane są według tego samego schematu. Ten łańcuch powtarza się w każdym module — poznanie go raz wystarcza do czytania dowolnego z nich:

src/router/routes.js
        │  (składa trasy wszystkich modułów)
        ▼
modules/<moduł>/routes/<modele>.js        ── meta.secured, meta.access
        │
        ▼
modules/<moduł>/pages/<modele>/*Page.vue  ── cienka strona: tytuł + breadcrumbs
        │
        ├──► <Moduł><Modele>Table.vue  ──► useCoreTable()
        │                                       │
        └──► <Moduł><Model>Form.vue    ──► useForm() + useFormSubmit()
                                                │
                                                ▼
                        modules/<moduł>/api/queries|mutations/*.js
                                                │  (TanStack Vue Query)
                                                ▼
                        modules/<moduł>/api/endpoints/<model>.js
                                                │
                                                ▼
                        modules/core/services/http.js  ── axios + interceptory
                                                │
                                                ▼
                                          Laravel API

Łańcuch spinają dwa mechanizmy. Bez nich kod modułu wygląda na niekompletny.

Auto-import. Composables (useCoreTable, useLocale, formatDate) i wszystkie komponenty (<base-table>, <v-input>) są dostępne bez instrukcji import. Brak importu w pliku nie oznacza więc, że symbol pochodzi skądinąd. Opisuje to Architektura.

Konwencja nazw <moduł>.<modele>.<akcja>. Nazwa trasy jest jednocześnie kluczem uprawnienia, źródłem breadcrumbs i podstawą do wyliczenia tras edycji oraz powrotu. Korzysta z niej pięć mechanizmów, więc jej zmiana psuje kilka rzeczy naraz. Opisuje to Routing.

Gdzie czego szukać

Zadanie	Strona
Uruchomienie projektu lokalnie	Pierwsze kroki
Układ katalogów i aliasy	Struktura katalogów
Pochodzenie auto-importów i globalnych komponentów	Architektura
Dodanie nowego modelu CRUD	Krok po kroku
Utworzenie nowego modułu	Moduły i generatory
Trasy, breadcrumbs, uprawnienia do tras	Routing
Ukrywanie elementów przed użytkownikiem bez uprawnień	Autentykacja
Wywołania API i obsługa błędów	Warstwa API
Query, mutacje, unieważnianie cache	Vue Query
Stan współdzielony między komponentami	Store'y Pinia
Strony z tytułem, breadcrumbs i przyciskiem w nagłówku	Layouty i strony
Kolumny, filtry, akcje wierszy i akcje masowe	Tabele
Pola formularza, walidacja, błędy 422	Formularze
Podpinanie zdjęć i plików do modeli	Media
Nowe typy bloków w builderze treści	Content builder
Stałe pola treści definiowane w kodzie	Custom fields
Tłumaczenia i obsługa języka treści	Tłumaczenia

Zasady obowiązujące w projekcie

Importy composables i komponentów są zbędne

Composables z modules/core/composables i modules/core/utils, a także wszystkie komponenty z katalogów components/, rejestrowane są globalnie. Pełna lista dostępnych nazw znajduje się w wygenerowanym pliku auto-imports.d.ts.

Błędów API nie obsługuje się w komponencie

Toasty dla błędów 401, 403 i 422 oraz komunikaty sukcesu wystawia interceptor axiosa. Jedynym wyjątkiem są błędy walidacji formularza, które przypisuje do pól useFormSubmit. Opisuje to Warstwa API.

Komentarzy // --place where generator will inject ... nie wolno usuwać

Stanowią one punkty zaczepienia generatora Plop. Usunięcie któregokolwiek sprawia, że npm run make przestaje wstrzykiwać kod w danym miejscu, nie zgłaszając przy tym żadnego błędu. Szczegóły w Modułach i generatorach.