# Sistema visual global de MyCode Control y archivado de prestadores

**Fecha:** 2026-07-30
**Repositorios:** `web_mycode` y `api_mycode`
**Estado:** Aprobado

## Objetivo

Todo `admin.mycode.cl` debe usar el mismo lenguaje visual claro de MyCode. El
rediseño no puede limitarse a la lista o al detalle de prestadores. También se
debe permitir retirar un prestador desde su detalle administrativo mediante un
archivado lógico auditable.

## Diagnóstico

El panel base todavía define colores oscuros propios y componentes
rectangulares. Las vistas de prestadores agregaron una segunda capa clara con
tokens MyCode, por lo que actualmente existen dos sistemas visuales dentro del
mismo producto.

El dominio ya comparte clases como `mc-admin-card`, `mc-admin-table`,
`mc-admin-input`, `mc-admin-btn`, `mc-admin-modal` y `mc-admin-state`. La
solución será transformar esas primitivas globales y dejar que los módulos
especializados hereden la misma base.

## Dirección visual

- Fondo general azul muy claro y superficies blancas.
- Azul MyCode como color primario de navegación, foco y acciones principales.
- Coral MyCode como acento de identidad, alertas editoriales y acciones
  destructivas.
- `Plus Jakarta Sans` para interfaz y `Bricolage Grotesque` para títulos.
- Botones píldora, bordes suaves, sombras moderadas y foco accesible.
- Tarjetas con radios amplios y jerarquía clara entre encabezado y contenido.
- Tablas legibles en escritorio y desplazables o adaptadas en pantallas
  estrechas.
- No se agregará modo oscuro en esta entrega.

## Cobertura global

La capa base se aplicará a:

1. Login administrativo.
2. Sidebar, navegación, topbar y contenedor principal.
3. Dashboard, métricas, gráficos, actividad y origen de registros.
4. Usuarios, filtros, edición, perfiles y moderación.
5. Prestadores, verificaciones y catálogos.
6. Registros de errores y sus vistas de detalle.
7. Formularios, tablas, badges, estados vacíos, paginación y modales.
8. Breakpoints de escritorio, tablet y móvil.

Los estilos específicos de prestadores conservarán sólo composición propia;
colores, tipografía, botones y superficies dependerán de la capa global.

## Arquitectura CSS

`mycode-design-tokens.css` seguirá siendo la fuente de identidad. Los tokens
históricos `--admin-*` se convertirán en alias de los tokens `--mc-*` y de las
superficies claras para mantener compatibilidad con todos los módulos.

Los archivos `01.css` a `11.css` continuarán atomizados por responsabilidad.
Se modificarán las primitivas existentes en lugar de añadir una hoja monolítica
de overrides. Los archivos especializados de prestadores y catálogos se
ajustarán sólo donde todavía codifiquen el tema anterior.

La auditoría estricta seguirá exigiendo un máximo de 150 líneas por archivo.

## Archivado administrativo del prestador

### Contrato API

Se agregará:

```text
POST /api/v1/admin/service-providers/{provider}/archive
```

Payload:

```json
{"reason": "Motivo administrativo obligatorio"}
```

La operación:

- requerirá el permiso administrativo existente
  `suspend_service_providers`;
- aceptará prestadores no archivados;
- cambiará su estado a `archived`;
- aplicará `SoftDeletes` al prestador;
- conservará sucursales, contactos, verificaciones y eventos;
- registrará actor, fecha y motivo en `service_provider_status_events`;
- mantendrá la política actual de depuración de archivos almacenados para un
  perfil archivado;
- devolverá el recurso administrativo archivado para confirmar la transición.

El propietario conservará su endpoint actual de eliminación lógica. Su
operación podrá seguir archivando sin motivo administrativo.

### Flujo web

El detalle mostrará `Eliminar prestador` únicamente cuando:

- el registro no esté archivado; y
- la sesión posea `suspend_service_providers`.

La acción abrirá el diálogo de moderación con:

- explicación de que no es un borrado físico;
- campo de motivo obligatorio;
- confirmación explícita;
- botón coral `Archivar prestador`.

Mientras se envía, todos los controles de moderación quedarán deshabilitados
para impedir dobles solicitudes. Un resultado exitoso volverá a renderizar el
detalle como archivado, sin acciones mutables. Un 403, 409 o 422 se mostrará en
el diálogo sin revelar detalles internos.

## Seguridad y datos

- El navegador sólo llamará al bridge del mismo origen.
- El bridge aceptará exclusivamente la acción `archive` y sólo reenviará
  `reason`.
- UUID, permiso y estado se validarán nuevamente en la API.
- No se expondrán JWT, rutas de archivos ni documentos privados.
- No se realizará borrado físico de filas relacionadas.

## Pruebas y aceptación

- Contrato API del archivado, permiso, motivo obligatorio, soft delete y
  evento auditable.
- Registro archivado disponible en la consulta administrativa con `withTrashed`.
- Bridge allowlisted y payload exacto.
- Acción visible según estado y permiso.
- Diálogo, confirmación, doble envío y respuesta tardía.
- Contratos visuales globales para shell, login, tarjetas, tablas, inputs,
  botones, modales, módulos y responsive.
- `php artisan test` en ambos repositorios.
- `npm run test:provider` y suites JS administrativas.
- `npm run production`.
- `php artisan architecture:audit --strict`.
- `git diff --check`.

## Fuera de alcance

- Modo oscuro.
- Borrado físico de prestadores.
- Rediseño de la autenticación clásica.
- Cambio de los tipos o niveles de verificación; se tratará como una decisión
  funcional independiente.