# Family Kiosk — Backend API (Slim + MySQL + Docker)

API REST para la app familiar en modo kiosko. Este README cubre **instalación y arranque** del backend usando **Docker Compose**.

> Estado probado: **PHP 8.2 + Apache**, **MySQL 8.0**, **Composer 2**, **Docker Compose v2**.

---

## Requisitos

* Docker y Docker Compose v2 (`docker compose version`)
* (Opcional) Make, curl, jq para utilidades

---

## Estructura del repo

```
family-kiosk/
├─ api/
│  ├─ Dockerfile
│  ├─ composer.json
│  ├─ .env.example  ← duplica como .env
│  ├─ public/
│  │  ├─ .htaccess
│  │  └─ index.php
│  ├─ config/settings.php
│  ├─ src/routes.php
│  └─ migrations/
│     └─ 001_init.sql  ← crea tablas iniciales
└─ docker-compose.yml   ← orquesta API + DB
```

> **Nota**: Este README asume que `docker-compose.yml` está en la **raíz** del proyecto y que los paths apuntan a `./api`.

---

## Variables de entorno

Copia el ejemplo y ajusta si fuera necesario:

```bash
cp api/.env.example api/.env
```

Valores por defecto (puedes dejarlos al principio):

```
APP_ENV=dev
APP_DEBUG=1
DB_HOST=db
DB_NAME=family_kiosk
DB_USER=app
DB_PASS=app
```

---

## Arranque rápido (Docker)

1. **Build + up**

```bash
docker compose up -d --build
```

* Levanta `db` (MySQL 8) y `api` (PHP 8.2 Apache).
* Aplica migraciones iniciales automáticamente desde `api/migrations/`.

2. **Instalar dependencias PHP (si el volumen pisa vendor/)**

```bash
docker compose exec api composer install --prefer-dist
```

3. **Probar salud**

```bash
curl -i http://localhost:8080/health   # debe responder 204 No Content
```

(Comprobación opcional)

```bash
curl -s http://localhost:8080/version | jq
```

---

## Comandos útiles

**Reconstruir la imagen de la API** (si cambiaste el Dockerfile):

```bash
docker compose build --no-cache api
```

**Logs en vivo**:

```bash
docker compose logs -f api
```

**Entrar al contenedor**:

```bash
docker compose exec api bash
```

**Parar y borrar contenedores**:

```bash
docker compose down
```

---

## Migrations y datos iniciales

* Las migraciones SQL en `api/migrations/` se ejecutan automáticamente al crear el contenedor de MySQL.
* Si necesitas **recrear** la base desde cero:

  1. `docker compose down -v` (borra volumen `db_data`)
  2. `docker compose up -d --build`

**Comprobar que la tabla `settings` tiene el registro id=1** (requerido por la app):

```sql
SELECT * FROM settings WHERE id=1;
```

Si no existe, crea uno mínimo:

```sql
INSERT INTO settings (id, kiosk_exit_password_hash)
VALUES (1, '$2y$10$exampleexampleexampleexampleexampleex');
```

> Sustituye el hash por uno real (ver sección Seguridad).

---

## Desarrollo sin Docker (opcional)

Si prefieres arrancar el servidor embebido de PHP para debug rápido:

```bash
cd api
composer install
cp .env.example .env
php -S 0.0.0.0:8000 -t public
```

Base de datos: apunta tu `.env` a una instancia local de MySQL o a la del contenedor si lo tienes levantado.

---

## Seguridad (resumen)

* **JWT_SECRET**: cuando añadas auth, configura un secreto robusto en `.env`.
* **Password kiosko**: guarda solo el **hash** en `settings.kiosk_exit_password_hash` (usa `password_hash()` en PHP o genera uno por CLI).
* Abre el puerto 8080 solo en entornos seguros; en producción pon **Nginx** o un proxy delante con HTTPS.

---

## Endpoints de verificación (dev)

* `GET /health` → 204 No Content
* `GET /version` → `{ api: "family-kiosk", version: "0.1.0" }`

(Se irán añadiendo endpoints: `/auth/login`, `/people`, `/tasks`, `/weather/now`, `/calendar/events`, `/dashboard`, etc.)

---

## Problemas comunes

**1) `version` obsoleto en Compose**

> `the attribute 'version' is obsolete`

* Solución: elimina la clave `version:` del `docker-compose.yml`.

**2) `env file .../api/api/.env not found`**

* Ocurre si ejecutas `docker compose` desde `api/` y el compose espera `./api/.env`.
* Solución A (recomendada): mover/usar `docker-compose.yml` en la **raíz** y ejecutar desde raíz.
* Solución B: si usas compose dentro de `api/`, ajusta rutas a `./.env` y `./migrations`.

**3) Composer falla por `zip`, `unzip` o `git`**

* La imagen debe instalar `git unzip libzip-dev` y la extensión `zip` de PHP. Ya está contemplado en el `Dockerfile`.

**4) Error 500 tras levantar**

* Causa típica: `vendor/` vacío por el volumen.
* Solución: `docker compose exec api composer install`.

**5) MySQL tarda en estar listo**

* Hay **healthcheck**; si aún así falla la conexión al principio, espera unos segundos o reinicia el servicio `api`.

---

## Próximos pasos

1. Añadir **JWT** y `/auth/login`.
2. CRUDs de **people**, **tasks**, **periods**.
3. Integración **Weather** (Open‑Meteo) y **Google Calendar API** (OAuth) para `/calendar/events`.
4. Endpoint agregado `/dashboard` para servir todo junto al frontend.

---

## Licencia

Privado. Uso interno para el proyecto familiar.