Arcturus-Morningstar-Extended/docs/builders_club_catalog_reference.md

Builders Club Catalog Reference

Questa guida riassume il setup corretto dopo la separazione completa tra catalogo normale e Builders Club.

Tabelle usate davvero

• Catalogo normale:
  • catalog_pages
  • catalog_items
• Builders Club:
  • catalog_pages_bc
  • catalog_items_bc
• Abbonamenti / add-on BC venduti nel catalogo normale:
  • catalog_club_offers

Quindi:

• se vuoi una pagina BC, va in catalog_pages_bc
• se vuoi un furni BC, va in catalog_items_bc
• se vuoi vendere lo stesso furni anche nel catalogo normale, aggiungi un'altra riga normale in catalog_items

Questo è proprio il vantaggio della separazione: lo stesso item_id può comparire sia nel catalogo normale sia nel BC, ma con comportamenti diversi.

Differenza pratica tra catalogo normale e BC

Catalogo normale

• gli offer arrivano da catalog_items
• hanno costi normali (cost_credits, cost_points, ecc.)
• quando comprati diventano proprietà utente / inventario

Builders Club

• gli offer arrivano da catalog_items_bc
• non hanno prezzo perché il piazzamento BC usa il flow dedicato
• non entrano nell'inventario utente
• non diventano mai proprietà utente
• quando rimossi dalla stanza vengono eliminati

Migration da applicare

Assicurati di avere applicato:

• Database Updates/009_add_builders_club_catalog_offers.sql
• Database Updates/010_add_catalog_mode_to_catalog_pages.sql
• Database Updates/011_add_builders_club_trial_room_lock.sql
• Database Updates/012_support_builders_club_catalog_tables.sql

La 012 è importante perché aggiorna catalog_pages_bc.page_layout con i layout BC moderni:

• builders_club_frontpage
• builders_club_addons
• builders_club_loyalty

Come aggiungere pagine BC

Le pagine BC vanno create in catalog_pages_bc.

Esempio:

INSERT INTO catalog_pages_bc
(
    parent_id,
    caption,
    page_layout,
    icon_color,
    icon_image,
    order_num,
    visible,
    enabled,
    page_headline,
    page_teaser,
    page_special,
    page_text1,
    page_text2,
    page_text_details,
    page_text_teaser
)
VALUES
(
    -1,
    'Builders Furni',
    'default_3x3',
    1,
    28,
    1,
    '1',
    '1',
    'catalog_header_roombuilder',
    '',
    '',
    'Builders Club',
    'Linea test',
    'Pagina test del Builders Club',
    ''
);

Come aggiungere furni BC

I furni BC vanno in catalog_items_bc.

Esempio:

INSERT INTO catalog_items_bc
(
    item_ids,
    page_id,
    catalog_name,
    order_number,
    extradata
)
VALUES
(
    '12345',
    1,
    'bc_test_sofa',
    1,
    ''
);

Dove:

• item_ids = ID del base item
• page_id = ID pagina in catalog_pages_bc
• catalog_name = chiave offer/localization

Come vendere lo stesso furni anche nel catalogo normale

Se vuoi che lo stesso furni sia:

• vendibile nel catalogo normale
• disponibile anche nel Builders Club

devi avere due righe distinte:

Normale

INSERT INTO catalog_items
(
    page_id,
    item_ids,
    catalog_name,
    cost_credits,
    cost_points,
    points_type,
    amount,
    club_only,
    extradata,
    have_offer,
    offer_id,
    limited_stack,
    order_number
)
VALUES
(
    500,
    '12345',
    'normal_test_sofa',
    5,
    0,
    0,
    1,
    '0',
    '',
    '1',
    -1,
    0,
    1
);

Builders Club

INSERT INTO catalog_items_bc
(
    item_ids,
    page_id,
    catalog_name,
    order_number,
    extradata
)
VALUES
(
    '12345',
    1,
    'bc_test_sofa',
    1,
    ''
);

Quindi lo stesso base item 12345 può vivere in entrambi i cataloghi senza condividere il prezzo.

Abbonamento e add-on BC

Abbonamento e add-on non stanno in catalog_items_bc.

Vanno in:

• catalog_club_offers

Tipi supportati:

• BUILDERS_CLUB
• BUILDERS_CLUB_ADDON

Sono venduti nel catalogo normale, come HC/VIP, ma il widget BC usa comunque le sue pagine dedicate da catalog_pages_bc.

Nota su catalog_mode

catalog_mode resta nella tabella catalog_pages, ma non è più il meccanismo principale per far comparire le pagine nel Builders Club.

Adesso il runtime BC legge direttamente:

• catalog_pages_bc
• catalog_items_bc

Quindi:

• aggiungere pagine BC in catalog_pages non basta
• aggiungere items BC in catalog_items non basta
• usare BOTH su una pagina normale non la renderà automaticamente una pagina BC

Query utili per test

Elencare pagine BC

SELECT * FROM catalog_pages_bc ORDER BY parent_id, order_num, id;

Elencare items BC

SELECT * FROM catalog_items_bc ORDER BY page_id, order_number, id;

Trovare lo stesso furni in entrambi i cataloghi

SELECT 'NORMAL' AS source, id, page_id, item_ids, catalog_name
FROM catalog_items
WHERE item_ids = '12345'

UNION ALL

SELECT 'BC' AS source, id, page_id, item_ids, catalog_name
FROM catalog_items_bc
WHERE item_ids = '12345';

Consiglio pratico

Per fare test rapidi:

1. crea una pagina in catalog_pages_bc
2. inserisci 1-2 furni in catalog_items_bc
3. lascia gli stessi furni anche in catalog_items se li vuoi vendibili normalmente
4. pubblica / ricarica il catalogo

Se vuoi, possiamo aggiungere anche un file SQL separato con qualche pagina BC e qualche furni BC già pronti da importare per i test.

Seed demo già pronto

Se vuoi una demo immediata, puoi usare:

• Database Updates/013_seed_builders_club_sample_page.sql

Questo seed:

• crea una root BC demo
• crea una pagina BC demo figlia
• duplica alcuni furni già esistenti del catalogo normale dentro catalog_items_bc

Così puoi testare subito il caso:

• stesso furni vendibile nel catalogo normale
• stesso furni disponibile anche nel Builders Club