Przejdź do głównej zawartości

Akcje palety poleceń w panelu administracyjnym

Punkt wpięcia oparty na rejestrze, który pozwala każdemu modułowi backendu dodawać przyciski akcji do palety poleceń w panelu administracyjnym (okno ⌘K / Ctrl+K — to, co operator widzi jako grupę Actions). Żadna akcja nie jest wpisana na stałe: każda, łącznie z New product i Import products, jest deklarowana raz, w manifeście modułu, do którego należy, i udostępniana przez ten rejestr.

Częścią po stronie platformy jest ten moduł, admin_actions; część działająca w panelu administracyjnym znajduje się w pakiecie @endora-commerce/admin-shell, w src/lib/admin-actions/.

Co deklaruje moduł​

manifest.ts modułu może deklarować zero lub więcej akcji, obok istniejących pól settings i i18n:

import { defineModuleManifest } from '@endora-commerce/contracts';

export const manifest = defineModuleManifest({
id: 'catalog',
name: 'Catalog',
version: '1.4.0',
dependencies: [],
i18n: { bundlesDir: 'i18n' },
actions: [
{
id: 'new-product',
labelKey: 'catalog.actions.newProduct.label',
descriptionKey: 'catalog.actions.newProduct.description',
icon: 'Plus',
targetRoute: '/catalog/products/new',
requiredPermission: 'catalog:write',
keywords: ['product', 'new', 'add', 'create'],
keywordsKey: 'actions.newProduct.keywords',
weight: 100,
},
],
});

Każdy wpis MUSI mieć stabilne id, tłumaczalny labelKey, icon z zamkniętej listy dozwolonych ikon oraz targetRoute. Pola opcjonalne to descriptionKey, requiredPermission, entryApiRoute, keywords (do 10), keywordsKey i weight (domyślnie 100).

keywords są po angielsku i pasują w każdym języku panelu. Słowa wyszukiwania w innym języku nie trafiają do manifestu: keywordsKey wskazuje wpis we własnych pakietach tłumaczeń modułu — względny wobec przestrzeni nazw modułu, tak jak labelKey — którego wartością jest lista rozdzielona przecinkami, na przykład "actions.newProduct.keywords": "produkt, nowy, dodaj" w i18n/pl.json i "product, new, add" w i18n/en.json. Serwer rozwiązuje go w języku operatora (z powrotem do angielskiego) i zwraca te słowa po keywords z manifestu, więc polski operator znajdzie akcję po polskim słowie, a nadal także po angielskim.

requiredPermission jest w schemacie opcjonalne, ale w praktyce obowiązkowe: musi to być kod, który backend egzekwuje na trasie stojącej za targetRoute, żeby paleta nigdy nie proponowała akcji kończącej się błędem 403 i nigdy nie ukrywała ekranu przed operatorem, który ma prawo go otworzyć. Oba te błędy się zdarzyły — settings/open-settings trafił do wydania bez żadnego kodu, choć prowadził do trasy chronionej przez settings:read, a inventory/open-inventory deklarował catalog:write dla trasy chronionej przez orders:read — i przegląd uprawnień nie wykrył żadnego z nich, bo sprawdza, czy kod jest egzekwowany gdziekolwiek, a nie czy jest egzekwowany tutaj. pnpm --filter backend run check:action-route-permissions porównuje jedno z drugim, wiążąc targetRoute aplikacji SPA z trasą API administracyjnego, która ją chroni. Zostaw to pole puste tylko wtedy, gdy cel naprawdę nie jest niczym chroniony; jeśli ekran jest chroniony uprawnieniem do odczytu, a etykieta akcji obiecuje zapis, pole nie może wyrazić obu tych rzeczy naraz, więc rozbieżność jest zapisywana w rejestrze wyjątków tej kontroli, a nie zgadywana.

Kontrola ustala tę trasę na podstawie adresu: najpierw szuka ścieżki API równej celowi, potem najpłytszej ścieżki pod nim, a na końcu najbliższej trasy zarejestrowanej przez moduł. Ten domysł zawodzi, gdy ekran korzysta z API, którego jego ścieżka w panelu nie nazywa. Kolejka wychodząca poleceń jest zakładką /platform/command-hooks, ale jej dane pochodzą z GET /api/v1/admin/command-outbox. Dla takiego ekranu entryApiRoute wskazuje trasę API administracyjnego, którą ekran otwiera, a kontrola porównuje requiredPermission tylko z tą trasą:

{
id: 'open-command-outbox',
targetRoute: '/platform/command-hooks/outbox',
requiredPermission: 'platform.command_outbox.read',
entryApiRoute: '/api/v1/admin/command-outbox',
// …
}

Wartość to ścieżka pod /api/v1/admin/, zapisana dokładnie tak, jak rejestruje ją trasa. Metoda wynika z celu: GET albo metody zapisu dla formularza /new. Jeśli żadna rejestracja nie odpowiada zadeklarowanej ścieżce, kontrola zgłasza to, zamiast wracać do domysłu. W czasie działania nic tego pola nie odczytuje. Deklaruj je tylko tam, gdzie domysł wybiera złą trasę.

Unikalność id w obrębie modułu wymusza schemat Zod manifestu — instalacja manifestu z dwiema akcjami o tym samym identyfikatorze kończy się błędem z czytelnym komunikatem wskazującym indeks.

Publiczne API​

Metoda + ścieżkaCel
GET /api/v1/admin/admin-actions?language=<en|pl>Zwraca listę akcji widocznych dla operatora, już przefiltrowaną według jego uprawnień i stanu instalacji modułów, posortowaną według (weight, etykieta w kolejności właściwej dla języka), z etykietami i opisami w żądanym języku (z przejściem na angielski, a potem na surowy klucz — dokładnie tak jak w łańcuchu zastępczym i18n panelu administracyjnego). Uprawnienie: dowolny uwierzytelniony administrator.

Odpowiedź zawiera pole meta.registryVersion — MAX(version) z widocznych wierszy — przydatne diagnostycznie. Aplikacja panelu administracyjnego nie odpytuje go cyklicznie; odświeżenie następuje po zmianie języka operatora i przy zamontowaniu komponentu.

Jak operator widzi akcje​

  1. Operator otwiera panel administracyjny i naciska ⌘K (lub Ctrl+K w systemach Windows i Linux).
  2. Paleta pokazuje dwie grupy: Navigate (stałe skoki) i Actions.
  3. Grupa Actions pokazuje każdą akcję, której moduł jest zainstalowany ORAZ której requiredPermission (jeśli jest ustawione) przyznaje rola operatora. Uprawnienie wieloznaczne *, które ma platform_admin, spełnia wymagania każdej akcji.
  4. Wpisywanie tekstu w polu wyszukiwania filtruje obie grupy, dopasowując fragment tekstu do etykiety, opisu i słów kluczowych wiersza, bez rozróżniania wielkości liter i znaków diakrytycznych. Operator może wpisać latwy, żeby znaleźć łatwy, albo import, żeby znaleźć Importuj produkty itd.
  5. Kliknięcie wiersza lub naciśnięcie Enter przenosi do targetRoute akcji i zamyka paletę.

Gdy operator nie widzi żadnej akcji (rzadko — tylko przy roli bez uprawnień i braku modułów dodających akcje niewymagające uprawnień), grupa Actions jest całkowicie ukryta.

Integracja z cyklem życia​

Ścieżka instalacji w orkiestratorze uzgadnia module_actions po zainstalowaniu pakietu tłumaczeń i18n, a przed hookiem instalacyjnym samego modułu. Mechanizm uzgadniający wstawia lub aktualizuje (UPSERT) każdą zadeklarowaną akcję i usuwa wiersze, których nowy manifest już nie deklaruje — kolejność instalacji, aktualizacje wersji i usuwanie akcji są idempotentne. Przy twardej deinstalacji (module:uninstall --hard) mechanizm uzgadniający usuwa każdy wiersz akcji należący do modułu przed krokiem usunięcia pakietu tłumaczeń i18n.

Stan jest przechowywany w module_actions (złożony klucz główny (module_id, action_id)); miękka deinstalacja (stan → disabled) NIE usuwa wierszy — opiera się na filtrze widoczności przy odczycie, który pomija każdy wiersz, którego moduł nie jest faktycznie obecny, co ukrywa akcje, ale zachowuje je na wypadek ponownego włączenia.

Ten filtr pyta mechanizm łączący obie osie stanu w jądrze — przez sondę dostarczaną przez kompozycję — i pyta o obie osie obecności: stan w module_registrations wdrożenia oraz ustawienie aktywacji operatora. Kiedyś w ten sposób pytał tylko o drugą, a dla pierwszej łączył tabele po module_registrations.state = 'installed', co oznaczało, że paleta i zabezpieczenia tras odczytywały odpowiedź na to samo pytanie z dwóch źródeł — rozbieżnych przez cały czas trwania każdego registryCache.refreshFromDb — więc paleta mogła proponować akcję, której trasa odpowiadała 503, i ukrywać taką, którą trasa nadal by obsłużyła. Tabela rejestru nadal jest zapisem osi platformy; paleta po prostu nie czyta jej już z pominięciem platformy.

Struktura danych​

KolumnaTypUwagi
module_idvarchar(64)Część klucza głównego.
action_idvarchar(64)Część klucza głównego.
label_keyvarchar(255)Klucz i18n tłumaczony przy odczycie.
description_keyvarchar(255) NULLOpcjonalny.
iconvarchar(64)Jedna z nazw z zamkniętej listy dozwolonych ikon.
target_routevarchar(255)Trasa w panelu administracyjnym.
required_permissionvarchar(64) NULLKod uprawnienia, w dowolnej notacji.
keywordsjsonbTablica ciągów znaków.
keywords_keyvarchar(255) NULLKlucz i18n słów wyszukiwania w danym języku, rozwiązywany przy odczycie.
weightintegerKlucz sortowania (domyślnie 100).
versionbigintLicznik dla wiersza; zwiększany przy każdym UPSERT.
installed_at, updated_attimestamptzMetadane wiersza.

Na module_id nie ma klucza obcego — moduły wynikają z systemu plików, a module_registrations jest rejestrem zapisu. Porządek utrzymuje ścieżka twardej deinstalacji w mechanizmie uzgadniającym, tak samo jak w przypadku translation_bundles.

Zalecane przedziały wag​

Wagi są tylko zaleceniem, ale recenzenci oczekują, że nowe akcje trafią do właściwego przedziału:

PrzedziałZastosowanie
0–99Zarezerwowane dla powłoki platformy.
100–199Podstawowe tworzenie (np. New product, New page, New post).
200–299Drugorzędne tworzenie i wejścia do konfiguracji.
300–399Akcje procesów i skrzynek odbiorczych.
400–499Rzadziej używana nawigacja i narzędzia.
≥ 500Rzadko używane akcje; trafiają na dół listy.

Lista dozwolonych ikon​

Dozwolone nazwy ikon to typ wyliczeniowy w packages/contracts/src/admin-actions.ts. Dodanie nowej ikony to jednowierszowa zmiana w tym typie i w icon-map.ts systemu projektowego panelu (@endora-commerce/admin-kit, src/lib/admin-actions/icon-map.ts).

Jakie akcje istnieją​

Zestaw akcji to suma tablic actions z manifestów modułów zainstalowanych w Twojej instancji, więc różni się między instancjami i ta strona go nie wymienia. Pierwsze wydanie zawierało dziesięć akcji w dziewięciu modułach; dziś akcje deklaruje znacznie więcej modułów. Aby zobaczyć zestaw, który instancja faktycznie udostępnia, wywołaj GET /api/v1/admin/admin-actions jako operator z uprawnieniem * albo przeszukaj manifesty modułów pod kątem actions:.