# Campos personalizados (Workspace)

> Define campos de metadatos a nivel de organización y su alcance por proyecto desde Workspace.

**Campos personalizados** en la barra lateral de Workspace abre `/workspace/custom-fields`. Los **propietarios** y **administradores** de la organización activa gestionan las definiciones de campos. Los **miembros** y **lectores** ven un mensaje de permiso y no pueden modificar definiciones.

## Tabla de gestión

Encima de la tabla, una **barra de filtros** compartida aloja un campo de **búsqueda** que filtra filas por el título del campo (sin distinguir mayúsculas, lado del servidor). Desde **Agregar filtro** puedes añadir chips **Entidad**, **Tipo** y **Grupo**, cada uno de selección múltiple que escribe un parámetro separado por coma (`type=select_single,radio`); los valores se combinan con OR dentro de un chip y con AND entre la búsqueda y los chips. Un **contador de campos** indica cuántas definiciones coinciden con la consulta activa del total (por ejemplo `1 de 12 campos`). El estado del filtro vive en la URL y cualquier cambio reinicia a la página 1. Cuando hay cualquier búsqueda o filtro activo, las filas de secciones principales se ocultan para mostrar solo las definiciones de campos personalizados que coinciden; limpiar el estado vacío-filtrado quita la búsqueda y todos los parámetros de filtro a la vez.

La tabla muestra todas las definiciones (sistema y personalizadas) con estas columnas:

| Columna  | Significado                                                                                                                                                                                                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NAME     | Título visible del campo                                                                                                                                                                                                      |
| GROUP    | Distintivo: **System** (precargado, estilo neutro) o **Custom** (estilo de acento)                                                                                                                                            |
| TYPE     | Tipo de entrada con el mismo icono que el diálogo de alta (Short text, Select list, Checkbox, …)                                                                                                                              |
| ENTITY   | Objeto destino con el mismo icono que el diálogo de alta (**Test case**, **Test run** o **Defect**)                                                                                                                           |
| PROJECTS | **Todos los proyectos** cuando el campo aplica en todos; avatares apilados con contador cuando está limitado a proyectos concretos; o aviso en cursiva **Sin proyectos** cuando está acotado pero no hay ninguno seleccionado |
| REQUIRED | Punto de acento: relleno si es obligatorio, hueco si es opcional (lectores de pantalla siguen oyendo Sí/No)                                                                                                                   |
| ACTIONS  | Editar (todas las filas); eliminar (solo filas custom)                                                                                                                                                                        |

Los datos se cargan desde la API de la organización al abrir la página. Las filas se ordenan con todos los campos **System** primero y luego los **Custom**; dentro de cada grupo, los títulos van de la A a la Z.

En una pantalla angosta (ancho de teléfono) la tabla se reorganiza como una lista de tarjetas: cada
definición (y cada sección núcleo de defectos) se presenta como su propia tarjeta, mostrando el mismo
grupo, tipo, entidad, proyectos y valor de obligatoriedad, con editar/eliminar siempre disponibles.
Desde el ancho de tablet en adelante, la lista es la tabla descrita arriba.

### Secciones núcleo de defectos

Tres secciones integradas de defectos — **Description**, **Evidence** y **Affected cases** — aparecen como filas fijas con distintivo **Core** cuando la tabla incluye algún campo de defecto (o solas si aún no hay campos personalizados de defecto). No son definiciones de campo personalizado: puedes renombrar el título de la sección para tu organización, pero no eliminarlas, cambiar su tipo ni acotarlas por proyecto.

- **Editar** abre un diálogo solo de título con un selector de idioma EN/ES en el encabezado, junto a **Guardar** y **Restablecer por defecto**. Ambos campos siempre se precargan — con tu override guardado en ese idioma cuando existe, o con el valor por defecto localizado del producto en caso contrario — así que el inglés nunca queda vacío y puedes guardar un renombre solo en español sin pasos adicionales.
- **Restablecer por defecto** siempre está visible y habilitado, exista o no un override; restablecer una sección sin override es una operación inofensiva que no hace nada.
- Los overrides son datos bilingües de la organización, resueltos según quien lee: un lector que ve la app en español ve tu texto en español guardado (o tu texto en inglés, si aún no tradujiste esa sección — nunca el valor por defecto del producto sin tocar mientras exista un override en el otro idioma). Cambiar tu propio idioma de la app actualiza estos encabezados de inmediato, sin recargar.
- Los renombres aplican solo a los **encabezados de sección en el detalle del defecto**. Las etiquetas en otros lugares (por ejemplo el campo **Description** en el diálogo Nuevo defecto) siguen usando el catálogo.

## Agregar un campo personalizado

**Agregar campo personalizado** abre el diálogo de creación. Bajo el título aparece el subtítulo _"Define un campo extra para casos, planes, defectos y demás entidades."_ y el botón de guardar lleva la leyenda **Guardar campo**. Los campos obligatorios se marcan con un asterisco (`*`); los opcionales no llevan marca alguna.

- **Título**, **Entidad** (**Test case**, **Test run** o **Defect**) y **Tipo** — los tres marcados como obligatorios
- Los campos de **Test run** tienen una regla adicional: un campo **Test run** marcado como **Campo obligatorio** DEBE tener un valor por defecto no vacío, tanto al crear como al editar. Guardar un campo de ejecución obligatorio con un valor por defecto vacío se rechaza (`422 validation_failed`, `details.field = "defaultValue"`); los campos de **Test case** y **Defect** conservan el comportamiento actual y pueden quedar obligatorios sin valor por defecto. La regla existe porque la creación de una ejecución nunca debe fallar para un integrador que omite un valor: con un valor por defecto garantizado y no vacío, un valor de ejecución obligatorio omitido siempre se resuelve a partir de él.
- **Habilitar para todos los proyectos** viene activado por defecto; al desactivarlo aparece el selector de **Proyectos** con la nota _"El campo se mostrará solo en los proyectos seleccionados."_
- **Placeholder**, **Valor por defecto** y **Campo obligatorio** dependen del tipo (ver tabla)
- En **Date picker**, **Valor por defecto** usa el calendario integrado de la aplicación (no el selector nativo del navegador); elige un día, **Borrar** u **Hoy**. Los valores se guardan en formato `YYYY-MM-DD`.
- En **Checkbox**, no se muestra placeholder; usa **Estado por defecto** (Marcado/Desmarcado) en lugar de “obligatorio”
- En **Paragraph**, **Valor por defecto** es un área de texto multilínea
- En **Number** y **URL**, **Valor por defecto** se valida al guardar (número finito / URL válida)
- En **Select list (single)**, **Select list (multi)** y **Radio**, usa la pestaña **Valores** para opciones (nombre, clase de icono Font Awesome, color: elige uno predefinido, escribe un valor hexadecimal o selecciona la muestra de color junto al campo hexadecimal para abrir el selector de color). Los campos de sistema incluyen opciones precargadas con iconos Font Awesome y colores semánticos por defecto (por ejemplo, prioridad Alta usa una flecha hacia arriba con color de acento). La pestaña **Valores** muestra el número de opciones definidas junto a su nombre. **Valor por defecto** es un desplegable o multiselección alimentado por esa lista en vivo
- Arrastra el asa (⠿) a la izquierda de cada fila para reordenar. Con teclado: enfoca el asa, pulsa Espacio para tomar la fila, Flecha arriba / abajo para moverla, Espacio para soltar, Escape para cancelar.

### Placeholder y valor por defecto por tipo

| Tipo                 | Placeholder | Valor por defecto                     |
| -------------------- | ----------- | ------------------------------------- |
| Short text           | Texto       | Texto                                 |
| Paragraph            | Texto       | Textarea multilínea                   |
| Number               | Texto       | Numérico (validado)                   |
| URL                  | Texto       | URL (validada)                        |
| Date picker          | Texto       | Selector de fecha integrado           |
| Checkbox             | Oculto      | Marcado / Desmarcado                  |
| Radio                | Texto       | Desplegable de opciones en Valores    |
| Select list (single) | Texto       | Desplegable de opciones en Valores    |
| Select list (multi)  | Texto       | Multiselección de opciones en Valores |
| User picker          | Texto       | Oculto                                |

En tipos con opciones, el control de valor por defecto queda **deshabilitado** hasta que la pestaña **Valores** tenga al menos una opción. Si eliminas una opción que estaba seleccionada como predeterminada, el valor por defecto se borra solo. Al editar, si un valor guardado ya no coincide con ninguna opción, el diálogo lo limpia y muestra un aviso breve en español.

Al guardar se crea una definición **Custom** en tu organización.

## Editar y eliminar

El diálogo de edición usa el mismo encabezado y el mismo botón **Guardar campo** que el de alta, con el subtítulo _"Modifica las propiedades de este campo personalizado."_. **Entidad** y **Tipo** se muestran deshabilitados y sin marca de obligatoriedad; **Título** sí permanece marcado con asterisco.

- **Entidad** y **Tipo** no se pueden cambiar después de crear (protege valores ya guardados).
- Puedes actualizar título, placeholder, valor por defecto, obligatorio y alcance por proyecto. Quitar un proyecto del alcance **no borra** valores ya capturados; vuelven a mostrarse si vuelves a vincular el proyecto.
- Las filas **System** (por ejemplo Priority, Severity, Status) no se pueden eliminar. Puedes renombrar el título, personalizar opciones (renombrar valores precargados, cambiar icono/color, reordenar, agregar opciones propias) y ajustar placeholder, valor por defecto, obligatorio y alcance. Las opciones precargadas no se pueden quitar de la lista; usa **Restablecer valores predeterminados** en el diálogo de edición para deshacer personalizaciones.
- Editar o reordenar opciones en cualquier campo conserva los valores ya guardados en casos de prueba; eliminar una opción sigue quitando los valores que apuntaban a ella.
- **Restablecer valores predeterminados** (solo campos de sistema) abre un diálogo de confirmación. Al confirmar se llama a `POST /api/v1/orgs/{orgUlid}/custom-fields/{fieldUlid}/reset`, que restaura título, placeholder, valor por defecto, obligatorio y nombres/iconos/colores de opciones según el seed, manteniendo los ULID estables. Se eliminan las opciones agregadas por el usuario. El alcance por proyecto (`all_projects` / `project_ulids`) se conserva. Los casos de prueba que apuntaban a opciones eliminadas reciben el valor por defecto del campo si existe, o quedan vacíos.
- Las filas **Custom** se pueden eliminar aunque haya casos, ejecuciones o defectos con valores para ellas. Si el campo tiene valores, el diálogo de eliminación indica cuántos valores y en cuántos proyectos se perderán, y **Eliminar** queda deshabilitado hasta que escribas el nombre del campo tal como aparece. Eliminar borra el campo y todos sus valores de forma permanente; no se puede deshacer. Si prefieres conservar los valores, quita el campo del alcance del proyecto en lugar de eliminarlo.

## Planes

Crear campos personalizados y editar sus definiciones forma parte de los planes **Pro** y **Enterprise**, y de la prueba gratuita. En el plan Free, la pantalla muestra todos los campos en modo de solo lectura: **Agregar campo personalizado** y **Guardar campo** en el diálogo de edición muestran la opción de mejorar el plan en su lugar. Completar valores de campos en casos, ejecuciones, resultados y defectos funciona en todos los planes.

### Si tu organización pasa al plan Free

No se borra nada:

- Cada campo conserva su definición, y sus valores se pueden seguir editando en todas partes.
- Propietarios y administradores pueden seguir abriendo el diálogo de edición de un campo para revisarlo, **eliminar** campos personalizados y usar **Restablecer valores predeterminados** en los campos de sistema.

Lo que se detiene hasta que vuelvas a un plan de pago: crear campos y guardar cambios en la definición de un campo, incluidos los de sistema.

## Relación con casos de prueba y defectos

Las definiciones editadas aquí alimentan etiquetas e iconografía de opciones en superficies de casos y defectos mediante la API.

En **casos de prueba**, los `customFieldValues` embebidos en respuestas GET/list incluyen `optionName`, `optionIcon` y `optionColor` cuando el valor guardado coincide con una opción conocida, de modo que la columna **Pri** del repositorio y los chips de prioridad en detalle renderizan Font Awesome desde los datos persistidos sin pedir definiciones por fila.

En **defectos**, cada organización recibe campos de sistema **Severity** y **Priority** precargados (obligatorios, con opciones por defecto). Puedes renombrar opciones, agregar nuevas (por ejemplo una severidad **Blocker**) y cambiar iconos/colores — los nombres de opción son datos de la organización, no texto fijo del producto. Las mismas definiciones aparecen en el diálogo **Nuevo defecto** (campos de sistema primero), en la pestaña **Propiedades** del detalle (filas de severidad/prioridad antes del responsable y demás filas tipadas) y en el flujo de **captura** durante una ejecución. Los listados y defectos de ejecución exponen severidad/prioridad solo vía `systemFieldValues`; el `GET` de detalle embebe `customFieldValues` completos. Los campos obligatorios de defecto sin valor por defecto bloquean la creación rápida con una sola tecla: **Enter** abre el diálogo completo **Nuevo defecto** con los datos del formulario rápido en lugar de publicar de inmediato.

**Restablecer valores predeterminados** en campos de sistema restaura nombres, iconos y colores del mapa canónico del seed manteniendo ULID estables de opciones. Las etiquetas de tipo ("Short text", "Select list (multi)") y de entidad ("Test case", "Defect") vienen del catálogo i18n del producto.

## Texto de campo bilingüe

Los títulos de campo, los placeholders y los nombres de opción ahora pueden llevar una traducción al español. El título y cada nombre de opción requieren texto en inglés; el texto en inglés de un placeholder es opcional, así que un campo sin placeholder simplemente no tiene texto en ningún idioma. Los once títulos de campo de sistema y los treinta y siete nombres de opción precargados ya incluyen una traducción al español hecha por una persona, así que una organización recién creada nace bilingüe; las filas de sistema sin editar de una organización existente recibieron la misma traducción mediante un backfill.

- La búsqueda de la tabla (el campo de **búsqueda** descrito arriba) encuentra un título guardado en **cualquiera** de los dos idiomas, así que puedes encontrar un campo por su título en español aunque la aplicación esté mostrándose en inglés.
- Restablecer los valores predeterminados de un campo de sistema restaura tanto el texto en inglés como el del seed en español.
- El servidor resuelve el título/placeholder/nombre de opción según el idioma que pida quien llama, y Workspace envía esa solicitud por sí mismo: la tabla de gestión sigue tu selector de idioma activo, así que un título, placeholder o nombre de opción traducido se muestra en español en cuanto cambias la aplicación a español. Los diálogos de alta/edición incluyen un control EN/ES en el encabezado para escribir la traducción al español junto al texto en inglés, y ambos diálogos se abren en tu propio idioma activo por defecto.
- Después de guardar, la app ofrece sincronizar el otro idioma cada vez que cambiaste texto en exactamente uno de los dos —título, placeholder o el nombre de una opción—, incluso si el otro idioma ya tiene texto, porque puede haber quedado desactualizado respecto a lo que acabas de cambiar. Acepta para pasar directamente a ese idioma y seguir editando, o rechaza para dejarlo como estaba; no se te volverá a preguntar por ese mismo guardado.
- Crear un campo requiere un título en inglés. Si escribís solo el título en español e intentás guardar, el diálogo te detiene y ofrece cambiar a inglés para completarlo, o copiar tu texto en español al inglés como punto de partida.
- Las traducciones también se pueden editar mediante los mapas opcionales `titleI18n` / `placeholderI18n` / `nameI18n` de la API (ver la [referencia de la API](https://docs.probara.net/es/developers/api-reference/)).