Companies

Scopo

Il modulo gestisce le anagrafiche legali e commerciali delle aziende: customer, supplier o entrambe. La scheda company e' il punto di ingresso per dati fiscali, policy credito, contatti, saldo e collegamenti a trunk, fatture, pagamenti e ticket.

Dove

Elemento	Valore
Route UI	/companies, /companies/new, /companies/[id]
Voce di menu	Clients / Companies
Componenti principali	apps/frontend/src/app/[locale]/(dashboard)/companies/*, apps/frontend/src/components/companies/*, apps/frontend/src/schemas/company.ts

Campi & comportamento

Campo	Significato	Validazione / comportamento
code	Codice interno company	Obbligatorio, massimo 32 caratteri nella modale completa; la pagina rapida lo genera da nome + timestamp.
legal_name	Ragione sociale	Obbligatoria, massimo 255 caratteri. In lista e' il link alla detail.
display_name	Nome visualizzato	Opzionale, massimo 255 caratteri.
kind	Ruolo commerciale	Enum customer, supplier, both; filtrabile server-side in lista.
tier	Segmento commerciale	Enum wholesale, reseller, mobile, tier1; filtrabile server-side in lista.
country_iso2	Paese	ISO2 opzionale; input uppercase, massimo 2 lettere; filtrabile server-side.
timezone	Fuso orario	Testo massimo 64 caratteri, default Europe/Rome.
parent_company_id	Company madre	Select popolata da /api/v1/companies; deve essere una company esistente e non la company corrente. L'errore FK viene mostrato come errore specifico.
is_reseller	Flag reseller	Checkbox.
currency	Valuta base	ISO3 obbligatorio, default EUR; filtro client-side costruito da valute note e dati caricati.
invoicing_period	Periodo fatturazione	Enum daily, weekly, biweekly, monthly, quarterly.
payment_term_days	Giorni pagamento	Intero non negativo.
credit_limit	Limite credito	Numero non negativo.
credit_policy	Policy superamento credito	Enum warn_only, soft_block, hard_block.
payment_mode	Modalita' pagamento	Enum prepaid, postpaid.
current_balance	Saldo corrente	Numero; la modale lo mostra ma avvisa che dopo la creazione e' gestito dal modulo balance.
invoice_locale	Locale fattura	Obbligatorio, massimo 8 caratteri, default en_US.
invoice_template	Template fattura	Opzionale, massimo 64 caratteri, default default.
stopped	Stop traffico	Checkbox nella tab Rates; in lista diventa stato active/stopped filtrato client-side.
stopped_at, stopped_reason	Dettaglio stop traffico	Data/ora locale e testo opzionale.
primary_*, noc_contact_email, finance_*, rates_*	Contatti operativi e finanziari	Email validate come email oppure vuote; rates_email_subject massimo 500 caratteri.
Indirizzo e fiscalita'	address_line1, address_line2, city, state, zip, vat_prefix, vat_number, tax_id	Testi opzionali; vat_prefix e' ISO2 opzionale, vat_number e tax_id massimo 64 caratteri.
notes, tags	Note operative e tag	tags e' inserito come CSV e inviato come array.

Azioni

Azione	Dove	Effetto
Create completa	/companies, bottone New Company	Modale CompanyModal, POST /api/v1/companies.
Create rapida	/companies/new	Form minimale per interconnect, POST /api/v1/companies, redirect a /companies/{id}.
Edit	/companies/[id], bottone Edit	PATCH /api/v1/companies/{id} e refresh detail/lista.
Delete	/companies/[id], bottone Delete	DELETE /api/v1/companies/{id}; se il backend richiede MFA la UI invia prima POST /api/v1/auth/mfa/challenge con action companies.delete e poi header X-MFA-Challenge-Token. Con status 409 mostra che esistono CDR collegati.
Import CSV	/companies, link Import CSV	Naviga a /bulk-import.
Export CSV	/companies, bottone Export CSV	Esporta lato browser le righe filtrate; disabilitato senza risultati.
Consultazione detail	/companies/[id]	Tab Overview, Trunks, Tariffs, Devices, Invoices, Payments, Tickets, Audit. Alcune tab sono link verso moduli dedicati.

API consumate

• List companies - lista, filtri e select parent.
• Create company - creazione completa e rapida.
• Get company - detail.
• Update company - edit.
• Delete company - delete.
• MFA challenge - re-challenge delete quando richiesto.
• List originators e List terminators - tab Trunks.
• List invoices - tab Invoices.
• List tickets - tab Tickets, con retry disabilitato.

Permessi/ruoli

La UI non mostra ruoli espliciti per lista/create/edit. La delete gestisce una richiesta MFA condizionale con action companies.delete. I ruoli RBAC effettivi sono da verificare in backend/RBAC.

Stati & edge case

• Loading: lista e detail mostrano un box/testo di caricamento.
• Empty: lista mostra Nessuna company; tab Trunks, Invoices e Tickets hanno empty message dedicati.
• Errori: lista e detail usano BannerError; parent company FK ha messaggio mirato per evitare confusione con VAT/Tax ID.
• Filtri server-side: q, kind, tier, country. Filtri client-side: status e currency.
• Detail Tariffs, Devices e Payments non editano dati locali: rimandano ai moduli /tariffs, /devices, /payments.
• Audit tab: il backend non espone ancora audit trail filtrato per company; la UI mostra empty state.

Collegamenti

• Moduli correlati: Originators, Terminators, Devices, Balance/Payments/Invoicing, Bulk Import.