Definición de modelos de datos para aplicaciones de Fabric

Fabric Apps usa decoradores typeScript para definir modelos de datos que generan tablas y API de base de datos. Cada entidad se define como una clase decorada con @entity(), se agregan decoradores de campo para tipos de datos y se asignan relaciones entre entidades.

Para obtener instrucciones sobre autorización y control de acceso, consulte Definición de permisos de datos.

Prerequisites

• Un proyecto Fabric Apps creado con npm create @microsoft/rayfin@latest o inicializado con npx rayfin init.
• Conocimientos básicos de las clases y decoradores de TypeScript.

Definición de una entidad

Para crear un modelo de datos, agregue el @entity() decorador a una clase TypeScript. A continuación, importe los decoradores necesarios desde @microsoft/rayfin-core:

import { entity, uuid, text, date } from '@microsoft/rayfin-core';

@entity()
export class Todo {
  @uuid() id!: string;
  @text() title!: string;
  @text({ optional: true }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

Esta entidad genera una Todo tabla con columnas para id, title, description, createdAty updatedAt.

Claves principales

Cada entidad usa un campo UUID string denominado id como clave principal. Si no declara id explícitamente, Fabric Apps lo agrega al esquema automáticamente.

• El id campo es opcional durante las operaciones de creación; el servidor genera un UUID si lo omite.
• Puede proporcionar su propio UUID en tiempo de creación si prefiere identificadores generados por el cliente.
• No se admiten claves principales compuestas ni nombres de clave personalizados.

@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Supported data types (Tipos de datos admitidos)

Use estos decoradores para definir tipos de campo:

Ejemplo con varios tipos

import { entity, uuid, text, int, decimal, boolean, date, set } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @decimal() price!: number;
  @int() stockQuantity!: number;
  @boolean() isAvailable!: boolean;
  @date() createdAt!: Date;
  @set('draft', 'published', 'archived') status!: 'draft' | 'published' | 'archived';
}

Modificadores de tipo

Agregue modificadores a decoradores de campo para configurar la validación y las restricciones:

Ejemplo con modificadores

@entity()
export class User {
  @uuid() id!: string;
  @email({ unique: true }) email!: string;
  @text({ min: 3, max: 50 }) username!: string;
  @text({ optional: true, max: 500 }) bio?: string;
  @int({ min: 0, max: 150 }) age!: number;
  @boolean({ default: false }) isVerified!: boolean;
}

Definir relaciones

Use @one() y @many() decoradores para definir propiedades de navegación entre entidades. Fabric Apps genera automáticamente columnas de clave externa al definir las relaciones.

• De uno a varios – Use @many() en el elemento principal y @one() en el elemento secundario.
• Muchos a uno – Use @one() en el elemento secundario para hacer referencia al elemento padre.
• No se admiten relaciones de muchos a muchos; use en su lugar una entidad de unión explícita.

Ejemplo con una relación de uno a varios

import { entity, uuid, text, date, one, many } from '@microsoft/rayfin-core';

@entity()
export class Notebook {
  @uuid() id!: string;
  @text() name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text() title!: string;
  @text() content!: string;
  @date() createdAt!: Date;
  @text() notebook_id!: string;
  @one(() => Notebook) notebook?: Notebook;
}

Al definir @one(() => Notebook) en la entidad Note, Fabric Apps crea automáticamente una columna de clave externa notebook_id. Declare explícitamente el campo de clave externa solo si planea leerlo o establecerlo en el código de aplicación.

Convención de nomenclatura de clave foránea

Al definir un campo de clave foránea, use la convención de nomenclatura {property}_id:

@entity()
export class Note {
  @uuid() id!: string;
  @text() notebook_id!: string;      // Foreign key field
  @one(() => Notebook) notebook?: Notebook;  // Navigation property
}

No se admiten nombres de clave externa personalizados (foreignKey, targetKey opciones).

Entidades del sistema de referencia

Fabric Apps no admite relaciones @one() que apuntan a entidades del sistema como la entidad integrada USER. Para asociar una fila con el usuario que ha iniciado sesión, añada un simple campo user_id de tipo @text() y rellénelo a partir de los claims de autenticación (normalmente claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text() title!: string;
  @text() user_id!: string;  // System user ID from claims.sub
}

Filtre las filas por user_id en las directivas de rol para aplicar el acceso por usuario.

Registro de entidades en el esquema

Agregue todas las clases de entidad a rayfin/data/schema.ts para que el cliente pueda generar servidores proxy de GraphQL:

import type { Note } from './Note.js';
import type { Notebook } from './Notebook.js';

export type NotesAppSchema = {
  Note: Note;
  Notebook: Notebook;
};

Actualice este tipo cada vez que cree una nueva entidad.

Aplicar los cambios de esquema.

Después de definir o modificar entidades, aplique los cambios a la base de datos:

1. Implemente el esquema actualizado en Fabric:

   npx rayfin up db apply
   

2. Si el cambio de esquema incluye operaciones destructivas (quitar columnas, cambiar el nombre de las tablas), la CLI le advierte y se niega a continuar. Use --force para invalidar la comprobación de seguridad:

   npx rayfin up db apply --force
   

procedimientos recomendados

• Defina campos de clave externa solo cuando necesite leerlos o establecerlos en el código; Fabric Aplicaciones los genera automáticamente a partir de decoradores de navegación.
• Use importaciones relativas con extensiones .js en archivos de entidad para que el JavaScript ESM generado se resuelva correctamente.
• Para conocer los patrones de autorización y el acceso basado en roles, consulte Definición de permisos de datos.

Solución de problemas

Relaciones que faltan

Si las relaciones no aparecen en la API, compruebe que:

• El decorador de navegación (@one() o @many()) está presente.
• La entidad está registrada en rayfin/data/schema.ts.

Contenido relacionado

• Consulta de datos con GraphQL
• Definición de permisos de datos
• Implementar en Fabric