duck-prod-manager/notes/directus-api.md

Directus Mayo API Extension

Data aktualizacji: 2026-05-20

Cel

Ten dokument opisuje aktualny stan budowy custom API w Directus dla frontendu Duck Prod Manager.

Extension znajduje sie w:

directus/extensions/directus-extension-mayo-api

Endpoint Directus extension ma miec identyfikator:

mayo-api

Dlatego publiczne sciezki beda dostepne pod prefiksem:

/mayo-api

Aktualny stan

Katalog extension jest przygotowany i zawiera scaffold Directus endpoint extension.

Istniejace pliki:

directus/extensions/directus-extension-mayo-api/README.md
directus/extensions/directus-extension-mayo-api/package.json
directus/extensions/directus-extension-mayo-api/src/index.js
directus/extensions/directus-extension-mayo-api/old/index.js.old
directus/extensions/directus-extension-mayo-api/old/old_index.js.old

src/index.js rejestruje obecnie pierwsze dwa endpointy:

• GET /mayo-api/products
• GET /mayo-api/dictionaries

Stare pliki w old/ sa tylko materialem referencyjnym. Nie traktujemy ich jako aktywnej implementacji.

Zalozona architektura

Nie umieszczamy wszystkich endpointow w jednym pliku.

src/index.js ma pelnic role glownego routera:

• eksportuje Directus endpoint extension,
• ustawia id: 'mayo-api',
• importuje pliki endpointow,
• rejestruje endpointy,
• nie zawiera zapytan SQL ani logiki biznesowej.

Kazdy endpoint ma miec osobny plik w katalogu routes/.

Logika wspolna powinna byc rozbita na:

• repositories/ - zapytania do bazy Directus,
• serializers/ - mapowanie danych z DB na format frontendu,
• utils/ - drobne helpery techniczne.

Proponowana struktura plikow

directus/extensions/directus-extension-mayo-api/src/
  index.js

  routes/
    products.get.js
    dictionaries.get.js
    product-timeline.get.js               # do zrobienia
    product-timeline-event.post.js        # do zrobienia
    product-specification.get.js          # do zrobienia
    product-specification-refresh.post.js # do zrobienia

  repositories/
    products.repository.js
    dictionaries.repository.js
    timeline.repository.js      # do zrobienia
    specification.repository.js # do zrobienia

  serializers/
    product.serializer.js
    timeline.serializer.js
    specification.serializer.js # do zrobienia
    dictionaries.serializer.js

  utils/
    async-handler.js
    http-error.js # do zrobienia, jesli bedzie potrzebny
    pagination.js
    order-search.js

Endpointy wymagane przez frontend

1. Lista produktow

GET /mayo-api/products

Status: zaimplementowany w pierwszym etapie.

Parametry query:

{
  limit,
  offset,
  search,
  orderSearch,
  model,
  client,
  finish,
  productionList,
  year,
}

orderSearch przychodzi z frontendu jako JSON string.

Oczekiwana odpowiedz:

{
  items: [],
  pageInfo: {
    limit,
    offset,
    hasMore,
    total,
  },
}

Element items powinien miec ksztalt produktu uzywany przez frontend:

{
  id,
  orderId,
  orderNumber,
  orderYear,
  orderIndex,
  model,
  client,
  finish,
  productionLists,
  timelinePreview: {
    body: [],
    neck: [],
  },
}

2. Slowniki

GET /mayo-api/dictionaries

Status: zaimplementowany w pierwszym etapie.

Oczekiwana odpowiedz:

{
  models: [],
  clients: [],
  finishes: [],
  productionLists: [],
  operations: [],
  colors: [],
}

3. Timeline produktu

GET /mayo-api/products/:id/timeline

Status: do zrobienia.

Oczekiwana odpowiedz:

{
  productId,
  events: [],
  timelinePreview: {
    body: [],
    neck: [],
  },
}

4. Dodanie eventu timeline

POST /mayo-api/products/:id/timeline/events

Status: do zrobienia.

Oczekiwana odpowiedz:

{
  event: {},
  timelinePreview: {
    body: [],
    neck: [],
  },
}

5. Specyfikacja produktu

GET /mayo-api/products/:id/specification

Status: do zrobienia.

Preferowana odpowiedz:

{
  productId,
  orderId,
  sourceUrl,
  lastFetchedAt,
  sections: [],
  diff: [],
}

Frontend akceptuje tez ksztalt:

{
  productId,
  orderId,
  sourceUrl,
  lastFetchedAt,
  specification: {
    sections: [],
  },
  diff: [],
}

6. Odswiezenie specyfikacji produktu

POST /mayo-api/products/:id/specification/refresh

Status: do zrobienia.

Odpowiedz powinna miec taki sam ksztalt jak GET /specification, ale z aktualnym lastFetchedAt i ewentualnym diff.

Kolejnosc implementacji

Rekomendowana kolejnosc:

1. GET /mayo-api/products
2. GET /mayo-api/dictionaries
3. GET /mayo-api/products/:id/timeline
4. POST /mayo-api/products/:id/timeline/events
5. GET /mayo-api/products/:id/specification
6. POST /mayo-api/products/:id/specification/refresh

Pierwsze dwa endpointy odblokowuja glowny ekran frontendu.

Co zostalo zrobione

• Przeanalizowano notes/api_services.md.
• Przeanalizowano frontendowe implementacje HTTP w frontend/src/services/*HttpApi.js.
• Przeanalizowano store Pinia, zeby ustalic realne parametry i ksztalt danych.
• Ustalono liste 6 endpointow wymaganych przez obecny frontend.
• Ustalono, ze index.js bedzie tylko routerem/rejestratorem endpointow.
• Ustalono docelowa hierarchie plikow extension.
• Utworzono ten dokument jako aktualny opis stanu prac nad Directus extension.
• Utworzono katalogi routes/, repositories/, serializers/, utils/.
• Wypelniono src/index.js rejestracja pierwszych endpointow.
• Zaimplementowano GET /mayo-api/products.
• Zaimplementowano GET /mayo-api/dictionaries.
• Zweryfikowano nazwy kolekcji na podstawie snapshot(6).json i db_schema.dbml.
• Uruchomiono npm run build w katalogu extension. Build zakonczyl sie poprawnie.
• Dodano README.md dla extension.
• Dodano license: "UNLICENSED" w package.json, zeby extension bylo oznaczone jako pakiet wewnetrzny.
• Uruchomiono npm run validate w katalogu extension. Walidacja zakonczyla sie poprawnie.
• Dodano mayo-api.http z requestami REST Client do manualnego testowania endpointow.
• Przebudowano db_schema.dbml pod nowa baze Directus: poprawione nazwy, tabele slownikowe zamiast enumow.
• Dostosowano aktywne repository extension do nowego schematu.
• Uwzgledniono relacje mayo_product_production_lists.order_item_id -> mayo_order_items.id.

Decyzje implementacyjne

• Aktywna implementacja ignoruje katalog directus/extensions/directus-extension-mayo-api/old.
• Pierwsza implementacja byla oparta o stary schemat Directus, ktory zawieral literowki:
  • mayo_order_porducts
  • mayo_lisst_products
  • mayo_color
• db_schema.dbml zostal przebudowany jako propozycja nowego schematu:
  • enumy zostaly zamienione na tabele slownikowe,
  • literowki zostaly poprawione,
  • nazwy kolekcji zostaly doprecyzowane pod Directus.
• Nowa baza Directus zostala utworzona zgodnie z db_schema.dbml, z jedna celowa zmiana:
  • mayo_product_production_lists.order_item_id wskazuje na mayo_order_items.id.
• Extension zostal dostosowany do nowych nazw kolekcji i relacji order_item_id.
• GET /products buduje timelinePreview z mayo_production_events, mayo_product_parts, mayo_part_types i mayo_production_operations.
• GET /products filtruje po model, client, year, productionList, finish i orderSearch.
• GET /dictionaries pobiera finish z tabeli slownikowej mayo_finishes.
• Kod operacji pochodzi z mayo_production_operations.code.
• Uruchomiono npm run build po dostosowaniu do nowego schematu. Build zakonczyl sie poprawnie.
• Uruchomiono npm run validate po dostosowaniu do nowego schematu. Walidacja zakonczyla sie poprawnie.

Proponowane nowe nazwy kolekcji

Stare nazwy i ich proponowane odpowiedniki:

mayo_color            -> mayo_colors
mayo_lisst_products   -> mayo_product_production_lists
mayo_lists            -> mayo_production_lists
mayo_models           -> mayo_product_models
mayo_operations       -> mayo_production_operations
mayo_order_porducts   -> mayo_order_items
mayo_part_events      -> mayo_production_events
mayo_parts            -> mayo_product_parts

Enumy zostaly zastapione tabelami:

mayo_models_neck_construction -> mayo_neck_constructions
mayo_parts_part_type          -> mayo_part_types
mayo_parts_finish             -> mayo_finishes

Do zrobienia

• Zaimplementowac GET /mayo-api/products/:id/timeline.
• Zaimplementowac POST /mayo-api/products/:id/timeline/events.
• Zaimplementowac GET /mayo-api/products/:id/specification.
• Zaimplementowac POST /mayo-api/products/:id/specification/refresh.
• Sprawdzic na realnych danych, czy finish na karcie produktu ma byc pojedynczym enumem, czy agregatem z top_finish i back_finish.
• Przetestowac frontend z VITE_USE_MOCK_API=false.