de codex

docs/hooks-and-api.md

@@ -26,6 +26,16 @@ Regla práctica:
 - Si el hook solo sirve a un módulo, créalo dentro del módulo
 - Si varias piezas del proyecto lo van a consumir, créalo como hook global
 
+## Reglas obligatorias para hooks
+
+- Un hook debe devolver datos con `return [...]`
+- No uses `echo json_encode(...)`
+- No uses `exit`
+- Para leer parámetros, usa `$_REQUEST[...]` o las variables ya inyectadas por el sistema
+- En hooks, usa `CmsApi::get()` o `CocoDB::get()` como primera opción
+- No uses `CocoDB::getInstance()` salvo necesidad real muy excepcional
+- No escribas SQL manual con `prepare()/bind_param()` salvo que no exista forma razonable de resolverlo con `CmsApi` o `CocoDB`
+
 ### Estructura de un Hook
 
 ```php
@@ -79,6 +89,14 @@ CmsApi.hook('/hooks/mimodulo/', {param1: 100, param2: 'texto'}, (data) => {
 });
 ```
 
+**Ejemplo real para hook de módulo:**
+```js
+// Módulo: template/estandar/modulos/buscadorapartados_hjd8s/
+CmsApi.hook('/hooks/buscadorapartados_hjd8s/', { termino: 'vela' }, (data) => {
+  console.log(data);
+});
+```
+
 **Desde otro Hook PHP:**
 ```php
 <?php
@@ -213,6 +231,11 @@ CmsApi.get('tableName', { where: conditions }, function(records) {
 
 Capa de abstracción de BD de bajo nivel usada internamente por CmsApi. Usar directamente desde hooks cuando necesites más control.
 
+Para búsquedas y lecturas habituales, prioriza:
+1. `CmsApi::get()`
+2. `CocoDB::get()`
+3. SQL manual solo si de verdad no hay alternativa razonable
+
 ### `CocoDB::get($table, $where, $order, $limit, $options)`
 
 ```php