Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.