FarmaFinder/Patentes/MEMORIA_TECNICA.md

# Memoria tecnica FarmaFinder

## 1. Resumen ejecutivo

FarmaFinder es una aplicacion web/PWA para buscar medicamentos en la base oficial de CIMA (AEMPS), localizar farmacias que los comercializan y administrar el catalogo de farmacias y sus relaciones con medicamentos. La aplicacion tambien incluye perfil de usuario con ubicacion guardada, geocodificacion, ordenacion por distancia, estados de apertura de farmacias, notificaciones push para medicamentos y un panel de administracion para altas/bajas/importacion de farmacias.

La base funcional actual esta repartida en cuatro capas principales:

- `frontend/`: interfaz React + Vite, tambien preparada para PWA y empaquetado Capacitor.
- `backend/`: API Express con sesion, autenticacion, persistencia SQLite/PG y notificaciones push.
- `API/`: helpers de importacion y normalizacion de farmacias desde fuentes externas.
- `android/` e `ios/`: shells nativos generados por Capacitor.

## 2. Stack tecnologico

### Frontend

- React 18
- Vite 5
- Leaflet + React Leaflet para el mapa
- Vitest + Testing Library + JSDOM para tests de UI
- PWA con `vite-plugin-pwa`
- Capacitor 6 para envoltorio nativo

### Backend

- Node.js en modo ESM
- Express 4
- SQLite como almacenamiento base local
- PostgreSQL opcional para usuarios y sesiones cuando `PG_URL` esta definido
- Redis para cache de CIMA
- `express-session` para sesion de usuario
- `bcrypt` para hash de contrasenas
- `web-push` para notificaciones push web
- `express-rate-limit` para proteccion de endpoints sensibles

### Integraciones externas

- CIMA API de la AEMPS para busqueda y detalle de medicamentos
- Nominatim / OpenStreetMap para geocodificacion
- OpenStreetMap Overpass u otras fuentes JSON para importacion de farmacias
- Webhooks externos tipo n8n para importacion de farmacias

## 3. Estructura del repositorio

- `frontend/`: SPA principal
- `backend/`: API principal y scripts de mantenimiento
- `API/`: libreria de importacion de farmacias desde fuentes externas
- `scraper/`: utilidades de scraping con Puppeteer
- `android/` y `ios/`: proyectos nativos Capacitor
- `docker-compose.yml`: entorno completo con backend, frontend, Redis y PostgreSQL

## 4. Arquitectura funcional

### Flujo publico

1. El usuario escribe un medicamento en el buscador.
2. El frontend llama a `GET /api/medicines/search`.
3. El backend consulta CIMA, filtra resultados y los cachea en Redis.
4. Al seleccionar un medicamento, el frontend llama a `GET /api/medicines/:id/pharmacies`.
5. El backend devuelve farmacias enlazadas en SQLite/PG con precio, stock, coordenadas y horario.
6. La UI permite ordenar por distancia si el usuario tiene ubicacion guardada o concede geolocalizacion.

### Flujo de administracion

1. Un admin inicia sesion.
2. El panel permite gestionar farmacias, buscar medicamentos en CIMA e importar farmacias externas.
3. El admin enlaza medicamentos a farmacias con precio y stock.
4. Al crear un nuevo enlace de farmacia-medicamento, el backend dispara notificaciones push a usuarios suscritos.

### Flujo de perfil y ubicacion

1. Un usuario autenticado puede editar su perfil.
2. Puede guardar direccion y coordenadas manualmente.
3. Tambien puede geocodificar su direccion via Nominatim o usar la geolocalizacion del navegador.
4. Esa ubicacion se usa en el ordenamiento por distancia en la vista publica.

## 5. Frontend

### Punto de entrada

- `frontend/src/main.jsx` monta `<App />` en `#root`.
- Se inicializa el shell nativo con `initNativeShell()`.

### Componente raiz

`frontend/src/App.jsx` controla tres vistas:

- `public`
- `admin`
- `profile`

Tambien gestiona:

- comprobacion de sesion con `GET /api/auth/check`
- apertura/cierre del modal de login
- cierre de sesion con `POST /api/auth/logout`
- panel de notificaciones guardadas

### Vistas principales

#### PublicView

`frontend/src/views/PublicView.jsx`

Responsabilidades:

- busqueda de medicamentos con debounce
- consulta de farmacias asociadas al medicamento
- mapa de farmacias
- lista de farmacias con precio, stock, horario y notificaciones
- ordenacion por distancia usando ubicacion guardada o geolocalizacion del navegador

Caracteristicas clave:

- Si el usuario tiene coordenadas en el perfil, se priorizan sobre la geolocalizacion del navegador.
- La lista y el mapa usan la misma ordenacion.
- Si no hay coordenadas o el navegador falla, se muestra un mensaje de error contextual.

#### AdminView

`frontend/src/views/AdminView.jsx`

Responsabilidades:

- autenticar acceso al panel
- mostrar tabs de:
  - farmacias
  - medicamentos
  - enlace farmacia-medicamento
- logout de admin

#### ProfileView

`frontend/src/views/ProfileView.jsx`

Responsabilidades:

- editar direccion y coordenadas del usuario
- geocodificar la direccion con `/api/geocode`
- obtener ubicacion actual del dispositivo
- abrir la vista de notificaciones guardadas
- cerrar sesion

## 6. Componentes de UI

### Busqueda y resultados

- `frontend/src/components/SearchBar.jsx`
- `frontend/src/components/MedicineResults.jsx`
- `frontend/src/components/PharmacyList.jsx`
- `frontend/src/components/PharmacyMap.jsx`

#### MedicineResults

- Lista resultados de CIMA.
- Cada card incluye boton de notificaciones para ese medicamento.
- Al pulsar la card se abre el detalle de farmacias asociadas.

#### PharmacyList

- Muestra farmacias enlazadas al medicamento.
- Incluye:
  - distancia al usuario si existe ubicacion
  - estado de apertura calculado a partir de `opening_hours`
  - direccion
  - telefono
  - precio
  - stock
  - boton de notificacion por farmacia cuando el stock esta agotado

#### PharmacyMap

- Muestra farmacias sobre Leaflet.
- Usa coordenadas de cada farmacia para ubicarlas en el mapa.

### Admin components

- `frontend/src/components/admin/PharmacyManagement.jsx`
- `frontend/src/components/admin/MedicineManagement.jsx`
- `frontend/src/components/admin/PharmacyMedicineLink.jsx`
- `frontend/src/components/admin/LoginForm.jsx`

#### PharmacyManagement

- Lista farmacias existentes.
- Permite crear, editar y borrar farmacias.
- Integra importacion por:
  - webhook externo
  - OpenStreetMap / Overpass
  - URL de open data JSON/GeoJSON
- Permite filtrar farmacias por radio geografico.
- Permite geocodificar una ciudad para obtener lat/lon/radio de trabajo.
- Gestiona horario semanal estructurado.

#### MedicineManagement

- Busca medicamentos en CIMA desde el panel admin.
- Solo sirve para exploracion y seleccion previa al enlace.

#### PharmacyMedicineLink

- Permite seleccionar farmacia y medicamento.
- Crea o actualiza el enlace con precio y stock.
- Permite editar y eliminar relaciones ya existentes.

## 7. Utilidades de frontend

### Geolocalizacion

`frontend/src/utils/geo.js`

- `haversineKm()`: calcula distancia entre dos puntos GPS.
- `getUserPosition()`: obtiene ubicacion del navegador con validaciones de contexto seguro.
- `formatDistance()`: da formato a metros/kilometros.

### Horarios

`frontend/src/utils/hours.js`

- `getOpenStatus()`: interpreta el horario semanal y devuelve un estado legible.
- Soporta:
  - abierto
  - cerrado
  - abre a una hora concreta
  - abre el siguiente dia habil
- El formato almacenado es JSON con claves `sun`, `mon`, `tue`, `wed`, `thu`, `fri`, `sat`.

### Notificaciones

`frontend/src/utils/notifications.js`

- comprueba soporte de Push API y Service Worker
- obtiene la VAPID public key del backend
- registra suscripciones push del navegador
- guarda una huella local en `localStorage`
- permite suscripcion global por medicamento o por medicamento + farmacia

### Service worker

`frontend/src/sw.js`

- precache de assets PWA
- muestra notificaciones al recibir eventos `push`
- navega a la URL asociada al click en la notificacion

## 8. Backend

### Arranque

`backend/server.js` es el nucleo de la API. Expone:

- la aplicacion Express
- `initDatabase()`
- la conexion `db`

Si `NODE_ENV !== test`, inicializa DB y levanta el servidor en `PORT` o `3001`.

### Configuracion basica

- CORS con credenciales
- `express.json()`
- session middleware
- rate limiting en:
  - busqueda
  - login
  - registro
  - geocoding

### Persistencia

#### SQLite

Se usa como base local principal:

- farmacias
- relaciones farmacia-medicamento
- subscripciones push
- fallback de usuarios cuando no hay PostgreSQL

#### PostgreSQL opcional

Si existe `PG_URL`, la tabla `users` y el store de sesiones se montan sobre PostgreSQL.

Esto genera una arquitectura mixta:

- SQLite para catalogo/relaciones
- PostgreSQL para usuarios y sesiones, si se configura

### Capa de sesion

- `express-session`
- store SQLite o PostgreSQL segun entorno
- cookie httpOnly con maxAge de 24h
- `trust proxy` configurable con `TRUST_PROXY`

## 9. Modelo de datos

### `pharmacies`

Campos:

- `id`
- `name`
- `address`
- `phone`
- `latitude`
- `longitude`
- `opening_hours`

### `pharmacy_medicines`

Relacion farmacia-medicamento.

Campos:

- `id`
- `pharmacy_id`
- `medicine_nregistro`
- `medicine_name`
- `price`
- `stock`

Restriccion:

- `UNIQUE(pharmacy_id, medicine_nregistro)`

### `users`

Campos actuales:

- `id`
- `username`
- `password_hash`
- `is_admin`
- `address`
- `latitude`
- `longitude`
- `created_at`

### `push_subscriptions`

Subscripciones push globales por medicamento.

Campos:

- `id`
- `medicine_nregistro`
- `medicine_name`
- `endpoint`
- `p256dh`
- `auth`
- `user_id`
- `created_at`

### `push_subscriptions_pharmacy`

Subscripciones push por medicamento y farmacia.

Campos:

- `id`
- `medicine_nregistro`
- `medicine_name`
- `pharmacy_id`
- `endpoint`
- `p256dh`
- `auth`
- `user_id`
- `created_at`

## 10. API backend

### Medicamentos

- `GET /api/medicines/search?q=...`
  - busca en CIMA con cache Redis
  - devuelve una lista normalizada
- `GET /api/medicines/:medicineId`
  - devuelve detalle de un medicamento por `nregistro`
- `GET /api/medicines/:medicineId/pharmacies`
  - devuelve farmacias que tienen ese medicamento

### Farmacias

- `GET /api/pharmacies`
  - lista completa de farmacias

### Autenticacion

- `POST /api/auth/login`
- `POST /api/auth/register`
- `POST /api/auth/logout`
- `GET /api/auth/check`

### Perfil

- `GET /api/users/me`
- `PUT /api/users/me`

### Geocoding

- `GET /api/geocode?q=...`
  - autenticado
  - usa Nominatim
  - devuelve lat/lon y texto de resultado
- `GET /api/admin/geocode?q=...`
  - solo admin
  - ademas calcula radio sugerido

### Admin: farmacias

- `POST /api/admin/pharmacies`
- `PUT /api/admin/pharmacies/:id`
- `DELETE /api/admin/pharmacies/:id`
- `POST /api/admin/pharmacies/import-webhook`
- `POST /api/admin/pharmacies/import-external`

### Admin: medicamentos y relaciones

- `GET /api/admin/medicines`
- `GET /api/admin/pharmacies/:pharmacyId/medicines`
- `POST /api/admin/pharmacy-medicines`
- `PUT /api/admin/pharmacy-medicines/:id`
- `DELETE /api/admin/pharmacy-medicines/:id`

### Notificaciones

- `GET /api/notifications/vapid-public-key`
- `POST /api/notifications/subscribe`
- `DELETE /api/notifications/unsubscribe`
- `GET /api/notifications/mine`
- `DELETE /api/notifications/mine`

## 11. Capa de importacion externa

La carpeta `API/` no expone un servidor HTTP propio, sino funciones reutilizables para importar farmacias desde distintas fuentes.

### `API/index.js`

- `fetchPharmaciesExternal(opts)`
  - `source = 'osm'`
  - `source = 'openData'`
- decide el extractor adecuado segun la fuente

### `API/normalize.js`

- `buildAddressFromOsmTags()`
- `osmElementToPharmacy()`
- normaliza nodos Overpass a un formato comun de farmacia
- parsea horarios OSM si existen

### `API/opening-hours-osm.js`

- parser de un subconjunto de `opening_hours`
- soporta:
  - `24/7`
  - rangos semanales
  - dias multiples
  - `off` / `closed`
  - franjas partidas resumidas

### `backend/farmacias-webhook-import.js`

- importa datos desde un webhook HTTP
- normaliza campos en espanol o ingles
- acepta ubicacion en distintas variantes
- extrae horarios si vienen en formato OSM
- inserta o salta duplicados con estadisticas

## 12. CIMA y cache

`backend/cima-service.js` implementa la integracion con CIMA.

### Busqueda

- consulta `https://cima.aemps.es/cima/rest/medicamentos`
- usa el parametro `nombre`
- normaliza el resultado a campos internos:
  - `id`
  - `nregistro`
  - `name`
  - `active_ingredient`
  - `dosage`
  - `form`
  - `formSimplified`
  - `laboratory`
  - `prescription`
  - `commercialized`
  - `generic`
  - `photos`
  - `docs`

### Detalle

- consulta `GET /medicamento/:nregistro`
- cachea por mas tiempo que la busqueda

### Cache

- Redis guarda resultados de busqueda y detalle
- si CIMA falla, se intenta devolver cache obsoleto si existe

## 13. Notificaciones push

### Estado actual

La app ya soporta notificaciones push web completas.

### Backend

- usa VAPID si `VAPID_PUBLIC_KEY` y `VAPID_PRIVATE_KEY` existen
- si faltan, push queda desactivado con respuesta `503`
- al crear una relacion nueva farmacia-medicamento, se ejecuta `sendPushForMedicine()`
- se deduplican endpoints para evitar notificacion doble global + farmacia
- si el endpoint devuelve `404` o `410`, la suscripcion se limpia

### Frontend

- permite suscripcion global por medicamento
- permite suscripcion por medicamento + farmacia
- el icono de campana refleja el estado local
- la vista `Saved notifications` permite ver y borrar suscripciones guardadas del usuario

## 14. PWA y capa nativa

### PWA

- existe `frontend/src/sw.js`
- hay assets publicos de icono
- la app esta pensada para funcionar como PWA instalable

### Capacitor

- `capacitor.config.json`
- `android/`
- `ios/`

El proyecto esta preparado para empaquetarse como app nativa. La documentacion de `NATIVE.md` indica que no hay una base de codigo separada para Android e iOS; la UI real vive en `frontend/`.

## 15. Scripts y comandos

### Raiz

- `npm run dev`: backend + frontend en paralelo
- `npm run start`: backend + preview frontend
- `npm run install:all`: instala dependencias raiz, backend y frontend
- `npm run build:web`: build de frontend
- `npm run cap:sync`: build web + sync Capacitor

### Backend

- `npm start`
- `npm run dev`
- `npm run seed`
- `npm run create-admin`
- `npm run migrate`
- `npm run import-farmacias`
- `npm test`

### Frontend

- `npm run dev`
- `npm run build`
- `npm run preview`
- `npm run test`

## 16. Docker

`docker-compose.yml` levanta:

- `redis`
- `postgres`
- `backend`
- `frontend`

Puertos:

- frontend: `3000`
- backend: `3001`

Persistencia:

- `backend_data` para la DB SQLite del backend
- `postgres_data` para PostgreSQL

## 17. Variables de entorno

### Backend

- `PORT`
- `SESSION_SECRET`
- `CORS_ORIGIN`
- `FARMACIAS_WEBHOOK_URL`
- `REDIS_HOST`
- `REDIS_PORT`
- `REDIS_PASSWORD`
- `DATABASE_PATH`
- `PG_URL`
- `TRUST_PROXY`
- `VAPID_PUBLIC_KEY`
- `VAPID_PRIVATE_KEY`
- `VAPID_SUBJECT`
- `NODE_ENV`

### App

- en produccion, el frontend debe poder resolver la URL del backend segun despliegue
- en native shell, el manual `NATIVE.md` indica que conviene usar URL absoluta o servir el PWA desplegado

## 18. Seeds, migraciones y administracion

### `backend/seed.js`

- crea tablas basicas
- inserta farmacias y medicamentos de ejemplo
- genera relaciones ficticias usando `EXAMPLE_...`
- actualmente es util para demos, no como dato real

### `backend/create-admin.js`

- crea usuario admin en SQLite o PostgreSQL segun `PG_URL`
- por defecto:
  - usuario: `admin`
  - password: `admin123`

### `backend/migrate.js`

- migracion para el cambio historico de `medicine_id` a `medicine_nregistro`
- la tabla `medicines` antigua se conserva como referencia si existe

## 19. Tests

### Backend

- `backend/__tests__/server.test.js`
  - valida busqueda vacia
  - valida login incorrecto
  - valida proteccion de rutas admin
  - valida creacion de farmacia autenticado
- `backend/__tests__/opening-hours-osm.test.js`
  - cubre parser de horarios OSM

### Frontend

- existe configuracion de Vitest
- hay `frontend/src/App.test.jsx`
- la cobertura visible en el repo parece enfocada a smoke tests y utilidades

## 20. Observaciones tecnicas y limites actuales

1. El backend mezcla SQLite y PostgreSQL segun entorno. Esto funciona, pero introduce dos rutas de persistencia para usuarios y sesiones.
2. Los medicamentos no se guardan localmente como catalogo propio; se consumen desde CIMA en tiempo real y se cachean en Redis.
3. Los enlaces farmacia-medicamento dependen de `nregistro` de CIMA, no de un ID interno de medicamentos.
4. Las notificaciones push son web push; en shells nativos siguen la logica del navegador/PWA, no una integracion FCM/APNs independiente.
5. La importacion de farmacias depende de la calidad de la fuente externa y de la normalizacion de campos.
6. El seed actual contiene datos de ejemplo y relaciones ficticias; no representa datos de produccion.

## 21. Conclusiones

El estado actual de FarmaFinder es el de una plataforma funcional orientada a consulta y administracion de farmacias y medicamentos, con un backend ya bastante consolidado: autentica usuarios, controla roles, persiste relaciones, geocodifica, importa fuentes externas, cachea CIMA y dispara push notifications. La parte de frontend acompana ese backend con un flujo publico de busqueda, un perfil con ubicacion y un panel admin operativo.

Si quieres, el siguiente paso puede ser convertir esta memoria en una version formal de entrega, con estilo academico o empresarial, o bien en un documento mas tecnico con diagramas de arquitectura y secuencia.

## 22. Next steps propuestos

El siguiente paso funcional natural para FarmaFinder seria incorporar el escaneo de la TSI, de forma que el usuario pueda identificar rapidamente su perfil asistencial y, a partir de ahi, cruzar su necesidad con el stock real disponible en farmacias.

### Objetivo

- Capturar la informacion de la tarjeta sanitaria individual mediante escaneo.
- Asociar esa informacion al perfil del usuario de manera segura.
- Recuperar o inferir los medicamentos relevantes para el usuario.
- Contrastar esos medicamentos con el stock de farmacias cercanas.
- Permitir actuar si no hay stock disponible, por ejemplo:
  - reservar una farmacia concreta
  - generar una solicitud de pedido
  - iniciar un flujo de aviso o sustitucion

### Flujo funcional propuesto

1. El usuario abre el escaner de TSI desde la app.
2. La app lee la tarjeta y extrae los identificadores necesarios.
3. El backend valida la informacion y la vincula al usuario autenticado.
4. Se obtiene la lista de medicamentos asociados o derivados del contexto del usuario.
5. El sistema cruza esa lista con:
  - farmacias cercanas
  - stock disponible
  - precio
  - horario
6. Si no existe stock suficiente, la app muestra alternativas y acciones posibles.

### Consideraciones tecnicas

- Esta funcionalidad requiere definir el formato exacto de lectura de la TSI y las fuentes de datos sanitarias a consultar.
- Debe tratarse como una funcionalidad sensible, con control de acceso estricto y minimizacion de datos.
- El escaneo deberia integrarse con el mismo modelo de ubicacion, autenticacion y notificaciones que ya existe.
- La logica de contraste stock/medicamento encaja bien con el modelo actual de `pharmacy_medicines`, pero probablemente exigiria ampliar la capa de negocio para soportar reservas, pedidos o estados intermedios.

### Riesgos y dependencias

- Dependencia de la integracion real con sistemas sanitarios externos.
- Posible necesidad de cumplimiento legal adicional por el tipo de dato tratado.
- Definicion de si el sistema solo informa de disponibilidad o si tambien permite operar pedidos/reservas.
- Necesidad de auditar trazabilidad, consentimiento y control de uso de datos.

### Resultado esperado

Esta ampliacion convertiria FarmaFinder de un buscador de disponibilidad a un asistente operativo de acceso al medicamento, capaz de ayudar al usuario a pasar de la consulta del stock a la accion cuando no exista disponibilidad inmediata.