Estrutura do projeto Fabric Apps

Os projetos Fabric Apps usam um layout de pastas consistente para que possa encontrar rapidamente modelos de dados, configuração backend e código frontend. Este artigo explica os ficheiros e pastas com que tens mais probabilidade de trabalhar depois de criares um projeto.

Disposição das pastas

Quando cria um novo projeto Fabric Apps, o modelo gera a seguinte estrutura:

your-project/
├── rayfin/
│   ├── data/
│   │   ├── schema.ts
│   │   └── *.ts
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── src/
├── package.json
├── tsconfig.json
└── README.md

Ficheiros de configuração de chaves

rayfin/rayfin.yml

O ficheiro rayfin/rayfin.yml é o principal ficheiro de configuração para o backend do teu Fabric Apps. Controla quais os serviços que correm durante o desenvolvimento local e suporta a interpolação de variáveis de ambiente para valores de configuração dinâmicos.

Exemplo completo:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    expiryInMinutes: 60
    refreshToken:
      lifetimeInDays: 30
    customClaims:
      tenant: "default"
    scopes:
      - read:data
      - write:data
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    password:
      enabled: true
    fabric:
      enabled: false
    passwordless:
      magicLink:
        enabled: false
        expiryMinutes: 15
      smsOtp:
        enabled: false
    email:
      enabled: false
      provider: smtp
      senderName: Rayfin Platform
      verificationTokenExpirationHours: 24
      passwordResetTokenExpirationMinutes: 30
      smtp:
        host: maildev
        port: 1025
        senderEmail: noreply@rayfin.local
        username: ""
        password: ""
        useSsl: false
        useStartTls: false
        webPort: 1080
  data:
    enabled: true
    dialect: mssql
  storage:
    enabled: false
  staticHosting:
    enabled: true
    root: .
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

A configuração inclui estes campos-chave:

Campos de nível superior

Campo Tipo Obrigatório Descrição
id string Yes Project slug usado como nome do project Docker Compose e identificador de item Fabric.
name string Yes Nome de exibição do projeto legível por humanos.
version string Yes Versão do projeto (semver).
services object Yes Bloco de configuração de serviço.

services.data

Campo Tipo Predefinição Descrição
enabled boolean false Ativa o serviço de dados.

services.auth

Campo Tipo Predefinição Descrição
enabled boolean false Ativa o serviço de autenticação.
expiryInMinutes number — O token JWT expira em minutos.
customClaims Record<string, string> — Reivindicações alfandegárias adicionadas aos JWTs emitidos.
scopes string[] — Âmbitos do OAuth (por exemplo, ["read:data", "write:data"]).
refreshToken.lifetimeInDays number — A vida útil do token de atualização em dias.
allowedRedirectUris string[] ["http://localhost:5173"] URIs de redirecionamento permitidos para retornos de chamada de autenticação.

services.auth.password

Campo Tipo Predefinição Descrição
enabled boolean true Ativar autenticação por email e palavra-passe para desenvolvimento local

services.auth.fabric

Campo Tipo Predefinição Descrição
enabled boolean false Ativar autenticação intermediada Fabric (Microsoft Entra ID SSO).

services.staticHosting

Campo Tipo Predefinição Descrição
enabled boolean false Ative o alojamento de conteúdo estático.
root string — Diretório raiz do projeto frontend (em relação à raiz do projeto).
folder string "dist" Diretório contendo ativos estáticos construídos (relativamente a root).
buildCommand string — Comando shell para executar antes de empacotar (por exemplo, npm run build).
indexDocument string — Documento padrão servido para o caminho raiz (por exemplo, index.html).

Sugestão

Todos os valores de cadeia de caracteres suportam a interpolação de variáveis de ambiente com a sintaxe ${VAR} e ${VAR:-default}. As variáveis são obtidas a partir de rayfin/.env e do ambiente da shell.

rayfin/.env

O ficheiro rayfin/.env é um ficheiro de ambiente opcional utilizado para fornecer valores a rayfin.yml por interpolação. Não incluas segredos no teu repositório. Em vez disso, crie um rayfin/.env.example ficheiro para fins de documentação e adicione .env ao seu .gitignore ficheiro.

Rayfin/tsconfig.json

O ficheiro rayfin/tsconfig.json é uma configuração TypeScript de referência de projeto usada pela CLI Fabric Apps para compilar as definições das suas entidades. Isto estende a raiz tsconfig.json e substitui as definições de que o Fabric Apps necessita, como composite: true e a resolução de módulos do Node.js. Não deverias precisar de editar este ficheiro diretamente.

Ficheiros de modelos de dados

rayfin/data/*.ts

Os ficheiros na rayfin/data/ pasta definem as suas entidades. As entidades são classes TypeScript decoradas com @entity(), bem como com decoradores de campo como @uuid() e @text(). Cada ficheiro de entidade exporta uma classe que representa um modelo de dados na sua aplicação.

rayfin/data/schema.ts

O rayfin/data/schema.ts ficheiro mapeia nomes de entidades para as suas classes. O cliente SDK Rayfin utiliza este mapa para fornecer acesso seguro por tipos a entidades através de client.data.<Entity>. Quando adiciona uma nova entidade, deve registá-la neste ficheiro de esquema.

Artefactos gerados

rayfin/.temp/

A rayfin/.temp/ pasta contém artefactos de backend gerados que são criados quando executas o servidor de desenvolvimento. Se o backend parecer estar a usar um schema ou uma configuração desatualizados, pare e reinicie o ambiente de desenvolvimento para regenerar estes ficheiros.

Importante

Não comprometas a .temp/ pasta no teu repositório. Adicione-o ao seu .gitignore ficheiro.

Estrutura do front-end

A src/ pasta contém o código da sua aplicação frontend. A estrutura exata depende do modelo que escolheste ao criar o teu projeto, como React ou Vue.

Os modelos do Fabric Apps utilizam as seguintes variáveis de ambiente Vite para a configuração frontend:

  • VITE_RAYFIN_API_URL – URL base que aponta o frontend para o backend da Fabric Apps. Defina esta variável de ambiente antes de executar npm run dev para substituir a predefinição.
  • VITE_RAYFIN_PUBLISHABLE_KEY – Chave publicável usada para autenticação de clientes.
  • VITE_FABRIC_ITEM_ID – ID do item Fabric definido por rayfin up. Escrito para .env.fabric-<workspacename> (e .env.fabric) durante a implantação. Usado para autenticação intermediada pelo Fabric.
  • VITE_FABRIC_WORKSPACE_ID – ID do espaço de trabalho do Fabric definido por rayfin up. Escrito juntamente com VITE_FABRIC_ITEM_ID durante a implementação.

Conteúdo relacionado

  • Last updated on