# Entidades maestro-detalle Muchas entidades no son una sola tabla: una factura, un pedido o un movimiento de almacén tienen un encabezado y partidas que se crean, cambian y eliminan juntos. El modelo genérico lo resuelve de forma declarativa: usted describe las tablas dependientes y el marco las guarda, relaciona y borra con el maestro, en una sola transacción. ## Declaración En el `model.dk` de la entidad, agregue a `@childs` un miembro por tabla dependiente: ```dkl @qry_partidas = "select * from factura_detalle where ifactura = @sys_pk and ifnull(sys_deleted,0)=0 order by renglon;" ref h = entity.child("factura_detalle", "ifactura", @qry_partidas) @childs<"partidas*"> : h ``` ### entity.child ```dkl entity.child::table, join, select_query ``` | Argumento | Significado | |---|---| | `table` | Tabla dependiente | | `join` | Campo de la tabla dependiente que apunta al maestro (clave foránea) | | `select_query` | Consulta que obtiene las filas de un maestro | El nombre del miembro (`partidas`) es el nombre con el que viajan las filas en el JSON, de entrada y de salida. La clave de las filas dependientes es siempre `sys_pk`. Puede declarar varias tablas dependientes; cada una se procesa por separado. ## Forma de los datos ```json { "sys_pk": 1, "sys_recver": 1, "folio": "A-1043", "icliente": 1, "total": 1450.00, "partidas": [ { "sys_pk": 2, "sys_recver": 0, "ifactura": 1, "renglon": 2, "descripcion": "Lápiz", "cantidad": 10, "precio": 25.00, "importe": 250.00 }, { "sys_pk": 3, "sys_recver": 0, "ifactura": 1, "renglon": 3, "descripcion": "Goma", "cantidad": 1, "precio": 1200.00, "importe": 1200.00 } ] } ``` Es la estructura que devuelve una lectura y la que se envía en alta o cambio: - Fila **nueva**: sin `sys_pk` o con `sys_pk` en 0. - Fila que se **conserva**: con su `sys_pk`. - Fila que se **elimina**: se omite del arreglo. No hace falta mandar la clave foránea al maestro: si falta, el marco la pone. ## Comportamiento ### Lectura Después de leer el maestro, se ejecuta la consulta de cada hijo usando **el maestro completo como parámetros**; por eso la consulta puede usar `@sys_pk` (y cualquier otro campo del encabezado). El resultado se agrega al maestro con el nombre del miembro. ### Alta y cambio 1. Los campos de los hijos se **retiran** del maestro (no se intenta guardarlos como columnas). 2. Se guarda el maestro y se obtiene su `sys_pk`. 3. Por cada hijo que **venga** en la carga útil: - Se consultan las filas que existen en la base para ese maestro. - **Las que existen y no vienen en el arreglo se eliminan** (borrado físico). - Cada fila del arreglo se guarda con `dbr.save`: con `sys_pk` mayor que 0 se actualiza; si no, se inserta. - Si la fila no trae la clave foránea, se le pone la del maestro. 4. Se confirma la transacción. Si un hijo declarado **no viene** en la carga útil, no se toca; un arreglo **vacío** elimina todas sus filas. ### Baja La baja del maestro **no elimina** los dependientes. Hágalo con integridad referencial en cascada en la base o con un `@custom_delete` (ejemplo abajo). ## Transacción Con `@use_transaction` en `@true` (predeterminado), el maestro y todos los hijos se guardan en una sola transacción: si algo falla, se deshace todo. No lo apague en entidades con dependientes, salvo que abra usted la transacción ([El modelo](/es/devkron/2.0/marcos/crudl/modelo.md#transacciones-que-abarcan-más-que-el-guardado)). ## Elegir y renombrar campos de cada hijo El objeto de `entity.child` admite dos miembros más: | Miembro | Significado | |---|---| | `fields` | Campos que se guardan de cada fila, separados por comas. Predeterminado `*` (todos) | | `alias` | Pares `alias:campo` separados por comas, cuando la interfaz usa otros nombres | Úselos cuando la consulta del detalle trae columnas calculadas o de otras tablas (descripción del producto, SKU) que no existen en la tabla dependiente: ```dkl ref h = entity.child("factura_detalle", "ifactura", @qry_partidas) h<"fields"> : "sys_pk,sys_recver,renglon,descripcion,cantidad,precio,importe" @childs<"partidas*"> : h ``` **No incluya el campo de unión en `fields` si las filas no lo traen.** Comprobado en 2.0: con `fields` = `"sys_pk,sys_recver,ifactura,..."` y filas sin `ifactura`, la copia de campos crea `ifactura` vacío y el marco ya no pone la clave del maestro; la partida se guarda con `ifactura` en NULL y no aparece en la lectura. Sin `ifactura` en `fields`, el marco la asigna correctamente. ### Declaración directa `entity.child` es una comodidad: el hijo es un registro corriente que puede escribir completo: ```dkl using @childs { member "partidas" { @"table": "factura_detalle" @"joinfield": "ifactura" @"keyfield": "sys_pk" @"select_query": @qry_partidas @"fields": "sys_pk,sys_recver,renglon,descripcion,cantidad,precio,importe" } } ``` Esos cinco miembros (más `alias`) son los que consulta el marco; `keyfield` es siempre `sys_pk`. ### Campos distintos en alta y cambio Conviene declarar el hijo dentro de cada operación, porque la lista suele variar: en el **alta**, omita `sys_pk` y `sys_recver` de `fields` (si la interfaz reenvía identificadores de otro documento, como al copiar una cotización a un pedido, se actualizarían filas ajenas); en el **cambio**, inclúyalos: distinguen las filas que se conservan y hacen funcionar la concurrencia del detalle. ## Detalle recibido como texto JSON Un formulario HTML no envía arreglos de objetos. El patrón es serializar el detalle en un campo oculto y deserializarlo en el modelo: ```html ``` ```dkl mi_create::&db, ¶ms, &data { ref datos = record.copy(data,"*") // del formulario llega como texto (tipo 1); de un cliente REST, ya como lista if field.typeof(data,"partidas") == 1 { datos<"partidas*"> : from.json(@@(data,"partidas")) } return entity.create(db, params, datos) } point @create to mi_create ``` Tras la sustitución, el miembro es una lista de registros y el marco la procesa normalmente. Comprobado: la misma función guarda la partida tanto desde un formulario urlencoded con `partidas=[{...}]` como desde un POST JSON con el arreglo. ## Ejemplo completo Una factura con partidas. **`entidades/factura/model.dk`**: ```dkl #include "dkli.dkh" #! module "Modelo de factura" { @table_name = "factura" @read_query = " select f.*, c.nombre as cliente_nombre from factura f left join cliente c on c.sys_pk = f.icliente where f.#<@keyfield> = @_entity_id limit 1;" @list_query = " select f.sys_pk, f.folio, f.fecha, f.total, c.nombre as cliente_nombre from factura f left join cliente c on c.sys_pk = f.icliente where ifnull(f.sys_deleted,0)=0 and (ifnull(@desde,'')='' or f.fecha >= @desde) order by f.fecha desc, f.folio desc limit 500;" // Columna calculada que no existe en la tabla @create_exclude_fields = "cliente_nombre" @update_exclude_fields = "cliente_nombre" @qry_partidas = "select * from factura_detalle where ifactura = @sys_pk and ifnull(sys_deleted,0)=0 order by renglon;" ref h = entity.child("factura_detalle", "ifactura", @qry_partidas) h<"fields"> : "sys_pk,sys_recver,renglon,descripcion,cantidad,precio,importe" @childs<"partidas*"> : h // Baja lógica del encabezado y del detalle baja_factura::&db, table, sys_pk { new p { @"sys_pk": sys_pk } do dbr.execute(db, "update factura_detalle set sys_deleted=1 where ifactura=@sys_pk;", p) do dbr.execute(db, "update factura set sys_deleted=1 where sys_pk=@sys_pk;", p) } point @custom_delete to baja_factura } ``` **Alta** (respuesta real, resumida): ```text POST /tienda/factura/ Content-Type: application/json {"folio":"A-1043","fecha":"2026-10-26","icliente":1,"total":1200, "partidas":[{"renglon":1,"descripcion":"Cuaderno","cantidad":2,"precio":600,"importe":1200}]} ``` ```json {"sys_pk":1,"sys_recver":0,"folio":"A-1043","fecha":"2026-10-26T06:00:00Z","icliente":1,"total":1200.00, "cliente_nombre":"Abarrotes López", "partidas":[{"sys_pk":1,"sys_recver":0,"ifactura":1,"renglon":1,"descripcion":"Cuaderno","cantidad":2.0000,"precio":600.00,"importe":1200.00}]} ``` **Cambio que agrega dos partidas y elimina la original** (no se envía la partida 1): ```text PATCH /tienda/factura/1 {"sys_recver":0,"total":1450,"partidas":[ {"renglon":2,"descripcion":"Lápiz","cantidad":10,"precio":25,"importe":250}, {"renglon":3,"descripcion":"Goma","cantidad":1,"precio":1200,"importe":1200}]} ``` La respuesta trae `sys_recver` 1 y las partidas 2 y 3; la 1 se borró. Un cambio posterior **sin** `partidas` (`{"sys_recver":1,"total":1450}`) deja intactas las dos partidas. **Baja**: `DELETE /tienda/factura/1` responde 204 y deja `sys_deleted=1` en la factura y en sus partidas; la lista ya no la muestra. ## Errores típicos | Síntoma | Causa y solución | |---|---| | Las partidas se guardan pero no aparecen al leer | Quedaron con la clave foránea en NULL: quite el campo de unión de `fields`, o mándelo en cada fila | | `Error de sintaxis ... Símbolo no esperado` en la línea de `entity.child` | La llamada está partida en varias líneas; ponga la consulta en una variable y la llamada en una línea | | Se borraron partidas que no debían | Un arreglo enviado incompleto elimina las filas que faltan; para no tocar el detalle, no envíe el miembro | | `Unknown column 'descripcion'` al guardar | La consulta del detalle trae columnas que no son de la tabla y la interfaz las reenvía: limite `fields` |