49 lines
4.7 KiB
Markdown
49 lines
4.7 KiB
Markdown
# Compañías, contactos y sedes
|
|
|
|
## Uso
|
|
|
|
Tras iniciar sesión, abrir Compañías. El listado permite buscar por nombre, crear compañías y abrir su ficha. El botón Nueva compañía está en la cabecera, a la derecha, y abre un modal. Dentro de cada ficha se puede editar la compañía y gestionar personas, departamentos y sedes. Las personas se crean y editan en una página propia; los departamentos, las asignaciones y las sedes utilizan modales. Los listados no muestran formularios integrados.
|
|
|
|
- Compañía: nombre obligatorio (100 caracteres como máximo) y estado activo/inactivo.
|
|
- Persona: nombre obligatorio; puesto, email y teléfono opcionales; estado activo/inactivo y clasificación como contacto. Nombre y puesto admiten 100 caracteres. El email se normaliza a minúsculas; el teléfono admite prefijo internacional, espacios, paréntesis, guiones y extensión.
|
|
- Sede: nombre obligatorio, teléfono opcional y dirección opcional, multilínea, de hasta 10.000 caracteres. El teléfono admite prefijo internacional, espacios, paréntesis, guiones y extensión. Una dirección o teléfono omitidos, vacíos o con solo espacios se guardan como ausencia.
|
|
|
|
Las compañías representan empresas clientes atendidas, no la organización que presta soporte ni usuarios con acceso. Todos los usuarios autenticados activos pueden gestionarlas. El administrador inicial conserva su autorización exclusiva sobre la gestión de usuarios.
|
|
|
|
Desactivar una compañía no desactiva sus contactos ni oculta sus sedes. Los estados se editan por separado. No se han añadido eliminación ni un estado de activación a las sedes.
|
|
|
|
## Dominio y persistencia
|
|
|
|
El módulo companies sigue Domain, Application e Infrastructure. Company es raíz de agregado; Person, Department, DepartmentAssignment, AssignmentRevision y Site son entidades internas, cada una con su UniqueID. Los identificadores nuevos son UUID v7; rehydrate y update conservan los persistidos.
|
|
|
|
Name, EmailAddress, PhoneNumber y SiteAddress encapsulan sus invariantes. CalendarDate representa las fechas de los periodos. Maybe representa los campos opcionales. Result expresa errores esperados. Los mappers convierten DTOs a valores de dominio y reconstruyen el agregado desde la persistencia; un registro inconsistente falla sin exponer sus datos.
|
|
|
|
MariaDB conserva companies, company_contacts y company_sites y añade las tablas de departamentos, asignaciones e historial descritas en [Personas y departamentos](personas-y-departamentos.md). Los contactos anteriores conservan sus identificadores y se representan como personas marcadas como contacto. Las claves foráneas relacionan cada contacto y sede con su compañía, con restricción de borrado. Las migraciones explícitas se aplican al arrancar y no borran datos existentes.
|
|
|
|
Las modificaciones bloquean la compañía dentro de una transacción antes de cargar y guardar el agregado. No se permite trasladar una entidad a otra compañía mediante una edición ni editar un contacto o sede usando el identificador de otra compañía.
|
|
|
|
Consultar [Personas y departamentos](personas-y-departamentos.md) para las reglas y nuevas rutas. Las rutas de contactos se mantienen por compatibilidad y gestionan personas con la marca de contacto.
|
|
|
|
## API
|
|
|
|
Todas las rutas requieren sesión válida. Las escrituras requieren el origen configurado y el token CSRF de la sesión.
|
|
|
|
| Método | Ruta | Operación |
|
|
| --- | --- | --- |
|
|
| GET | /api/companies | Listado |
|
|
| GET | /api/companies/:companyId | Ficha con personas, contactos, departamentos, asignaciones y sedes |
|
|
| POST | /api/companies | Crear compañía |
|
|
| POST | /api/companies/:companyId/update | Editar compañía |
|
|
| POST | /api/companies/:companyId/contacts | Crear contacto |
|
|
| POST | /api/companies/:companyId/contacts/:id/update | Editar contacto |
|
|
| POST | /api/companies/:companyId/sites | Crear sede |
|
|
| POST | /api/companies/:companyId/sites/:id/update | Editar sede |
|
|
|
|
Los contratos Zod se declaran en common/dto/request, response y shared. Las mutaciones devuelven la ficha completa para actualizar la caché de TanStack Query. TanStack Table filtra el listado; React Hook Form valida los formularios. Los controles proceden del paquete compartido shadcn/ui.
|
|
|
|
## Validación
|
|
|
|
Las pruebas cubren identidad UUID, invariantes, pertenencia al agregado, actualizaciones, teléfono y dirección opcionales y límites. Las pruebas HTTP usan exclusivamente metis_desk_test y comprueban autenticación, CSRF/origen, persistencia, relaciones y direcciones de 10.000 caracteres Unicode.
|
|
|
|
También se ha probado en el navegador la búsqueda, la creación de compañías y contactos, y la creación y edición de sedes con direcciones multilínea, usando datos ficticios en el entorno de pruebas aislado.
|