# Plantilla Workspace — Aduanasoft

Plantilla base para nuevos proyectos del ecosistema **Workspace de Aduanasoft**.
Incluye autenticación SSO con Keycloak/Hub, arquitectura multi-tenant, y un dashboard
funcional listo para extender.

---

## Stack

| Capa | Tecnología |
|---|---|
| Frontend | SvelteKit 5 + Tailwind CSS |
| Backend | FastAPI + SQLAlchemy + PostgreSQL |
| Auth | Keycloak (OpenID Connect) vía Workspace Hub |
| Cache / Queue | Valkey (Redis) + Celery |
| Storage | MinIO (S3-compatible) |
| Contenedores | Docker Compose |

---

## Estructura del proyecto

```
├── backend/
│   ├── api/v1/modules/
│   │   ├── core/          # Auth, usuarios, tenants, permisos, licencias
│   │   └── example/       # Módulo de referencia — copia y renombra
│   ├── core/              # Config, seguridad, DB, middleware
│   └── alembic/           # Migraciones (solo esquema core)
│
├── frontend/
│   ├── src/routes/
│   │   ├── auth/          # Callback OAuth2, SSO, logout
│   │   ├── login/         # Login local (dev) o redirect al workspace
│   │   └── dashboard/     # Shell + rutas stub
│   └── src/lib/
│       ├── server/        # workspace-auth, workspace-apps, api SSR
│       └── stores/        # company, system, workspace-apps
│
└── scripts/
    └── auth-mode.sh       # Alterna entre modo local y workspace
```

---

## Inicio rápido

### 1. Clonar y configurar

```bash
git clone https://git.aduanasoft.com/ADUANASOFT/plantillas-proyectos.git mi-proyecto
cd mi-proyecto
```

Renombrar el proyecto en `.env` y `docker-compose.yml`:
- `CORE_DB_NAME=app_core` → `mi_proyecto_core`
- `name: app` en `docker-compose.yml` → `mi-proyecto`

### 2. Levantar en modo local (sin workspace)

```bash
./scripts/auth-mode.sh local
docker compose up -d
```

Abre `http://localhost:5173` → click **"Entrar como dev"**.

### 3. Conectar al workspace

```bash
./scripts/auth-mode.sh workspace
# Pregunta:
#   URL del workspace    → https://workspace.aduanasoft.com
#   Keycloak Realm       → master
#   Keycloak Client ID   → nombre-del-client
```

> El equipo del Hub debe registrar la app y agregar el redirect URI:
> `http://localhost:5173/auth/callback`

---

## Variables de entorno

El `.env` usa una sola URL base para derivar toda la configuración del workspace:

```env
# Una variable, todo se deriva de aquí
WORKSPACE_URL=https://workspace.aduanasoft.com
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=mi-app-frontend

# Auth local (desarrollo sin workspace)
DEV_LOCAL_AUTH=False   # True = botón "Entrar como dev"
SECRET_KEY=...         # Se genera automáticamente con auth-mode.sh local
```

El `docker-compose.yml` construye automáticamente:
- `HUB_URL` = `${WORKSPACE_URL}`
- `VITE_KEYCLOAK_URL` = `${WORKSPACE_URL}/kcauth`

---

## Agregar un módulo nuevo

### Backend

Copia `backend/api/v1/modules/example/` y renombra:

```
my_module/
├── __init__.py
├── models.py    # SQLAlchemy — hereda TenantScopedMixin + TimestampMixin
├── dto.py       # Pydantic v2 — Request / Response separados
├── service.py   # Lógica de negocio, recibe db + tenant_id + company_id
└── routes.py    # FastAPI router, usa Depends(get_current_user)
```

Registrar en `backend/api/v1/router.py`:

```python
from .modules.my_module.routes import router as my_router
router.include_router(my_router, prefix="/my-module", tags=["my-module"])
```

### Frontend

Crear `frontend/src/routes/dashboard/my-module/+page.svelte` y agregar al sidebar en
`frontend/src/lib/components/sidebar/modules.ts`:

```typescript
{ title: 'Mi módulo', url: '/dashboard/my-module', icon: MyIcon }
```

---

## Script auth-mode

```bash
./scripts/auth-mode.sh status     # Ver modo actual
./scripts/auth-mode.sh local      # Activar login local (dev sin workspace)
./scripts/auth-mode.sh workspace  # Configurar y conectar al workspace
```

Al cambiar de modo el script pregunta si reiniciar los contenedores automáticamente.

---

## Convenciones

- **Commits**: Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`)
- **Branches**: `feature/DESC`, `fix/DESC`
- **Nombres en código**: inglés; comentarios de lógica de negocio en español
- **Backend**: Pydantic v2, async por default, routers por dominio
- **Frontend**: SvelteKit 5 runes (`$state`, `$derived`, `$effect`), Tailwind utility-first