# El modelo El modelo genérico `crudl/entity.dk` implementa las operaciones sobre tablas con el patrón de diseño de Devkron, que usa la biblioteca `dbr` (campos de control `sys_pk`, `sys_guid`, `sys_recver`, `sys_dtcreated`, `sys_timestamp`, `sys_deleted`, `sys_lock`; vea [Biblioteca dbr](/es/devkron/2.0/bibliotecas/motor/dbr/)). Para cambiar o ampliar su comportamiento, cree `model.dk` en la carpeta de la entidad. El `model.dk` se incluye **después** de `entity.dk`, así que puede cambiar sus variables, usar sus funciones (`entity.read`, `entity.create`...) y apuntar sus punteros a funciones propias. ## Variables del modelo | Variable | Valor predeterminado | Uso | |---|---|---| | `@table_name` | `""` | Tabla. Vacía = el valor de `_entities_type` | | `@keyfield` | `"sys_pk"` | Campo clave. El parámetro `_key` de la URL tiene prioridad | | `@read_query` | `select * from #<@table_name> where #<@keyfield>=@_entity_id limit 1;` | Consulta de READ | | `@get_sys_pk` | `select sys_pk from #<@table_name> where #<@keyfield>=@_entity_id and ifnull(sys_deleted,0)=0 limit 1;` | Obtiene `sys_pk` con una clave alterna (UPDATE, DELETE) | | `@list_query` | `select * from #<@table_name> where ifnull(sys_deleted,0)=0;` | Consulta de LIST | | `@create_fields`, `@update_fields` | `"*"` | Campos que se guardan (`*` = todos los que lleguen, o lista separada por comas) | | `@create_exclude_fields`, `@update_exclude_fields` | `""` | Campos que **no** se guardan (lista separada por comas) | | `@create_alias_fields`, `@update_alias_fields` | `""` | Pares `alias:campo` separados por comas, para cuando la carga útil usa otros nombres | | `@use_transaction` | `@true` | Transacción en alta, cambio y baja | | `@childs` | registro vacío | Tablas dependientes ([Maestro-detalle](/es/devkron/2.0/marcos/crudl/maestro-detalle.md)) | | `@custom_delete` | nulo | Función de borrado propia (abajo) | En las consultas, `#<...>` es **sustitución de texto** (para nombres de tabla y columna) y `@nombre` es un **parámetro enlazado**: `@table_name` y `@keyfield` se insertan como texto y `@_entity_id` viaja como parámetro. Los parámetros de la URL y, en READ de detalle, los campos del maestro, están disponibles como parámetros (`@estado`, `@texto`...). `_entities_type` y `_key` vienen de la URL; antes de insertarlos como texto, el marco les quita `;`, `'`, `` ` `` y `"` (`entity.safe_id`). Aun así, no construya consultas donde un valor de la petición termine como texto. ## Punteros de función | Puntero | Firma | Debe devolver | |---|---|---| | `@create` | `&db, ¶ms, &data` | La entidad creada | | `@read` | `&db, ¶ms` | La entidad | | `@update` | `&db, ¶ms, &data` | La entidad actualizada | | `@delete` | `&db, ¶ms` | Nada | | `@list` | `&db, ¶ms` | La lista | | `@blank` | `&db, ¶ms` | Un elemento vacío o con valores predeterminados | | `@custom_delete` | `&db, tabla, sys_pk` | Nada | Se cambian con `point`: ```dkl mifuncion_update::&db, ¶ms, &data { // guarde aquí los datos de data en db, con los parámetros de params } point @update to mifuncion_update ``` ### Contrato de las funciones - **Errores**: señálelos con `rise_error(código, mensaje)`. Un código de 400 o más es el estado HTTP; cualquier otro produce 500. - **Transacciones**: si su función abre una, debe confirmarla o deshacerla. El controlador no maneja transacciones. - **Lo que devuelve** no lo interpreta el marco: lo pasa a la vista en `output` y, en REST, lo serializa a JSON. Puede ser la entidad, una estructura con la entidad y datos auxiliares, o una lista; LIST tampoco tiene que devolver una lista. - **Deshabilitar una operación**: ponga el puntero en nulo y la operación responderá **404 `Operación no admitida`**. ### Deshabilitar operaciones: entidad de solo lectura ```dkl #include "dkli.dkh" #! module "Modelo de país (solo lectura)" { @list_query = "select sys_pk, clave, nombre from pais where ifnull(sys_deleted,0)=0 order by nombre;" ref @create = @null ref @update = @null ref @delete = @null } ``` ```text GET /tienda/pais/ → [{"sys_pk":1,"clave":"MEX","nombre":"México"}] POST /tienda/pais/ → 404 {"message":"{404} Operación no admitida[Ln= 161]"} DELETE /tienda/pais/1 → 404 {"message":"{404} Operación no admitida[Ln= 171]"} ``` **En 2.0 use `ref @create = @null`.** La forma de la documentación 1.0, `point @create to @null`, falla con `No existe una función '@null' declarada` porque `point` espera el nombre de una función. ## Ejemplo: un modelo con filtros, valores predeterminados y borrado lógico ```dkl #include "dkli.dkh" #! module "Modelo de cliente" { @list_query = " select sys_pk, codigo, nombre, estado, saldo from cliente where ifnull(sys_deleted,0)=0 and (ifnull(@estado,'')='' or estado=@estado) and (ifnull(@texto,'')='' or codigo=@texto or nombre like concat('%',@texto,'%')) order by nombre limit 250;" // El saldo lo calcula un proceso, no la interfaz @create_exclude_fields = "saldo" @update_exclude_fields = "sys_pk,sys_guid,sys_dtcreated,saldo" Cliente.blank::&db, ¶ms { new r { @"estado": "activo" @"saldo": 0 } return r } borrado_logico::&db, table, sys_pk { new p { @"sys_pk": sys_pk } do dbr.execute(db, "update " + table + " set sys_deleted=1 where sys_pk=@sys_pk;", p) } point @blank to Cliente.blank point @custom_delete to borrado_logico } ``` Resultados reales: ```text GET /tienda/cliente/_new → {"estado":"activo","saldo":0} GET /tienda/cliente/?texto=Ferre → [{"sys_pk":3,"codigo":"CLI-0003","nombre":"Ferretería Norte",...}] POST /tienda/cliente/ {"codigo":"CLI-0009","nombre":"Prueba","saldo":999} → saldo 0.00 (excluido) DELETE /tienda/cliente/5 → 204; la fila queda con sys_deleted=1 ``` Use `ifnull(@parametro,'')` en los filtros: si el parámetro no viene en la URL, llega como nulo. ## Comportamiento de las operaciones predeterminadas ### CREATE 1. Resuelve `@keyfield` (de `_key`) y `@table_name` (de `_entities_type` si está vacía). 2. Copia los datos aplicando `@create_fields` y `@create_alias_fields`. 3. Retira los campos de `@childs` y los de `@create_exclude_fields`. 4. Abre la transacción si `@use_transaction`. 5. Guarda el maestro con `dbr.save` y después los dependientes. 6. Confirma; ante cualquier error deshace y responde 500. 7. Pone el identificador nuevo en `params/_entity_id`, relee con el **puntero** `@read` y lo devuelve. ### READ 1. Resuelve `@table_name` y `@keyfield`. 2. Ejecuta `@read_query` con los parámetros. 3. Sin registro, responde 404 `Elemento no encontrado: ...`. 4. Carga los dependientes de `@childs`. `@read_query` no filtra `sys_deleted`: con borrado lógico, una lectura directa sigue mostrando el registro marcado (comprobado). Si debe ocultarlo, agregue la condición a la consulta. ### UPDATE 1. Resuelve `@table_name` y `@keyfield`; copia los datos con `@update_fields` y `@update_alias_fields`; retira hijos y excluidos. 2. Determina la fila: - Sin `_entity_id` en la URL: toma `sys_pk` o `sys_guid` de la carga útil; sin ninguno, 404 `No se ha indicado la identidad de la entidad`. - Con `@keyfield` igual a `sys_pk` o `sys_guid`: lo usa directamente. - Con otra clave: obtiene `sys_pk` con `@get_sys_pk`; si no la encuentra, 404 `Id no encontrado`. 3. Guarda maestro y dependientes en la transacción. 4. Relee con `@read` y devuelve. Cuando el identificador viene **solo** en la carga útil (`PUT /tienda/cliente/` con `{"sys_pk":1,...}`), el cambio se guarda pero la relectura no tiene `_entity_id` y la respuesta es 404 `Elemento no encontrado`. Mande siempre el identificador en la URL. ### DELETE 1. Resuelve `@table_name` y la clave primaria (directa si `@keyfield` es `sys_pk`; con `@get_sys_pk` si no). 2. En la transacción, invoca `@custom_delete` si existe; si no, **borra la fila físicamente**. 3. Responde 204. Con `@keyfield` = `sys_pk`, borrar un identificador que no existe también responde 204 (no se comprueba que exista). ### LIST Ejecuta `@list_query` con los parámetros y devuelve la lista. La consulta predeterminada oculta los marcados como eliminados. ## Filtros, orden y paginación El modelo genérico ejecuta `@list_query` tal cual: no agrega filtros, orden ni paginación. Todo lo que necesite va en la consulta o en un `@list` propio. Los parámetros de la URL están disponibles como parámetros enlazados, lo que resuelve los filtros sin código (ejemplo de arriba). Para orden dinámico o paginación con total necesita un `@list` propio. Si arma la cláusula de orden con un parámetro de la URL, valídelo contra una lista de columnas permitidas antes de insertarlo como texto. ### Puntos de extensión en la consulta Cuando los filtros son muchos o dependen entre sí, deje marcadores de texto en la consulta y llénelos desde una función. Los **nombres** y fragmentos se insertan con `#<...>`; los **valores** siempre viajan como parámetros: ```dkl @list_query = " select vnt.sys_pk, vnt.referencia, vnt.fecha, cte.nombre as cliente # from venta vnt inner join cliente cte on cte.sys_pk = vnt.icliente # where not ifnull(vnt.sys_deleted,0) # order by vnt.fecha desc, vnt.referencia desc limit #<@max_filas>; " componer_filtros::¶ms { if not(field.exist(params,"estado")) { params<"estado"> : -1 } conditions = "" joins = "" selects = "" if @@(params,"#estado") >= 0 { conditions = conditions + " and vnt.statusadministrativo = @estado" } if trim(@@(params,"$texto")) != "" { conditions = conditions + " and (vnt.referencia like concat('%',@texto,'%') or cte.nombre like concat('%',@texto,'%'))" } @list_query = ftext(@list_query) } ``` `ftext` evalúa los `#<...>` con las variables visibles en ese momento (`conditions`, `joins`, `selects`, `@max_filas`). Llame a `componer_filtros(params)` al inicio de su `@list` propio, antes de ejecutar la consulta, y nunca concatene un valor recibido dentro de la cadena. ## Transacciones que abarcan más que el guardado `@use_transaction` cubre solo el guardado del maestro y sus dependientes. Si la operación incluye más (validaciones contra la base, folios, totales, otros registros), apague esa transacción y abra la suya: ```dkl #include "dkli.dkh" #! module "Modelo de venta con folio" { @table_name = "venta2" @create_exclude_fields = "folio" asignar_folio::&db, &data { new p { @"serie": @@(data,"$serie") } if dbr.num(db, "select count(*) from folio where serie=@serie for update;", p) == 0 { do rise_error(400, "Serie no válida") } do dbr.execute(db, "update folio set ultimo = ultimo + 1 where serie=@serie;", p) return dbr.num(db, "select ultimo from folio where serie=@serie;", p) } mi_create::&db, ¶ms, &data { @use_transaction = @false do dbr.begin(db) if @@(data,"#total") <= 0 { do rise_error(400, "El total debe ser mayor a cero") } folio = asignar_folio(db, data) ref entidad = entity.create(db, params, data) new p { @"folio": folio @"id": @@(entidad,"#sys_pk") } do dbr.execute(db, "update venta2 set folio=@folio where sys_pk=@id;", p) do dbr.commit(db) return entity.read(db, params) exception { if dbr.in_transaction(db) { do dbr.rollback(db) } do rise_error(last_error_code(), last_error()) } } point @create to mi_create } ``` Resultados reales (folio inicial 1042): ```text POST {"serie":"A","icliente":1,"total":100} → {"sys_pk":1,...,"serie":"A","folio":1043,...} POST {"serie":"Z",...} → 400 {"message":"{400} {400} Serie no válida..."} POST {"serie":"A",...,"total":0} → 400; el folio sigue en 1043 (se deshizo todo) ``` Así su función conserva el guardado predeterminado (incluidos los dependientes) y controla el alcance de la transacción. Al reenviar la excepción conserve el código (`last_error_code()`) para no perder la clasificación. El patrón general de "una función por proceso, que abre transacción solo si no hay una abierta" está en la guía [Transacciones bien hechas](/es/devkron/2.0/guias/transacciones.md). ## @custom_delete No sustituye a `@delete` sino al **borrado** que hace la implementación predeterminada: recibe la conexión, el nombre de la tabla y el `sys_pk` ya resuelto, y corre dentro de la transacción. Es el lugar natural del borrado lógico (ejemplo del modelo de cliente, arriba). ## Concurrencia ### Bloqueo optimista: sys_recver La actualización se ejecuta como `UPDATE ... SET sys_recver = sys_recver + 1, ... WHERE sys_recver = AND sys_pk = ...`. **Envíe siempre `sys_recver` en la carga útil** de un cambio: si no coincide con el de la base (otro lo cambió antes), no se afecta ninguna fila y la respuesta es 500 `Save Error. No fue posible actualizar la entidad`. Cada cambio devuelve la entidad con `sys_recver` aumentado en 1, lista para el siguiente cambio. ### Bloqueo pesimista: sys_lock Se implementa con `sys_lock` y `dbr.lock`, `dbr.chklock` y `dbr.unlock` ([Biblioteca dbr](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md)); la tabla debe estar registrada en `sys_catalog`. El marco **no pone ni quita** bloqueos, pero los respeta al guardar: `dbr.save` no modifica una fila con `sys_lock` (ni el maestro ni las filas de `@childs`), aunque la bloquee la misma sesión. Las bajas **no** pasan por esa comprobación: si las necesita protegidas, use `dbr.chklock` en su `@delete` o `@custom_delete`. Un flujo típico: bloquear al entregar el formulario de edición y liberar antes de guardar. El identificador del bloqueo viaja al formulario y vuelve como campo de control: ```dkl #include "dkli.dkh" #! module "Cliente con bloqueo pesimista" { @table_name = "cliente" read_con_bloqueo::&db, ¶ms { ref entidad = entity.read(db, params) if @@(@http_context,"$request/get/_editar") == "1" { idbloqueo = dbr.lock(db, @table_name, @@(entidad,"#sys_pk")) exception { do rise_error(423, "El registro está siendo editado por otro usuario") } entidad<"---idbloqueo">: idbloqueo } return entidad } update_y_liberar::&db, ¶ms, &data { // dbr.save no guarda una fila bloqueada: verifique y libere el bloqueo antes de guardar idbloqueo = @@(params,"#---idbloqueo") if idbloqueo > 0 { do dbr.chklock(db, @table_name, idbloqueo) exception { do rise_error(423, "El bloqueo ya no es válido; vuelva a abrir el registro") } do dbr.unlock(db, idbloqueo) } return entity.update(db, params, data) } point @read to read_con_bloqueo point @update to update_y_liberar } ``` Probado con dos usuarios, cada uno con su sesión del IdP de base de datos: ```text Usuario 1: GET /tienda/clientebloq/1?_editar=1 → 200, "---idbloqueo": 3 Usuario 2: GET /tienda/clientebloq/1?_editar=1 → 423 El registro está siendo editado por otro usuario Usuario 2: PATCH /tienda/clientebloq/1 (sin bloqueo) → 500 Save Error. No fue posible actualizar la entidad Usuario 2: PATCH ... con "---idbloqueo":3 → 423 El bloqueo ya no es válido... Usuario 1: PATCH ... con "---idbloqueo":3 → 200, sys_recver 5, sys_lock vuelve a nulo ``` Diferencias con la documentación 1.0: `dbr.lock` recibe **tres** argumentos (`db, tabla, sys_pk`), toma la sesión de la conexión y, si la fila ya está bloqueada por otra sesión, **lanza un error** en lugar de devolver 0; y `dbr.unlock` recibe `db, id`. El bloqueo pertenece a la **sesión** de base de datos: un nuevo inicio de sesión del mismo usuario cierra sus sesiones anteriores y sus bloqueos dejan de ser suyos. ## Campos de sistema Puede usar como identificador `sys_pk`, `sys_guid` o el campo que indique con `_key`: ```text GET /tienda/cliente/CLI-0001?_key=codigo ``` El marco no filtra los campos de control que lleguen en la carga útil. Si el punto final es accesible desde fuera, o la interfaz reenvía la entidad completa, declare los que no deben tocarse: ```dkl @create_exclude_fields = "sys_lastuser" @update_exclude_fields = "sys_pk,sys_guid,sys_dtcreated,sys_user" ``` `sys_recver` es la excepción: debe llegar para que funcione la concurrencia. ## La relectura después de alta y cambio Las implementaciones predeterminadas releen con el **puntero** `@read`, no con `entity.read`. Si su `@read` devuelve una estructura enriquecida (la entidad más catálogos para el formulario), el alta y el cambio devolverán también esa estructura. Si no lo quiere, use una variable propia: ```dkl read_venta::&db, ¶ms { if not(isset("@read_entity_only")) { @read_entity_only = @false } if @read_entity_only { return entity.read(db,params) } ref entidad = entity.read(db,params) new data { @"entity*": entidad @"catalogos*": cargar_catalogos(db) } return data } ``` y póngala en `@true` al principio de sus funciones de alta y cambio: `@read_entity_only = @true`. ## Funciones del modelo genérico | Función | Qué hace | |---|---| | `entity.create`, `entity.read`, `entity.update`, `entity.delete`, `entity.list`, `entity.blank` | Las implementaciones predeterminadas, para llamarlas desde las suyas | | `entity.child(tabla, join, consulta)` | Describe una tabla dependiente ([Maestro-detalle](/es/devkron/2.0/marcos/crudl/maestro-detalle.md)) | | `entity.safe_id(id)` | Quita `;`, `'`, `` ` `` y `"` de un identificador antes de insertarlo como texto | | `entity.remove_fields(&data, &lista)` | Quita de un registro los campos de una lista | ## Errores típicos | Síntoma | Causa y solución | |---|---| | `No existe una función '@null' declarada` | Use `ref @create = @null` en lugar de `point @create to @null` | | `Save Error. No fue posible actualizar la entidad` | `sys_recver` no coincide (otro guardó antes), falta en la carga útil, o la fila está bloqueada (`sys_lock`) | | `Error de sintaxis ... Símbolo no esperado` en `model.dk` | Una llamada a función partida en varias líneas: en 2.0 los argumentos de una llamada van en una sola línea; ponga las consultas largas en variables (las cadenas sí pueden ocupar varias líneas) | | Un filtro no funciona cuando no se envía | Use `ifnull(@param,'')`: el parámetro ausente llega nulo | | El alta devuelve más que la entidad | Su `@read` devuelve una estructura enriquecida; vea `@read_entity_only` |