Crear un archivo de esquema (.sfn)

Webspace empieza con un pequeño archivo. Al definir los datos y los permisos en un archivo de esquema (.sfn) y desplegarlo, se preparan conjuntamente la base de datos y las API. Después podrá crear un servicio en el que el contenido introducido en la pantalla se guarde y aparezca en tiempo real en las pantallas de otros usuarios.

El archivo de esquema es el plano del servicio. Guardarlo no modifica la base de datos real; debe desplegarlo en API Build para aplicarlo al entorno de ejecución.

Flujo de creación

1. Cree un archivo de esquema.
2. Configure las tablas y columnas.
3. Compruebe los permisos de acceso de cada API.
4. Seleccione un motor de almacenamiento y realice el despliegue.
5. Invoque las API generadas desde HTML o una aplicación.

No necesita completar todo desde el principio. La forma más sencilla de comprenderlo es empezar con una tabla pequeña, introducir datos desde una pantalla real y ampliar después la estructura y los permisos.

Crear un archivo de esquema

En el espacio de trabajo, seleccione Create > Template Files > New Schema DB.

Introduzca un nombre y guarde para crear el archivo.

En este paso no se elige un motor de base de datos. Cree primero la estructura y seleccione SQLite3, PostgreSQL, MySQL o MariaDB como motor de almacenamiento real durante el despliegue.

Crear la estructura de datos

Puede crearla desde cero o preparar un borrador con AI y perfeccionarlo. Si ya dispone de SQL, también puede importarlo.

1. Crear un borrador con AI

No necesita conocer todos los términos de las tablas. Describa qué información desea gestionar y con quién, y la AI creará una estructura inicial.

1. Seleccione Copy AI prompt.
2. Pegue el prompt copiado en la ventana de chat del servicio de AI que utilice.
3. Debajo de ## Request, al final de las instrucciones, describa el servicio que desea crear.

   Ejemplo: gestione el nombre de la patente, el número de solicitud, la persona responsable y el estado, y permita que solo la persona responsable y los administradores lo modifiquen.

4. Copie el JSON creado por la AI y péguelo en la pantalla de importación.
5. Seleccione Import para crear la estructura de tablas en el esquema, como se muestra a continuación.

Las instrucciones copiadas incluyen el formato y las reglas de escritura del archivo de esquema. Priorizan una estructura válida para varios motores de almacenamiento frente a SQL específico de una base de datos.

El botón Copy AI prompt copia instrucciones para generar el esquema. El siguiente ejemplo muestra el formato para un esquema vacío con el motor SQLite, con las instrucciones de idioma adaptadas para obtener comentarios en español. El prompt que copia el producto depende del esquema, del motor y del idioma de la interfaz actuales; puede ajustar manualmente sus instrucciones de idioma. Empiece con este prompt en lugar de escribir el archivo manualmente.

Eres un asistente para diseñar esquemas de bases de datos.
Devuelve únicamente JSON válido.
No añadas explicaciones.
No encierres la respuesta en bloques de código Markdown.
Devuelve solo el array data de un archivo de esquema de SetFN.
No incluyas content-type, dbType ni apiBuild.
Motor de despliegue actual: SQLite.
El motor de almacenamiento forma parte de la configuración del despliegue, no de la sintaxis del esquema. Mantén el esquema compatible con SQLite, PostgreSQL, MySQL y MariaDB.

## Idioma
- Los identificadores deben estar en inglés y usar ASCII: "label" y los nombres de tablas y columnas deben escribirse en snake_case inglés; las claves JSON, los tipos y los valores predeterminados deben conservarse exactamente como se muestran.
- Escribe en español las cadenas destinadas a las personas: todos los valores "cmt", incluidos los comentarios de tablas y columnas y la descripción de los valores permitidos.
- La solicitud del usuario que aparece más abajo puede estar escrita en español. Interprétala como requisitos; no traduzcas los identificadores a ese idioma.
- El estado actual que aparece más abajo son datos y puede contener texto en cualquier idioma. Conserva exactamente los nombres y las claves existentes.

Reglas de seguridad y portabilidad:
- Nunca incluyas contraseñas, tokens, claves de API, cadenas de conexión, hosts, puertos, usuarios de base de datos ni otras credenciales.
- Los nombres de tablas, "label" y los nombres de columnas deben estar en snake_case ASCII, sin caracteres que no sean ASCII. Todas las tablas deben tener columnas y comenzar por la columna id que se muestra más abajo.
- Usa únicamente tipos lógicos portables de SetFN: serial4, serial8, int2, int4, int8, integer, real, float4, float8, numeric, decimal, varchar, char, text, bool, json, timestamp, timestamptz, date, time, bytea, blob, uuid. Escribe solo el nombre del tipo y coloca la longitud en "len" ("type": "varchar", "len": 20); no escribas nunca "varchar(20)".
- No generes expresiones de tipos nativas de una base de datos ni fragmentos SQL como enum(...), SET(...), unsigned dentro de una cadena de tipo, arrays, columnas generadas, cláusulas de motor o funciones predeterminadas específicas de un proveedor.
- Si un campo tiene un conjunto fijo de valores, usa "text" y documenta los valores permitidos en "cmt". No inventes una propiedad enum.
- No hagas público un endpoint salvo que el usuario solicite acceso público de forma explícita. Nunca hagas públicas de forma predeterminada las operaciones create, update o delete.
- Configura de forma predeterminada el acceso autenticado en todas las tablas. Usa ownerOnly solo con una columna de propietario válida, como "_user_id".

Usa los valores predeterminados canónicos con independencia del motor de despliegue.
- Columnas de ID automático: "auto_increment"
- Valores predeterminados de fecha y hora: "now()"
El servicio de despliegue convierte estos tipos lógicos y valores predeterminados al motor seleccionado.

Columnas del sistema recomendadas:
- "_user_id": ID del usuario propietario. Úsala en lugar de campos personalizados como "user_id" o "author_id" cuando el registro pertenezca al usuario que ha iniciado sesión.
- "_nick": apodo del autor. Puede insertarse automáticamente a partir de los datos de la sesión, así que no crees otro campo de apodo duplicado salvo que sea realmente necesario.
- "_created_at": fecha y hora de creación. Úsala en lugar de campos personalizados como "created_at".
- "_updated_at": fecha y hora de actualización. Úsala en lugar de campos personalizados como "updated_at".
- "_deleted_at": fecha y hora opcional de eliminación lógica. Inclúyela solo cuando sea necesaria la eliminación lógica.

Indicaciones sobre las columnas del sistema:
- Estas columnas son opcionales, pero debes preferirlas cuando encajen con el caso de uso.
- Si la tabla necesita registrar al autor o propietario, usa preferentemente "_user_id" y, de forma opcional, "_nick".
- Si la tabla necesita las fechas de creación y actualización, usa preferentemente "_created_at" y "_updated_at".
- Evita generar columnas personalizadas duplicadas como "user_id", "nick", "created_at" o "updated_at" cuando puedan usarse las columnas del sistema correspondientes.
- Puedes omitir las columnas del sistema si el esquema solicitado no las necesita claramente.

Contrato para juegos de tablero por turnos:
- Aplícalo solo cuando el usuario solicite un juego de tablero por turnos, como un juego de alinear fichas.
- Crea tres tablas portables cuyos nombres pueden adaptarse al juego del usuario: una tabla de partidas, una de movimientos y una de jugadores.
- La tabla de partidas debe contener: id, room_code (único), status, black_user_id, white_user_id, current_turn, winner_user_id, result, move_count, board_size, win_length, black_time_ms, white_time_ms, turn_started_at, finish_reason, finished_at, _created_at, _updated_at.
- La tabla de movimientos debe contener: id, game_id (indexado), move_no, user_id, stone, row, col, result, _created_at. Haz que (game_id, row, col) sea único cuando el formato del esquema lo permita.
- La tabla de jugadores debe contener: id, user_id (único), nickname, wins, losses, draws, score, _updated_at.
- Usa tipos lógicos y valores predeterminados portables. No añadas un campo eventProcessor a los datos de las tablas. Después de generar el esquema, el usuario conecta los nombres de estas tablas al procesador "turn-based-board" registrado en API Build > Feature connections.
- No inventes identificadores de procesadores ni controladores de servidor específicos del juego.

Estructura obligatoria:
[
  {
    "label": "users",
    "table": { "name": "users", "cmt": "Miembros" },
    "columns": [
      {
        "name": "id",
        "type": "serial4",
        "notnull": true,
        "primary": true,
        "index": false,
        "unique": false,
        "default": "auto_increment",
        "cmt": "PK"
      },
      {
        "name": "_user_id",
        "type": "int4",
        "notnull": true,
        "index": true,
        "unique": false,
        "default": null,
        "cmt": "ID del propietario (insertado desde la sesión)"
      },
      {
        "name": "_created_at",
        "type": "timestamp",
        "notnull": false,
        "index": false,
        "unique": false,
        "default": "now()",
        "cmt": "Fecha de creación"
      }
    ],
    "permissions": {
      "security": { "login": true, "ownerColumn": "_user_id" },
      "ops": {
        "list": { "login": true },
        "view": { "login": true },
        "create": { "login": true },
        "update": { "login": true, "ownerOnly": true },
        "delete": { "login": true, "roles": ["admin"] }
      }
    }
  }
]

Los valores "cmt" del ejemplo están en español para mostrar la estructura; sigue las reglas de idioma para los valores reales.

Datos actuales:
[]

## Resultado
Responde únicamente con el array JSON data en el formato anterior. Escribe en español los textos destinados a las personas, como descripciones, etiquetas e indicaciones.

## Solicitud
[Escriba aquí la solicitud para crear o modificar el esquema]

El resultado de la AI es solo un borrador. Antes de desplegarlo, compruebe que los nombres sean comprensibles, que no se haya incluido información personal y qué personas deben poder consultar y modificar los datos.

2. Importar SQL

En Import > SQL, puede pegar instrucciones CREATE TABLE existentes. Los principales tipos, valores predeterminados, índices y restricciones de SQLite, PostgreSQL y MySQL/MariaDB se convierten a la estructura del archivo de esquema.

Si ha abierto un archivo SQL en el espacio de trabajo, también puede usar Convert to SetFN Schema. Se aplican las mismas reglas de conversión en ambos casos.

3. Crearlo directamente en la pantalla

En la pantalla de edición en forma de tabla puede añadir tablas y columnas una a una.

Añadir una tabla

Seleccione Add Table en la parte superior de la pantalla e introduzca la información de la tabla.

Añadir una columna

Seleccione Add y después Add at Top o Add at Bottom para añadir una fila nueva a la lista de columnas. Cada fila corresponde a una columna.

Puede configurar los siguientes elementos.

En el menú System Columns, puede seleccionar columnas habituales para registrar el usuario y la hora, como _user_id, _nick y _created_at.

Copiar y eliminar una columna

Haga clic con el botón derecho en una columna para mostrar el menú contextual.

• Copiar y añadir: seleccione Copy and Add Above, Copy and Add Below, Copy and Add to Top o Copy and Add to Bottom para añadir una columna con las mismas propiedades.
• Delete row: elimina la columna seleccionada.

4. Editar como JSON

Seleccione Editor en la esquina superior derecha para escribir toda la estructura como JSON. El JSON y la tabla utilizan el mismo contenido, por lo que puede alternar entre ambos métodos.

El siguiente ejemplo es un perfil de usuario sencillo que almacena una dirección de correo.

{
  "content-type": "application/setfn-schema",
  "dbType": "sqlite3",
  "data": [
    {
      "table": { "name": "user_profile", "schema": "public" },
      "columns": [
        {
          "name": "email",
          "type": "varchar",
          "len": 255,
          "unique": true,
          "notnull": true
        }
      ],
      "label": "사용자 프로필"
    }
  ]
}

dbType sirve para mantener la compatibilidad con archivos existentes y no determina el motor de ejecución real. El motor final y la información de conexión se definen en el paso de almacenamiento de API Build.

Los permisos de API son tan importantes como los datos

En cada API puede definir si se exige iniciar sesión, el nivel mínimo, los administradores, los equipos y si solo se permiten los datos del propio autor.

• Si una consulta de lista contiene información personal, no utilice permisos públicos.
• En los datos por usuario, indique la columna que identifica al propietario.
• Empiece con permisos de modificación y eliminación más restrictivos que los de consulta.
• Compruebe que el resumen de permisos de la pantalla muestre todas las condiciones previstas.

Después de guardar

Guarde el archivo mediante el botón de la esquina superior izquierda o Ctrl+S. A continuación, compruebe los endpoints y permisos en API Build y realice el despliegue en una base de datos real.

Cuando termine, registre un pequeño dato. Desde el momento en que la estructura creada aparezca en una respuesta de la API, el archivo de esquema dejará de ser un simple documento para convertirse en un servicio en funcionamiento.

Información útil

• Use solo letras inglesas minúsculas, números y guiones bajos (_) en los nombres de tablas y columnas.
• Si hay muchas columnas, use la edición JSON o la importación de SQL.
• Según la política del administrador, puede estar prohibido sobrescribir un esquema que ya contenga datos o permitirse únicamente a administradores y responsables del despliegue.

Siguiente paso

Consulte el motor de almacenamiento y los endpoints en Crear API y desplegar una base de datos, y ejecute su primera API.

Documentos relacionados

• Crear un juego de Gomoku en tiempo real
• Crear API y desplegar una base de datos
• Importar y exportar SQL
• Consultar el ejemplo de frontend