157 lines
4.4 KiB
Markdown
157 lines
4.4 KiB
Markdown
# 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
|