Rozszerzanie widoków przez hooki

{
    key: 'core.shipping',   // stabilny identyfikator (zwykle kod modułu)
    title: 'Przesyłki',     // opcjonalny; diagnostyka i logi – nagłówek ma sam fragment (karta)
    order: 20,              // kolejność sklejania rosnąco; brak → 100
    view: { type: 'card' }  // czysty root widget OVE
}

const { Core, DB, Log } = require('@orbito/api-lib');
const Order = require('../src/models/Order');
const { PERMISSIONS, requirePermission } = require('../src/register-permissions');
const {
    ORDER_DETAILS_HOOK,          // 'views.orderDetails'
    normalizeFragments,          // walidacja, deduplikacja, sortowanie
    buildOrderDetailsView,       // sklejenie w root widget
} = require('../src/lib/order-details-block');

module.exports = {
    description: 'Buduje blok karty zamówienia z fragmentów dostarczonych przez inne moduły',

    params: {
        orderId: { type: 'string', required: true },
    },

    handler: async function(params, ctx) {
        requirePermission(PERMISSIONS.ORDERS_VIEW, ctx);

        const order = await Order.findOne({ _id: new DB.ObjectId(params.orderId) });
        if (!order) {
            throw new Error('Order not found');
        }

        // Handlery dostają surowy dokument zamówienia – fragmenty i tak wołają
        // własne metody modułu po `orderId`.
        const responses = await Core.execHook(ORDER_DETAILS_HOOK, {
            orderId: String(order._id),
            order,
        });

        const fragments = normalizeFragments(responses, (message, details) => Log.warn(message, details));

        return {
            view: buildOrderDetailsView(fragments),
            fragments: fragments.map(({ key, title, order: position }) => ({ key, title, order: position })),
        };
    },
};

{
    type: 'flex',
    id: 'orderDetailsBlock',
    direction: 'column',
    gap: 3,
    childs: fragments.map(fragment => fragment.view),
}

const { Core } = require('@orbito/api-lib');
const { orderDetailsViewHandler } = require('./src/hooks/order-details-view');

// Zależność jest jednostronna: `core.orders` emituje hook i skleja odpowiedzi,
// nie znając tego modułu.
Core.registerHook('views.orderDetails', orderDetailsViewHandler);

const path = require('path');
const { Log } = require('@orbito/api-lib');
const { loadViewSchema, bindPlaceholders } = require('../lib/view-schema');

const SLOT_VIEW_FILE = path.join(__dirname, '..', '..', 'pages', 'slots', 'order-details.yaml');

async function orderDetailsViewHandler(payload) {
    try {
        const orderId = payload?.orderId;
        if (!orderId) {
            return null;
        }

        return {
            key: 'core.shipping',
            title: 'Przesyłki',
            order: 20,
            view: bindPlaceholders(loadViewSchema(SLOT_VIEW_FILE), { orderId }),
        };
    } catch (err) {
        Log.error('Shipping: nie udało się zbudować fragmentu widoku zamówienia', {
            orderId: payload?.orderId,
            error: err?.message,
        });
        return null;
    }
}

module.exports = { orderDetailsViewHandler };

{
    orderIds: ['<id>', ...],
    // lekka projekcja zamówień – tyle, ile trzeba do oceny własnej flagi
    orders: [{
        _id: '<id>',
        invoice: { isNeeded: true },
        isPaid: true,
        isPacked: false,
        delivery: { isCod: false },
    }],
}

{
    key: 'shipment',              // stabilny, unikalny identyfikator (wymagany)
    label: 'Przesyłka',           // etykieta dla operatora (wymagana)
    icon: 'truck-delivery',       // ikona Tabler bez prefiksu `ti-` (wymagana)
    order: 30,                    // kolejność w wierszu rosnąco; brak → 100
    inactive: {                   // opcjonalny opis stanu „nic się nie wydarzyło”
        title: 'Brak przesyłki',
        summary: 'Nie utworzono przesyłki dla zamówienia',
    },
    states: {                     // stan per zamówienie – tylko dla tych, które go mają
        '<orderId>': {
            active: true,
            tone: 'success',      // success | info | warning | muted
            title: 'Przesyłka utworzona',
            summary: 'Kurier: DPD\nNumer przesyłki: 0001234567',
        },
    },
}

const { Core, Log } = require('@orbito/api-lib');
const Shipment = require('./src/models/Shipment');

// Emitent (`core.orders`) woła hook raz na stronę wyników, a tam `perPage` jest ≤ 100.
const MAX_ORDER_IDS = 100;

Core.registerHook('orders.flags', async payload => {
    try {
        const orderIds = (payload?.orderIds || [])
            .filter(orderId => typeof orderId === 'string' && orderId.trim())
            .slice(0, MAX_ORDER_IDS);

        if (!orderIds.length) {
            return null;
        }

        // Jedno zapytanie na całą stronę listy.
        const shipments = await Shipment.find({ orderId: { $in: orderIds } }, 1000, 0, { createdAt: -1 });

        const states = {};
        for (const shipment of shipments) {
            const orderId = String(shipment.orderId || '');
            if (!orderId || states[orderId]) {
                continue;
            }

            states[orderId] = {
                active: true,
                tone: shipment.status === 'error' ? 'warning' : 'success',
                title: 'Przesyłka utworzona',
                summary: `Kurier: ${shipment.carrier}\nNumer przesyłki: ${shipment.trackNo}`,
            };
        }

        return {
            key: 'shipment',
            label: 'Przesyłka',
            icon: 'truck-delivery',
            order: 30,
            inactive: {
                title: 'Brak przesyłki',
                summary: 'Nie utworzono przesyłki dla zamówienia',
            },
            states,
        };
    } catch (err) {
        Log.error('Shipping: nie udało się zbudować flagi przesyłki', { error: err?.message });
        return null;
    }
});

{
    module: 'core/shipping',   // moduł, do którego wraca przycisk
    page: 'shipments',         // strona tego modułu
    label: 'przesyłek',        // dopełniacz do tytułu „Wróć do przesyłek”
}