# ESPECIFICACIONES DEL PROYECTO: Tienda DJGST

## 1. Descripción General
Este proyecto es una plataforma de comercio electrónico (e-commerce) desarrollada para "Mayorista del Norte". Permite a los clientes navegar por un catálogo de productos, gestionarlos en un carrito de compras y realizar pedidos. También incluye una API REST para integración con otros servicios.

## 2. Stack Tecnológico
* **Lenguaje:** Python 3.x
* **Framework Web:** Django 3.2
* **API:** Django REST Framework
* **Base de Datos:** PostgreSQL
* **Frontend:** Django Templates (HTML, CSS, JavaScript)
* **Gestión de dependencias:** `requirements.txt`

## 3. Arquitectura de Aplicaciones (Django Apps)
El proyecto está organizado en las siguientes aplicaciones dentro de la carpeta `apps/`:

* **`ppal` (Página Principal):** Gestiona la página de inicio, la página de "Nosotros", la página de "Contacto" y el manejo de errores (404).
* **`tienda`:** Gestiona el catálogo de productos, categorías y marcas.
* **`cliente`:** Gestiona la autenticación y la información de los usuarios/clientes.
* **`carrito`:** Gestiona la lógica del carrito de compras (añadir, eliminar, visualizar productos seleccionados).
* **`pedido`:** Gestiona la creación, el seguimiento y el detalle de los pedidos realizados.
* **`api`:** Provee endpoints REST para la interacción con el catálogo y otros recursos.

## 4. Modelo de Datos Principal
* **Catálogo:**
    * `Categoria`: Nombre y slug para filtrado.
    * `Marca`: Nombre y slug para filtrado.
    * `Producto`: Nombre, slug, descripción, imagen, precio, disponibilidad, marca y categoría.
* **Ventas:**
    * `Pedido`: Relacionado con un usuario, contiene fecha de creación y estado (Creado, Procesando, Completado).
    * `PedidoItem`: Detalle de cada producto en un pedido (producto, precio al momento de la compra, cantidad).

## 5. Funcionalidades Implementadas
* [x] Catálogo de productos con filtros por categoría y marca.
* [x] Gestión de carrito de compras.
* [x] Sistema de autenticación de usuarios.
* [x] Proceso de creación de pedidos.
* [x] API REST para productos.

## 6. Roadmap / Tareas Pendientes
* [ ] Generación de facturas en PDF.
* [ ] Implementación de envío de correos electrónicos de confirmación.
* [x] Mejora en la interfaz de usuario (CSS/Diseño).
* [ ] Implementación de búsqueda avanzada con paginación.
* [ ] Refactorización de la gestión de usuarios y seguridad de claves.
* [ ] Optimización de la carga de imágenes.

## 7. Configuración del Entorno
* **Base de datos:** PostgreSQL.
* **Archivos estáticos/media:** Configurados para servir imágenes de productos y estilos.
* **Idioma:** Español (es-ar).

## 8. Multi-cliente (Personalización sin tocar el repositorio)

### Modelo
Cada cliente es una **copia completa del repositorio** en el servidor (Opción A).
Todo lo específico de un cliente vive **fuera del control de versiones** (carpeta `site/` y `.env`),
de modo que un `git pull` jamás pisa la personalización ni la configuración de base de datos.

### Estructura por cliente
```
/var/www/app_<cliente>/        ← git clone del repo (BASE_DIR)
├── .env                       ← gitignored: DB, SECRET_KEY, SITE_NAME, colores...
└── site/                      ← gitignored: personalización del cliente
    ├── templates/ppal/ppal.html   ← home propia (contenido y estructura)
    ├── templates/tienda/          ← otros templates a sobreescribir si hace falta
    └── static/
        ├── css/tema.css           ← colores del cliente (sobreescribe --theme-*)
        └── media/logo.png         ← logo (y favicon.ico) del cliente
```

### Variables de `.env` (por cliente)
| Variable | Descripción |
|---|---|
| `SITE_DIR` | Ruta absoluta a la carpeta `site/` del cliente (vacío = repo genérico) |
| `SITE_NAME` | Nombre del sitio (título, home, footer) |
| `DEVELOPED_BY` | Texto "Desarrollado por" del footer |
| `DB_ENGINE` / `DB_*` | Configuración de base de datos propia de cada cliente |

### Cómo se aplica la personalización
1. **Plantillas:** `settings.py` agrega `SITE_DIR/templates` con precedencia al directorio de templates.
   Si el cliente tiene `site/templates/ppal/ppal.html`, se usa en lugar del del repo.
2. **Colores:** el tema del repo usa CSS variables (`--theme-primario`, `--theme-acento`, ...).
   `base.html` carga `css/tema.css` después de `style.css`/`usi.css`; el cliente redefine
   las variables en su `site/static/css/tema.css`.
3. **Logo/favicon:** se referencian como `media/logo.png` y `media/favicon.ico`.
   `STATICFILES_DIRS` da precedencia a `SITE_DIR/static`, así que el logo del cliente pisa al del repo.

### Alta de un cliente nuevo
1. `git clone` del repositorio en `/var/www/app_<cliente>/`.
2. Crear `.env` a partir de `.env.example` (DB, SECRET_KEY, ALLOWED_HOSTS, SITE_NAME, DEVELOPED_BY, SITE_DIR).
3. Crear `site/templates/` y `site/static/` (ejemplo en `site/ejemplo/`).
4. Copiar `ppal.html` del repo a `site/templates/ppal/ppal.html` y personalizarla.
5. Copiar el `tema.css` a `site/static/css/tema.css` y cambiar los colores.
6. Copiar `static/media/logo.png` y `favicon.ico` a `site/static/media/`.
7. Crear la base de datos y correr `iniciardb.sh`.
8. Actualizar código: `git pull` dentro de `/var/www/app_<cliente>/`.

### Actualización de código
```bash
cd /var/www/app_<cliente> && git pull
```
El pull solo actualiza código genérico. `.env` y `site/` quedan intactos.

## 9. Cambiar a PostgreSQL (producción)

El proyecto soporta SQLite (por defecto) y PostgreSQL. El motor se elige en el `.env`
de cada cliente con la variable `DB_ENGINE`.

### 1. Verificar el driver
`psycopg2-binary` ya está incluido en `requirements.txt`. Si al instalar faltara:
```bash
uv pip install psycopg2-binary
```

### 2. Crear la base de datos en PostgreSQL
Conexión de ejemplo vía `psql` o PgAdmin:
```sql
CREATE DATABASE nombre_db;
CREATE USER usuario_db WITH PASSWORD 'tu_password';
ALTER ROLE usuario_db SET client_encoding TO 'utf8';
ALTER ROLE usuario_db SET default_transaction_isolation TO 'read committed';
ALTER ROLE usuario_db SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE nombre_db TO usuario_db;
```

### 3. Configurar `.env` del cliente
Cambiar `DB_ENGINE` a `postgresql` y completar los datos:
```dotenv
# Database Configuration
DB_ENGINE=postgresql
DB_NAME=nombre_db
DB_USER=usuario_db
DB_PASSWORD=tu_password
DB_HOST=127.0.0.1
DB_PORT=5432
```

### 4. Aplicar migraciones
```bash
./.venv/bin/python manage.py migrate
```

### Notas
- Los motores soportados están definidos en `tiendadj/settings.py`: `sqlite` (por defecto) y `postgresql`.
- `iniciardb.sh` y `iniciardb_prod.sh` funcionan con PostgreSQL: al usar `flush`,
  no dependen de borrar un archivo y también resetean las secuencias (id a 1).
- Cada cliente puede usar SQLite para pruebas locales y PostgreSQL en producción
  con solo cambiar su propio `.env`, sin tocar el repositorio.