# Brief para agente frontend: implementar autenticacion, farmacia y registro

Implementa en la SPA React la integracion completa con las APIs ya existentes del backend Laravel para:

- busqueda publica de farmacia
- solicitud de registro
- login con sesion y cookies
- consulta de usuario autenticado
- logout

No inventes endpoints nuevos. No uses Bearer tokens. No simules autenticacion con almacenamiento local de tokens.

## Fuente de verdad

Usa estos documentos del backend como referencia:

- `docs/frontend/authentication-frontend-handoff.md`
- `docs/frontend/authentication-api.md`

Si encuentras diferencias entre ambos, prioriza `authentication-api.md` para el contrato y `authentication-frontend-handoff.md` para el flujo de pantallas.

## Objetivo funcional

La SPA debe permitir:

1. Buscar una farmacia por codigo.
2. Guardar el UUID publico de la farmacia encontrada.
3. Enviar una solicitud de registro pendiente usando ese UUID como `pharmacy_id`.
4. Iniciar sesion con username o email usando Laravel Sanctum stateful.
5. Recuperar la sesion al recargar la app mediante `/api/v1/auth/me`.
6. Cerrar sesion correctamente.

## Restricciones tecnicas obligatorias

- Usar cookies y sesion con Laravel Sanctum.
- Configurar el cliente HTTP con `withCredentials: true`.
- Antes de `POST /api/v1/auth/register`, `POST /api/v1/auth/login` y `POST /api/v1/auth/logout`, solicitar `GET /sanctum/csrf-cookie`.
- No guardar tokens en `localStorage`, `sessionStorage` ni cookies manuales.
- No esperar `access_token`, `token` ni `personal_access_token` en respuestas.
- No usar IDs numericos internos de farmacia.
- No mandar campos administrativos o internos en el registro.

## Endpoints disponibles

- `GET /api/v1/public/pharmacies/by-code/{code}`
- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `GET /api/v1/auth/me`
- `POST /api/v1/auth/logout`

## Implementacion esperada

### 1. Cliente HTTP compartido

Crea o adapta un cliente HTTP reutilizable para toda la SPA con:

```ts
import axios from 'axios';

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  withCredentials: true,
  withXSRFToken: true,
  headers: {
    Accept: 'application/json',
  },
});
```

Tambien crea una utilidad para pedir CSRF:

```ts
export async function ensureCsrfCookie() {
  await api.get('/sanctum/csrf-cookie');
}
```

## 2. Estado de autenticacion

Implementa un estado global o store para:

- `user`
- `isAuthenticated`
- `isBootstrappingAuth`
- `login`
- `logout`
- `fetchMe`

Comportamiento:

- Al iniciar la app, llamar `GET /api/v1/auth/me`.
- Si responde `200`, guardar `response.data.data.user`.
- Si responde `401`, dejar `user = null`.

## 3. Pantalla de registro

Implementa el formulario de registro con estos campos:

- `pharmacy_code` solo para la busqueda previa en la UI
- `first_name`
- `last_name`
- `whatsapp`
- `whatsapp_confirmation`
- `phone`
- `identification_number`
- `username`
- `password`
- `password_confirmation`
- `email`
- `city`
- `nickname`
- `terms_accepted`

Flujo requerido:

1. El usuario busca farmacia usando `GET /api/v1/public/pharmacies/by-code/{code}`.
2. Si la API responde bien, guardar `response.data.data.id` como `pharmacy_id`.
3. Mostrar nombre, codigo y ciudad de la farmacia encontrada.
4. Al enviar el formulario, no mandar `pharmacy_code`; mandar `pharmacy_id`.
5. Antes del `POST`, pedir CSRF.
6. Enviar `POST /api/v1/auth/register`.
7. Si responde `201`, mostrar mensaje de exito y no iniciar sesion.

Importante:

- `pharmacy_id` debe ser el UUID publico devuelto por la API.
- Nunca mandar el ID numerico interno.
- `terms_accepted` debe enviarse en `true`.
- `whatsapp_confirmation` y `password_confirmation` deben mantenerse en el formulario.

## 4. Pantalla de login

Implementa formulario con:

- `login`
- `password`
- `remember`

Flujo:

1. Pedir CSRF.
2. Enviar `POST /api/v1/auth/login`.
3. Si responde `200`, llamar `GET /api/v1/auth/me`.
4. Guardar `response.data.data.user`.
5. Redirigir a la pantalla autenticada definida por la app.

Importante:

- `login` acepta username o email.
- Si falla, mostrar el mensaje generico devuelto por backend.
- No intentes distinguir si fallo por usuario, password o estado.

## 5. Logout

Flujo:

1. Pedir CSRF si tu cliente lo requiere antes del `POST`.
2. Enviar `POST /api/v1/auth/logout`.
3. Limpiar el estado local del usuario.
4. Marcar `isAuthenticated = false`.
5. Redirigir segun corresponda.

## 6. Manejo de respuestas y errores

La API responde con este patron:

Exito:

```json
{
  "success": true,
  "message": "Mensaje",
  "data": {}
}
```

Error:

```json
{
  "success": false,
  "message": "Mensaje",
  "errors": {
    "field_name": [
      "Detalle"
    ]
  },
  "error_code": "ERROR_CODE"
}
```

Implementa manejo consistente para:

- `VALIDATION_ERROR`
- `REGISTRATION_DATA_ALREADY_EXISTS`
- `PHARMACY_NOT_FOUND`
- `INVALID_CREDENTIALS`
- `UNAUTHENTICATED`
- `TOO_MANY_REQUESTS`

Reglas:

- Mostrar `message` como feedback general.
- Mostrar `errors[field]` junto a los campos cuando exista.
- Si llega `UNAUTHENTICATED`, limpiar sesion local.
- Si llega `TOO_MANY_REQUESTS`, mostrar mensaje de reintento.

## 7. Datos exactos a leer del backend

### Busqueda de farmacia

Leer:

- `response.data.data.id`
- `response.data.data.code`
- `response.data.data.name`
- `response.data.data.city`

Guardar:

- `response.data.data.id` como `pharmacy_id`

### Login y me

Leer:

- `response.data.data.user.id`
- `response.data.data.user.first_name`
- `response.data.data.user.last_name`
- `response.data.data.user.username`
- `response.data.data.user.email`
- `response.data.data.user.status`
- `response.data.data.user.roles`
- `response.data.data.user.pharmacy`

## 8. Cosas que no debes hacer

- No crear endpoints nuevos.
- No cambiar nombres de campos del backend.
- No asumir doble envoltorio distinto al documentado.
- No usar `pharmacy_code` en el endpoint de registro.
- No mandar `role`, `roles`, `permissions`, `status` ni campos internos.
- No guardar tokens.
- No depender solo de `roles` para seguridad real.

## 9. Entregables esperados del frontend

- Cliente HTTP compartido configurado para Sanctum
- Bootstrap de autenticacion al cargar la SPA
- Pantalla de login funcional
- Pantalla de registro funcional con busqueda de farmacia
- Persistencia correcta del usuario autenticado en estado global
- Logout funcional
- Manejo consistente de errores por campo y mensajes globales

## 10. Criterio de aceptacion

La implementacion frontend se considera correcta si:

1. Puede buscar una farmacia por codigo y usar su UUID publico.
2. Puede enviar una solicitud de registro sin iniciar sesion.
3. Puede iniciar sesion sin usar tokens.
4. Puede recuperar sesion con `/api/v1/auth/me` despues de recargar.
5. Puede cerrar sesion y perder acceso a rutas autenticadas.
6. Maneja correctamente errores `401`, `404`, `422` y `429`.