Struttura del progetto app Fabric

I progetti Fabric Apps separano configurazioni backend, modelli dati e codice frontend. La disposizione esatta dipende dal modello. Il template predefinito blankapp corrisponde a Universal App, uno spazio di lavoro npm con frontend, dati e pacchetti condivisi separati.

Layout della cartella

L'impalcatura predefinita dell'Universal App ha la seguente struttura:

your-project/
├── rayfin/
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── packages/
│   ├── frontend/
│   │   ├── src/
│   │   └── package.json
│   ├── data/
│   │   └── src/index.ts
│   └── shared/
│       └── src/index.ts
├── package.json
├── tsconfig.json
└── README.md
Location Proprietà
rayfin/ Configurazione backend e valori dell'ambiente attivo.
packages/frontend/ Interfaccia del browser, inizializzazione del client e costruzione frontend.
packages/data/ Classi di entità in runtime decorate e registrazione dello schema.
packages/shared/ Contratti di record isomorfi e tipi di schema condivisi con il frontend. Non mettere qui codice solo backend.

I dati sono disabilitati nello scaffold di base. Attivalo quando la tua app ha bisogno di record persistenti:

npm run pack:add -- data-modeling

La funzionalità aggiunge un'entità iniziale e un contratto condiviso e abilita il servizio dati. Per la modellazione delle entità e la configurazione del dialetto MSSQL, vedi Definire modelli dati.

Alternativa al modello piatto

Alcuni template e app esistenti utilizzano un layout piatto con codice frontend nella radice src/, entità in rayfin/data/, e una mappa di tipo schema in rayfin/data/schema.ts. Questa disposizione rimane valida. Non spostare file o creare pacchetti duplicati solo per abbinarsi a un altro template. Leggi i percorsi di servizio in rayfin/rayfin.yml per trovare le directory che il tuo progetto effettivamente genera.

File di configurazione chiave

rayfin/rayfin.yml

Il file rayfin/rayfin.yml è il file di configurazione principale per il back-end Fabric Apps. Controlla i servizi eseguiti durante lo sviluppo locale e supporta l'interpolazione di variabili di ambiente per i valori di configurazione dinamica.

Lo spazio di lavoro predefinito utilizza percorsi di servizio espliciti. Il seguente esempio mostra quei percorsi con Data abilitato per un'app che necessita di un database:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: false
  data:
    enabled: true
    dialect: mssql
    path: packages/data
    buildCommand: npm run build
  staticHosting:
    enabled: true
    path: packages/frontend
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected

I valori del servizio path sono relativi alla radice del progetto. I comandi di build vengono eseguiti nella directory del servizio risolta. L'inizializzazione delle funzioni registra services.functions.path anche quando seleziona un pacchetto workspace come packages/functions. I progetti flat possono utilizzare il percorso esistente rayfin/functions. Vedi Utilizzo delle funzioni.

La configurazione include questi campi chiave:

Campi di primo livello

Campo Tipo Obbligatorio Description
id string Sì Slug del progetto usato come nome del progetto Docker Compose e identificatore dell'elemento Fabric.
name string Sì Nome visualizzato del progetto comprensibile.
version string Sì Versione del progetto (semver).
services object Sì Blocco di configurazione del servizio.

services.data

Campo Tipo Impostazione predefinita Description
enabled boolean false Abilitare il servizio dati.
dialect string — Usa mssql per un database SQL in Fabric. Richiesto quando i dati sono abilitati.
path string — Directory dei pacchetti dati rispetto alla radice del progetto, come packages/data. I modelli flat possono usare rayfin/data.
buildCommand string — Comando di compilazione per il pacchetto dati configurato.

services.storage

Campo Tipo Impostazione predefinita Description
enabled boolean false Abilita l'archiviazione remota dei file. Richiede services.data.enabled: true.
path string . Root del progetto di archiviazione, rispetto alla radice dell'app. Ad esempio: packages/storage.

Lo storage funziona su Fabric, anche durante lo sviluppo. Non utilizza un servizio di archiviazione locale o un emulatore. Dichiara le cartelle e le loro politiche di accesso nella directory radice rayfin/storage/ del progetto di archiviazione configurato. Per le istruzioni di configurazione, vedi Archivia e gestisci file.

services.auth

Campo Tipo Impostazione predefinita Description
enabled boolean false Abilitare il servizio di autenticazione.
expiryInMinutes number — Il token JWT scade in pochi minuti.
customClaims Record<string, string> — Attestazioni personalizzate aggiunte ai token JWT emessi.
scopes string[] — Scope OAuth (ad esempio, ["read:data", "write:data"]).
refreshToken.lifetimeInDays number — Durata del token di aggiornamento in giorni.
allowedRedirectUris string[] ["http://localhost:5173"] URI di reindirizzamento consentiti per i callback di autenticazione.

services.auth.password

Campo Tipo Impostazione predefinita Description
enabled boolean true Abilitare l'autenticazione tramite posta elettronica e password per lo sviluppo locale

services.auth.fabric

Campo Tipo Impostazione predefinita Description
enabled boolean false Abilitare l'autenticazione mediata di Fabric (Microsoft Entra ID SSO).
externalEntraExchange boolean — Abilita lo scambio diretto delegato di token Entra e l'autenticazione con host genitore esterno quando supportate dall'ambiente target.

services.staticHosting

Campo Tipo Impostazione predefinita Description
enabled boolean false Abilitare l'hosting di contenuto statico.
path string — Directory dei pacchetti frontend rispetto alla radice del progetto.
root string — Root legacy del frontend usato da configurazioni flat.
folder string "dist" Directory contenente asset statici costruiti rispetto al percorso frontend risolto.
buildCommand string — Comando Shell da eseguire prima della creazione del pacchetto , ad esempio npm run build.
indexDocument string — Documento predefinito servito per il percorso radice (ad esempio, index.html).

Suggerimento

Tutti i valori di tipo stringa supportano l'interpolazione delle variabili di ambiente con la sintassi ${VAR} e ${VAR:-default}. Le variabili vengono ricavate da rayfin/.env e dall'ambiente della shell.

rayfin/.env

Il file rayfin/.env contiene i valori attivi di runtime e deployment e fornisce valori a rayfin.yml tramite interpolazione. La CLI scrive valori neutrali RAYFIN_PUBLIC_* rispetto al framework per il backend attivo. Solo le variabili con quel prefisso vengono incluse nei file di ambiente del frontend generati. Non mettere mai segreti nelle RAYFIN_PUBLIC_* variabili.

Evita rayfin/.env dal controllo del codice sorgente. Usare rayfin/.env.example per documentare le variabili attese con segnaposto.

rayfin/.deployments.json

Il registro di distribuzione registra gli URL backend, gli URL di hosting, gli ID degli oggetti e gli ID dello spazio di lavoro per le distribuzioni del tuo progetto. Non è un file di ambiente frontend. Tienilo fuori dal controllo del codice sorgente. Usare npx rayfin up list per elencare i deployment registrati e npx rayfin up switch <name> per passare al deployment attivo e rigenerare i relativi valori di ambiente.

rayfin/tsconfig.json

I template forniscono la configurazione TypeScript per il loro layout. I pacchetti workspace hanno le proprie configurazioni e riferimenti ai progetti; i template piatti possono compilare entità tramite rayfin/tsconfig.json. Preservare i riferimenti dello scaffold e utilizzare i suoi script di build e type-check invece di assumere una singola compilazione root.

File del modello di dati

Mantieni allineati i tipi di registrazione runtime e quelli rivolti al cliente con il layout scelto.

Entità dello spazio di lavoro e contratti condivisi

In Universal App, i file sotto packages/data/src/ definiscono classi di entità decorate. Registra le classi di runtime nell'array schema esportato da packages/data/src/index.ts.

Mantieni le interfacce di record corrispondenti e il UniversalAppSchema tipo in packages/shared/src/index.ts. Il frontend importa questo contratto da @rayfin-app/shared invece di importare classi backend decorate.

Entità con modello piatto

In un template piatto, rayfin/data/*.ts definisce entità e rayfin/data/schema.ts mappa i nomi delle entità a tipi per client.data.<Entity>. Segui il meccanismo di registrazione fornito da quel template.

File di archiviazione

La cartella opzionale rayfin/storage/ sotto la radice del progetto di archiviazione contiene classi decorate con @blob() e un schema.ts file che le registra. Quando ometti services.storage.path o lo imposti su ., aggiungi questi file nella cartella rayfin/storage/ della tua app. Ad esempio, services.storage.path: packages/storage colloca questi file sotto packages/storage/rayfin/storage/. Esporta un array schema che elenchi le cartelle per cui effettuare il deploy in Fabric. Il AppStorageSchema tipo mappa i nomi delle cartelle alle classi per l'accesso al client tipizzato. Per un esempio, vedi Archivia e gestisci file.

Artefatti generati

rayfin/.temp/

La rayfin/.temp/ cartella contiene elementi back-end generati creati quando si esegue il server di sviluppo. Se il back-end sembra usare uno schema o una configurazione non aggiornati, arrestare e riavviare lo stack di sviluppo per rigenerare questi file.

Importante

Non eseguire il commit della .temp/ cartella nel repository. Aggiungerlo al .gitignore file.

Struttura front-end

Il frontend predefinito è in packages/frontend/src/. I modelli flat possono usare la radice src/. L'impostazione services.staticHosting.path identifica il pacchetto frontend.

Mappatura dell'ambiente e del framework attivi

rayfin dev e rayfin up generano valori specifici .env.local del framework da rayfin/.env. Per un frontend annidato, il file viene scritto sotto services.staticHosting.path, come packages/frontend/.env.local; i progetti flat utilizzano la radice del progetto.

Sorgente in rayfin/.env Output di Vite in .env.local Next.js output in .env.local
RAYFIN_PUBLIC_API_URL VITE_RAYFIN_API_URL NEXT_PUBLIC_RAYFIN_API_URL
RAYFIN_PUBLIC_PUBLISHABLE_KEY VITE_RAYFIN_PUBLISHABLE_KEY NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY
RAYFIN_PUBLIC_ITEM_ID VITE_FABRIC_ITEM_ID NEXT_PUBLIC_FABRIC_ITEM_ID
RAYFIN_PUBLIC_WORKSPACE_ID VITE_FABRIC_WORKSPACE_ID NEXT_PUBLIC_FABRIC_WORKSPACE_ID
RAYFIN_PUBLIC_PORTAL_URL VITE_FABRIC_PORTAL_URL NEXT_PUBLIC_FABRIC_PORTAL_URL

Modifica i valori sorgente in rayfin/.env, non il file generato. Per rigenerare senza distribuire:

npx rayfin env --framework vite

Usa --framework nextjs o --framework plain per altre mappe supportate. Usare --output <dir> per scegliere una directory di output o --show per ispezionare la mappatura pubblica senza scrivere. Tieni i file generati .env.local fuori dal controllo del codice sorgente.

Migra un layout di ambiente precedente

I progetti più vecchi potrebbero contenere file .env.fabric o .env.fabric-<workspace>. Questi file non sono i file dell'ambiente attivo nel layout attuale. Esegui npx rayfin up per usare il flusso di lavoro dell'ambiente corrente. Rivedi eventuali messaggi di migrazione e copia i valori personalizzati in rayfin/.env quando necessario. Il registro di deployment sostituisce i file dell'ambiente di ogni area di lavoro. Non configurare nuove app in modo che dipendano da esse.