# 📘 DOCUMENTACIÓN DEL PROYECTO - PERFUME CHIMI

**Sistema de Gestión de Inventario para Perfumería**

---

## 🎯 RESUMEN GENERAL DEL SISTEMA

**perfumeChimi** es un sistema de gestión de inventario y control de precios para una perfumería que vende fragancias árabes. El sistema permite administrar productos con un esquema de precios escalonados basado en márgenes de ganancia del 30%, 50%, 75% y 100%.

### **Objetivo Principal**
Gestionar el inventario de fragancias con cálculo automático de precios considerando:
- Costo de materia prima por kilogramo
- IVA del 19%
- Costos fijos y variables (empaques, alcohol, mano de obra, etc.)
- Múltiples precios de venta según margen de ganancia

---

## 🏗️ ESTRUCTURA DEL PROYECTO

### **Framework y Tecnologías**
- **Laravel:** 10.10
- **PHP:** 8.1+
- **Base de datos:** MySQL (puerto 3308, BD: "perfumes")
- **Frontend:** Blade Templates, HTML5, CSS3, JavaScript
- **Librerías:**
  - Select2 4.1.0 (selectores avanzados)
  - SweetAlert2 11 (alertas)
  - Font Awesome 6.4.0 (iconos)
  - jQuery 3.6.0
  - DomPDF 3.1 (generación de PDFs - no implementado aún)

### **Estructura de Directorios Principal**
```
c:\xampp\htdocs\perfumeChimi\
├── app/
│   ├── Models/              # Modelos Eloquent
│   └── Http/Controllers/    # Controladores
├── database/
│   └── migrations/          # Migraciones de BD
├── resources/
│   └── views/               # Vistas Blade
├── public/
│   ├── css/                 # Estilos CSS
│   └── js/                  # JavaScript
├── routes/
│   └── web.php              # Definición de rutas
├── .env                     # Configuración de entorno
└── CLAUDE.md                # Este archivo (PROTEGIDO)
```

---

## 🔐 SEGURIDAD DE ESTE ARCHIVO

**⚠️ IMPORTANTE:** Este archivo `CLAUDE.md` es solo para uso interno del equipo de desarrollo.

**Protección implementada:**
- Archivo `.htaccess` en la raíz bloquea el acceso HTTP a `CLAUDE.md`
- No debe ser accesible públicamente desde el navegador
- Solo accesible desde el servidor local

---

## 📊 LÓGICA DE NEGOCIO IMPLEMENTADA

### **Sistema de Precios Basado en Excel**

El sistema replica la lógica de un archivo Excel con las siguientes columnas y cálculos:

#### **Campos de Entrada Manual:**

1. **PRODUCTO** (`nombre`): Nombre que le da el proveedor
2. **FRAGANCIA** (`fragancia`): Nombre comercial (OBLIGATORIO)
3. **CÓDIGO** (`codigo`): Código único del producto
4. **CATEGORÍA** (`categoria_id`): Clasificación del producto
5. **PRESENTACIÓN** (`presentacion`): Tamaño (ej: 100ml, 50ml)
6. **COSTO 1K** (`costo_1k`): Costo de compra por kilogramo (valor base)
7. **COSTO FRAG + % CF + CV** (`costo_frag_cf_cv`): Costo total del producto terminado
   - FRAG: Costo de la fragancia por unidad
   - CF: Costos Fijos (empaques, envases, etiquetas)
   - CV: Costos Variables (alcohol, mano de obra, etc.)

#### **Campos Calculados Automáticamente:**

1. **19% IVA** (`iva_19`):
   ```
   iva_19 = costo_1k × 0.19
   ```

2. **COSTO 1K + IVA** (`costo_1k_con_iva`):
   ```
   costo_1k_con_iva = costo_1k + iva_19
   ```

3. **COSTO GR** (`costo_gr`):
   ```
   costo_gr = costo_1k_con_iva ÷ 1000
   ```
   *Convierte el costo de kilogramo a gramo*

4. **PRECIO 30%** (`precio_30`):
   ```
   precio_30 = costo_frag_cf_cv × 1.30
   ```
   *Precio con 30% de margen de ganancia*

5. **PRECIO 50%** (`precio_50`):
   ```
   precio_50 = costo_frag_cf_cv × 1.50
   ```
   *Precio con 50% de margen de ganancia*

6. **PRECIO 75%** (`precio_75`):
   ```
   precio_75 = costo_frag_cf_cv × 1.75
   ```
   *Precio con 75% de margen de ganancia*

7. **PRECIO 100%** (`precio_100`):
   ```
   precio_100 = costo_frag_cf_cv × 2.00
   ```
   *Precio con 100% de margen (doble del costo)*

### **Flujo de Cálculo Completo:**

```
ENTRADA MANUAL: costo_1k (ej: 162,401)
      ↓
CÁLCULO: iva_19 = 162,401 × 0.19 = 30,856
      ↓
CÁLCULO: costo_1k_con_iva = 162,401 + 30,856 = 193,257
      ↓
CÁLCULO: costo_gr = 193,257 ÷ 1000 = 193.257
      ↓
ENTRADA MANUAL: costo_frag_cf_cv (ej: 271)
      ↓
CÁLCULO: precio_30 = 271 × 1.30 = 352
CÁLCULO: precio_50 = 271 × 1.50 = 406
CÁLCULO: precio_75 = 271 × 1.75 = 473
CÁLCULO: precio_100 = 271 × 2.00 = 542
```

---

## 🗄️ ESTRUCTURA DE LA BASE DE DATOS

### **Tabla: `productos`**

| Campo | Tipo | Descripción | ¿Calculado? |
|-------|------|-------------|-------------|
| `id` | bigint (PK) | ID único | - |
| `codigo` | varchar(50) UNIQUE | Código del producto | Manual |
| `nombre` | varchar(200) | Nombre del proveedor | Manual |
| `fragancia` | varchar(200) | Nombre comercial | Manual (OBLIGATORIO) |
| `presentacion` | varchar(100) | Tamaño (100ml, 50ml, etc.) | Manual (opcional) |
| `categoria_id` | bigint (FK) | Categoría del producto | Manual |
| `costo_1k` | decimal(12,2) | Costo por kilogramo | Manual |
| `iva_19` | decimal(12,2) | IVA del 19% | ✅ Calculado |
| `costo_1k_con_iva` | decimal(12,2) | Costo + IVA | ✅ Calculado |
| `costo_gr` | decimal(12,2) | Costo por gramo | ✅ Calculado |
| `costo_frag_cf_cv` | decimal(12,2) | Costo total terminado | Manual |
| `precio_30` | decimal(12,2) | Precio con 30% ganancia | ✅ Calculado |
| `precio_50` | decimal(12,2) | Precio con 50% ganancia | ✅ Calculado |
| `precio_75` | decimal(12,2) | Precio con 75% ganancia | ✅ Calculado |
| `precio_100` | decimal(12,2) | Precio con 100% ganancia | ✅ Calculado |
| `stock_actual` | integer | Cantidad disponible | Manual |
| `stock_minimo` | integer | Nivel mínimo de alerta | Manual |
| `estado` | boolean | Activo/Inactivo | Manual |
| `created_at` | timestamp | Fecha de creación | Auto |
| `updated_at` | timestamp | Última actualización | Auto |

### **Tabla: `categorias`**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `id` | bigint (PK) | ID único |
| `nombre` | varchar(100) UNIQUE | Nombre de categoría |
| `descripcion` | text | Descripción opcional |
| `estado` | boolean | Activo/Inactivo |
| `created_at` | timestamp | Fecha de creación |
| `updated_at` | timestamp | Última actualización |

### **Tabla: `proveedores`**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `id` | bigint (PK) | ID único |
| `nombre` | varchar(255) | Nombre del proveedor |
| `documento` | varchar(20) UNIQUE | NIT o documento |
| `telefono` | varchar(20) | Teléfono de contacto |
| `email` | varchar(100) | Email |
| `direccion` | text | Dirección |
| `contacto` | varchar(100) | Persona de contacto |
| `estado` | boolean | Activo/Inactivo |
| `created_at` | timestamp | Fecha de creación |
| `updated_at` | timestamp | Última actualización |

### **Tabla: `producto_costos` (OCULTA - NO EN USO ACTUALMENTE)**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `id` | bigint (PK) | ID único |
| `producto_id` | bigint (FK) | Producto asociado |
| `concepto` | varchar(200) | Tipo de costo (alcohol, tapa, etc.) |
| `valor` | decimal(10,2) | Valor del costo |
| `created_at` | timestamp | Fecha de creación |
| `updated_at` | timestamp | Última actualización |

**Nota:** Esta tabla y su funcionalidad están **ocultas** en las vistas pero se mantienen en la BD para uso futuro.

---

## 📝 REGLAS DE NEGOCIO IMPORTANTES

### **1. Cálculos Automáticos**

- Los cálculos se realizan en el **backend (PHP)** y también en el **frontend (JavaScript)** para actualización en tiempo real
- Los valores calculados se **guardan en la base de datos** para mejor rendimiento y trazabilidad
- Al editar `costo_1k` o `costo_frag_cf_cv`, todos los valores dependientes se recalculan automáticamente

### **2. Validaciones**

- El campo `codigo` debe ser **único** en toda la base de datos
- El campo `fragancia` es **obligatorio** (no puede estar vacío)
- El campo `costo_1k` debe ser **mayor a 0**
- El campo `costo_frag_cf_cv` debe ser **mayor a 0**
- El campo `stock_actual` debe ser **entero positivo o cero**
- El campo `stock_minimo` debe ser **entero positivo o cero**

### **3. Sistema de Alertas de Stock Bajo**

- Se activa cuando: `stock_actual <= stock_minimo`
- Notificación en tiempo real con badge en el header
- Polling cada 30 segundos vía API: `/api/notificaciones/stock-bajo`
- Las notificaciones se almacenan en `localStorage` del navegador

### **4. Formato de Números (Colombia)**

- **Separador de miles:** Punto (.) → Ejemplo: 1.000.000
- **Separador decimal:** Coma (,) → Ejemplo: 1.500,50
- Implementado con JavaScript en formularios
- Conversión automática al enviar al servidor (punto decimal estándar)

### **5. Estados de Productos**

- `estado = true`: Producto activo y disponible
- `estado = false`: Producto inactivo (no aparece en ventas)

---

## 🚀 FUNCIONALIDADES IMPLEMENTADAS

### **Módulo de Productos**

✅ **CRUD Completo:**
- Crear producto con cálculos automáticos
- Ver listado con filtros y búsqueda
- Editar producto con recálculo automático
- Eliminar producto (con validaciones)
- Ver detalle de producto

✅ **Búsqueda y Filtros:**
- Búsqueda en tiempo real por código o nombre
- Filtro por categoría
- Filtro por productos con stock bajo
- Paginación personalizada (5, 10, 25, 50 registros)

✅ **Alertas:**
- Sistema de notificaciones de stock bajo
- Badge animado en el header
- Dropdown con listado de productos afectados

### **Módulo de Categorías**

✅ **CRUD Completo:**
- Crear, editar, ver, eliminar categorías
- Protección contra eliminación si tiene productos asociados

### **Módulo de Proveedores**

✅ **CRUD Completo:**
- Gestión completa de proveedores
- Contador de compras asociadas

### **Módulos Ocultos (Temporalmente)**

🔒 **Compras:** Funcionalidad completa pero oculta del menú
🔒 **Clientes:** Funcionalidad completa pero oculta del menú
🔒 **Ventas:** Funcionalidad completa pero oculta del menú
🔒 **Costos Adicionales:** Tabla y funcionalidad mantenidas pero ocultas

---

## 🛠️ CAMBIOS REALIZADOS (HISTORIAL)

### **Fecha: 2026-06-03**

#### **Cambios en la Base de Datos:**

✅ **Eliminados:**
- Campo `precio_compra` (reemplazado por `costo_1k`)
- Campo `precio_venta` (reemplazado por precios escalonados)
- Campo `descripcion` (no necesario según Excel)
- Campo `marca` (no necesario según Excel)

✅ **Agregados:**
- `fragancia` VARCHAR(200) NOT NULL
- `costo_1k` DECIMAL(12,2)
- `iva_19` DECIMAL(12,2)
- `costo_1k_con_iva` DECIMAL(12,2)
- `costo_gr` DECIMAL(12,2)
- `costo_frag_cf_cv` DECIMAL(12,2)
- `precio_30` DECIMAL(12,2)
- `precio_50` DECIMAL(12,2)
- `precio_75` DECIMAL(12,2)
- `precio_100` DECIMAL(12,2)

#### **Cambios en el Código:**

✅ **Separación de CSS:**
- Estilos de Select2 movidos a `public/css/select2-custom.css`
- Estilos de notificaciones en `public/css/app.css`

✅ **Separación de JavaScript:**
- Lógica de formularios en `public/js/productos-form.js`
- Formateo de números en `public/js/number-format.js`
- Sistema de notificaciones en `public/js/app.js`

✅ **Actualización de Vistas:**
- `index.blade.php`: Nueva tabla con columnas del Excel
- `create.blade.php`: Formulario con nuevos campos y cálculos automáticos
- `edit.blade.php`: Formulario con nuevos campos y cálculos automáticos
- `show.blade.php`: Detalle con todos los campos calculados

✅ **Ocultaciones:**
- Menú: Compras, Clientes, Ventas (comentados en `layouts/app.blade.php`)
- Botón "Costos adicionales" en index de productos

#### **Decisiones Técnicas:**

- Migraciones separadas para mejor control de versiones
- Valores calculados guardados en BD (mejor rendimiento)
- Campo `fragancia` definido como obligatorio
- Eliminados campos de prueba en la BD

---

## ⚠️ PROBLEMAS ENCONTRADOS Y SOLUCIONES

### **Problema 1: Código duplicado en formularios**

**Descripción:** Las vistas `create.blade.php` y `edit.blade.php` tenían código CSS y JavaScript duplicado (240+ líneas).

**Solución:**
- Creación de archivos externos reutilizables
- `select2-custom.css` para estilos
- `productos-form.js` para lógica de formularios
- `number-format.js` para formateo de números

---

## 📌 PENDIENTES Y PRÓXIMAS TAREAS

### **Alta Prioridad:**

- [ ] Implementar generación de PDFs para listados de productos
- [ ] Agregar exportación a Excel de productos
- [ ] Implementar sistema de reportes con gráficos

### **Media Prioridad:**

- [ ] Sistema de usuarios con roles y permisos
- [ ] Auditoría de cambios (quién hizo qué y cuándo)
- [ ] Backup automático de la base de datos

### **Baja Prioridad:**

- [ ] Reactivar módulo de Compras con nueva lógica
- [ ] Reactivar módulo de Ventas con nueva lógica
- [ ] Implementar sistema de múltiples sucursales

---

## 🔍 CONSIDERACIONES IMPORTANTES PARA NUEVAS SESIONES

### **Al continuar este proyecto:**

1. **Leer este archivo completo** antes de hacer cambios
2. **Respetar la lógica de cálculo** del Excel (no modificar fórmulas sin consultar)
3. **Mantener separación de CSS/JS** en archivos externos
4. **No eliminar** la tabla `producto_costos` (está oculta pero puede reactivarse)
5. **No exponer** este archivo `CLAUDE.md` públicamente
6. **Actualizar este archivo** cada vez que se hagan cambios significativos

### **Comandos útiles:**

```bash
# Ejecutar migraciones
php artisan migrate

# Revertir última migración
php artisan migrate:rollback

# Crear nueva migración
php artisan make:migration nombre_de_la_migracion

# Crear controlador
php artisan make:controller NombreController

# Crear modelo
php artisan make:model NombreModelo

# Limpiar caché
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

### **Rutas importantes:**

```
/productos              → Listado de productos
/productos/create       → Crear producto
/productos/{id}/edit    → Editar producto
/productos/{id}         → Ver detalle de producto
/categorias             → Listado de categorías
/proveedores            → Listado de proveedores
/api/notificaciones/stock-bajo → API de notificaciones
```

---

## 📧 CONTACTO Y SOPORTE

Para dudas sobre este proyecto, contactar al equipo de desarrollo.

**Última actualización:** 2026-06-03
**Versión del documento:** 1.0
**Responsable:** Claude Code Assistant

---

## 📄 LICENCIA Y CONFIDENCIALIDAD

Este documento es **confidencial** y solo debe ser usado internamente por el equipo de desarrollo de perfumeChimi. No compartir públicamente.

---

**FIN DEL DOCUMENTO**
