metis-desk/docs/estructura-web-por-entidades-y-operaciones.md

Estructura web por entidades y operaciones

El código de navegador de cada módulo se organiza primero por entidad o área funcional y, dentro de ella, por las operaciones existentes. Esta estructura se aplica a core, identity, assets, resources y companies. No modifica la composición del servidor ni los contratos HTTP.

Ubicación de las responsabilidades

Ejemplo real de tickets en modules/companies/src/web/:

tickets/
  create/
    ui/
      intervention-ticket-create-dialog.tsx
      ticket-quick-editor.tsx
      ticket-quick-forms.tsx
      ticket-target-create-dialog.tsx
      index.ts
    index.ts
  detail/
    ui/
      ticket-detail.tsx
      ticket-detail-dialog.tsx
      index.ts
    index.ts
  list/
    ui/
      tickets-page.tsx
      index.ts
    index.ts
  shared/
    api/
      ticket-api.ts
      index.ts
    ui/
      ticket-form.tsx
      ticket-editor-dialog.tsx
      ticket-targets.tsx
      ticket-classification-fields.tsx
      ticket-feedback.tsx
      ticket-help.tsx
      index.ts
    tickets.test.tsx
    index.ts
  index.ts

El árbol muestra las ubicaciones, no implica exportar todos los ficheros. Los índices declaran únicamente los símbolos que sus consumidores necesitan. Las operaciones sin una responsabilidad propia no reciben directorios vacíos: por ejemplo, el editor común de alta y edición permanece en tickets/shared/ui/.

• ui: componentes y formularios existentes. Un componente principal por fichero, sin nuevas subdivisiones de JSX trivial.
• api: funciones de acceso HTTP y claves de consultas existentes.
• controllers y hooks: responsabilidades React ya separadas en el código original, como catalog/shared/controllers/use-catalog-save.ts y work-environments/detail/hooks/use-environment-queries.ts.
• types y helpers: contratos y cálculos existentes, próximos a sus consumidores.
• <entity>/shared: código utilizado por varias operaciones de la misma entidad y pruebas que cubren conjuntamente esas operaciones.
• web/shared: recursos de varias entidades del módulo, incluidas traducciones y componentes comunes. No sustituye a common, que sigue conteniendo contratos y schemas compartidos con el servidor.

No se han creado controllers, hooks, schemas ni adapters para trasladar lógica desde los componentes. Esa auditoría queda para una tarea posterior. Las props y los schemas que ya pertenecían a sus ficheros mantienen su contrato y ubicación relativa a la responsabilidad.

Entidades y ámbitos compartidos

Los listados, detalles, altas específicas e historiales se sitúan en list, detail, create y history. Las operaciones particulares conservan nombres explícitos, como change-logo, change, start, update o end.

Áreas antes agrupadas por una categoría amplia quedan identificadas por sus entidades: mailboxes, mailbox-uses y mail-configurations; work-profiles y work-environments; processes y process-templates; interventions e intervention-templates. Los componentes de dashboard y workspace siguen el mismo criterio funcional.

Los formularios y diálogos que sirven tanto para crear como para editar se mantienen en el shared/ui de su entidad. No se duplican ni se introducen wrappers de alta y edición sin comportamiento propio. Un diálogo de alta de tickets pertenece a tickets/create, aunque se abra desde una intervención; el consumidor no determina la identidad del componente.

Los clientes HTTP existentes que abarcan varias entidades permanecen en el ámbito compartido adecuado: por ejemplo, identity/shared/api/identity-api.ts y assets/shared/api/inventory-api.ts. Separar sus métodos o auditar su lógica excede esta reorganización. Las funciones, firmas y claves de consultas no cambian.

Índices y dependencias

Cada nivel con un contrato consumido desde otra unidad dispone de un index.ts que enumera sus exportaciones. No se crean índices vacíos, exportaciones *, exportaciones de tests ni índices para detalles privados utilizados exclusivamente dentro de su propio directorio. Los tipos se reexportan mediante export type.

Los consumidores utilizan el índice de la unidad correspondiente cuando ello no añade ciclos. Los imports entre ficheros de la misma unidad permanecen directos. También se conservan imports directos específicos cuando un índice agregado añadiría un ciclo de dependencias, por ejemplo en flujos de altas anidadas. No se amplía la API pública para resolver esas dependencias internas.

web/index.ts mantiene los símbolos públicos originales de @metis/<module>/client y compone los índices internos. Las aplicaciones y otros módulos continúan utilizando ese contrato público. Los antiguos caminos internos no tienen reexports de compatibilidad.

Pruebas y mantenimiento

Las pruebas existentes acompañan al ámbito que comprueban. Los scripts de cada paquete referencian sus nuevas ubicaciones; los imports, traducciones y enlaces de documentación se actualizan junto con los movimientos.

Para futuros cambios, consultar también componentes de interfaz, inventario de modales, patrón de listados y pruebas. No trasladar una responsabilidad compartida a una operación concreta ni extraer lógica nueva únicamente para reproducir un árbol de directorios.