# Product Requirements Document (PRD)

## Almacen - Inventory Management System

**Project:** Almacen2 - Modern Inventory & Provisioning System  
**Version:** 1.0.0  
**Date:** 2026-03-18  
**Status:** Draft for Review  

---

## 1. Executive Summary

### Purpose
Replace the legacy PHP/MySQL inventory management system (AlmacenAdmin, 2017) with a modern Laravel-based solution that handles:
- Equipment loans (Préstamos)
- Personal protective equipment (PPE) provisions (Dotaciones)
- Item transfers between locations (Transferencias)
- Comprehensive inventory tracking
- Reporting with CSV export

### Target Users
| Role | Spanish | Description | Permissions |
|------|---------|-------------|-------------|
| **Admin** | Administrador | Warehouse administrators | Full CRUD, reports, configuration |
| **Supervisor** | Supervisor | Department supervisors | Approve/reject operations, view all |
| **Worker** | Trabajador/Obrero | Field workers | Request operations, view own transactions |

---

## 2. Legacy Baseline (AlmacenAdmin)

### Current System Overview
- **Technology:** PHP 7.1 / MySQL (MariaDB) — 2017
- **Architecture:** Monolithic procedural PHP
- **Data Model:** Flat tables without relationships
- **Authentication:** Simple password hash (MD5/single hash)
- **No API:** Pure server-side rendering

### Legacy Database Schema

| Table | Purpose | Key Fields |
|-------|---------|------------|
| `bienes` | Inventory items | sap, codigo, descripcion, cantidad, tipo |
| `prestamos` | Equipment loans | numOperacion, codigo, cantidad, status, cedulaSolicita |
| `dotacion` | PPE provisions | numOperacion, codigo, cantidad, status |
| `transferencias` | Location transfers | numOperacion, codigo, cantidad, emisor, receptor |
| `devolucionprestamo` | Loan returns | numOperacion, fechaDevolucion |
| `devoluciontransferencia` | Transfer returns | numOperacion, emisor, receptor |
| `usuarios` | Users (workers) | cedula, nombre, tipo, cargo, tallas uniformes |
| `operaciones` | Operation registry | numero, tipo |
| `registrostock` | Stock movements | numOperacion, codigo, cantidad, objetivo |

### Legacy Business Flows
1. **Loans (Préstamos):** Request → Approval → Dispatch → Return
2. **Provisions (Dotaciones):** Request → Approval → Dispatch → Complete
3. **Transfers (Transferencias):** Request → Approval → Complete → (Optional Return)
4. **Stock Registry:** Ingestion → Movements → Auditing

---

## 3. Architectural Vision (Target)

### Technology Stack
| Component | Technology | Version |
|-----------|------------|---------|
| Framework | Laravel | 12.x |
| Database | PostgreSQL (prod) / SQLite (dev) | 15+ / 3.x |
| Frontend | Blade + Bootstrap 5 | 5.x |
| API | RESTful JSON API | v1 |
| Auth (Web) | Laravel Breeze | 2.x |
| Auth (API) | Laravel Sanctum | 4.x |
| Testing | PHPUnit/Pest | 4.x / 4.x |

### Target Data Model

```mermaid
erDiagram
    USER ||--o{ TRANSACTION : requests
    USER ||--o{ TRANSACTION : authorizes
    USER ||--o{ TRANSACTION : dispatches
    USER {
        string name
        string email
        string role
        string department
        string job_title
        string employee_id
        date hire_date
        string shirt_size
        string jacket_size
        string pants_size
        string boots_size
        string shoes_size
    }
    
    ITEM ||--o{ TRANSACTION_ITEM : involved_in
    ITEM }|--|| CATEGORY : belongs_to
    ITEM }|--|| LOCATION : stored_at
    
    ITEM {
        string sap_code
        string barcode
        string description
        int stock
        int min_stock
        int max_stock
        decimal cost
        decimal weight
        string pack_unit
        int pack_quantity
        string distribution_unit
        string image_path
        string status
    }
    
    TRANSACTION ||--o{ TRANSACTION_ITEM : contains
    TRANSACTION }|--|| USER : requested_by
    TRANSACTION }|--|| USER : authorized_by
    TRANSACTION }|--|| USER : dispatched_by
    
    TRANSACTION {
        string type
        string status
        date request_date
        date approval_date
        date dispatch_date
    }
    
    TRANSACTION_ITEM {
        int quantity
        string notes
    }
    
    LOCATION ||--o{ LOCATION : has_parent
    LOCATION {
        string name
        string location_type
        int parent_id
    }
    
    CATEGORY {
        string name
        string code
        boolean is_epp
    }
```

### Status Workflows

#### Loan (Préstamo) Flow
```
Solicitud → Pendiente → Aprobado → Despachado → Devuelto
                    ↘ Rechazado
                    ↘ Cancelado
```

#### Provision (Dotación) Flow
```
Solicitud → Pendiente → Aprobado → Despachado → Entregado
                    ↘ Rechazado
                    ↘ Cancelado
```

#### Transfer (Transferencia) Flow
```
Solicitud → Pendiente → Aprobado → Completado
                    ↘ Cancelado
```

---

## 4. Functional Requirements

### 4.1 Items Module (Inventario)

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F001 | CRUD Items | High | ⏳ Pending |
| F002 | Unique SAP Code per item | High | ⏳ Pending |
| F003 | Auto-generate barcode | High | ⏳ Pending |
| F004 | Min/Max stock levels | High | ⏳ Pending |
| F005 | Categories (with EPP flag) | High | ⏳ Pending |
| F006 | Locations (hierarchical) | High | ⏳ Pending |
| F007 | Item images | Medium | ⏳ Pending |
| F008 | Unit cost tracking | High | ⏳ Pending |
| F009 | Weight for logistics | Medium | ⏳ Pending |
| F010 | Unit conversion (pack → distribution) | Medium | ⏳ Pending |
| F011 | Search and filter items | High | ⏳ Pending |
| F012 | Low stock alerts | High | ⏳ Pending |

### 4.2 Loans Module (Préstamos)

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F020 | Create loan request | High | ⏳ Pending |
| F021 | Approve/Reject loan | High | ⏳ Pending |
| F022 | Dispatch loan | High | ⏳ Pending |
| F023 | Return loan | High | ⏳ Pending |
| F024 | Cancel pending loan | Medium | ⏳ Pending |
| F025 | Loan history per user | High | ⏳ Pending |
| F026 | Stock adjustment on dispatch/return | High | ⏳ Pending |

### 4.3 Provisions Module (Dotaciones)

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F030 | Create provision request | High | ⏳ Pending |
| F031 | Track worker uniform sizes | High | ⏳ Pending |
| F032 | Approve/Reject provision | High | ⏳ Pending |
| F033 | Dispatch provision | High | ⏳ Pending |
| F034 | Complete provision | High | ⏳ Pending |
| F035 | Provision history per user | High | ⏳ Pending |

### 4.4 Transfers Module (Transferencias)

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F040 | Create transfer request | High | ⏳ Pending |
| F041 | Source/Destination locations | High | ⏳ Pending |
| F042 | Approve/Reject transfer | High | ⏳ Pending |
| F043 | Complete transfer (update stock) | High | ⏳ Pending |
| F044 | Transfer history | High | ⏳ Pending |

### 4.5 Reports Module (Reportes)

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F050 | Inventory report | High | ⏳ Pending |
| F051 | Loans report (by status) | High | ⏳ Pending |
| F052 | Provisions report | High | ⏳ Pending |
| F053 | Transfers report | High | ⏳ Pending |
| F054 | Low stock report | High | ⏳ Pending |
| F055 | Monthly operations summary | Medium | ⏳ Pending |
| F056 | Item tracking (history) | Medium | ⏳ Pending |
| F057 | Export all reports to CSV | High | ⏳ Pending |

### 4.6 Import/Export Module

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F060 | Bulk import items via CSV | High | ⏳ Pending |
| F061 | Download CSV template | High | ⏳ Pending |
| F062 | Auto-create categories on import | Medium | ⏳ Pending |
| F063 | Auto-create locations on import | Medium | ⏳ Pending |

### 4.7 Authentication & Authorization

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| F070 | User authentication (web) | High | ✅ Done |
| F071 | Role-based access (Admin/Supervisor/User) | High | ⏳ Pending |
| F072 | API token authentication | Medium | ⏳ Pending |

---

## 5. Non-Functional Requirements

### 5.1 Performance
| Metric | Requirement |
|--------|-------------|
| Response time | < 2 seconds |
| Max concurrent users | 100 |
| Initial load | < 3 seconds |

### 5.2 Security
- Passwords hashed with BCrypt (cost factor 10)
- CSRF tokens on all forms
- XSS prevention
- SQL injection prevention
- Secure file upload validation
- Rate limiting on API

### 5.3 Usability
- Interface in Spanish
- Responsive design (Bootstrap 5)
- Clear error messages
- Progress indicators for long operations

---

## 6. Current State Analysis

### ✅ Already Implemented

| Component | Details |
|-----------|---------|
| Laravel 12 setup | Composer.json, artisan, bootstrap |
| Authentication | Breeze installed, login/logout routes |
| User model | Extended with legacy fields (cedula, cargo, tallas) |
| Legacy migrations | bienes, prestamos, dotacion, transferencias, usuarios |
| Basic CRUD infrastructure | ModelCrudController (generic) |
| Dashboard route | Basic controller exists |
| Admin routes | /administracion, /asignacion (basic) |

### ⏳ Partially Implemented

| Component | Details |
|-----------|---------|
| Migrations | Legacy schema mapped, modern models NOT created |
| Routes | Basic skeleton, no actual implementation |
| Models | Skeleton models, no relationships or methods |

### ❌ Not Yet Implemented

| Component | Priority |
|-----------|----------|
| Modern data model (Items, Categories, Locations, Transactions) | Critical |
| API v1 endpoints | High |
| Transaction workflows (loans, provisions, transfers) | Critical |
| Reports with CSV export | High |
| Bulk import functionality | High |
| Barcode generation | Medium |
| Image handling for items | Medium |
| Unit conversion system | Medium |
| Role-based middleware | High |
| Comprehensive tests | High |

---

## 7. Out of Scope (MVP Phase 1)

The following are explicitly **NOT** in scope for the initial release:

- Email/SMS notifications
- Advanced dashboard with charts
- Mobile native app
- Barcode scanning (hardware integration)
- Multi-tenant support
- Complete audit trail
- Real-time WebSocket updates
- PDF report generation

---

## 8. Timeline Estimate

| Milestone | Duration | Deliverables |
|-----------|----------|--------------|
| M1: Foundation | 1 week | Modern data models, migrations, seeders |
| M2: Items CRUD | 1 week | Full items management, categories, locations |
| M3: Loans Workflow | 1 week | Complete loan lifecycle |
| M4: Provisions Workflow | 3 days | PPE/uniform provisioning |
| M5: Transfers Workflow | 2 days | Location transfers |
| M6: Reports & Export | 1 week | All reports, CSV export, bulk import |
| M7: Testing & Polish | 1 week | Unit tests (>85%), bug fixes |

**Total estimated:** 6-7 weeks

---

## 9. Dependencies

### External Systems
- None currently (standalone system)

### Internal Dependencies
- Laravel 12.x framework
- PostgreSQL 15+ for production
- Bootstrap 5.x for UI

---

## 10. Acceptance Criteria

### Items
- [ ] Create item with unique SAP code
- [ ] Auto-generate barcode on item creation
- [ ] System calculates available stock (stock - reserved)
- [ ] Upload item image
- [ ] Warning when stock ≤ min_stock

### Loans
- [ ] User can request loan
- [ ] Supervisor can approve/reject
- [ ] Admin can dispatch
- [ ] Stock reduces on dispatch
- [ ] Stock increases on return

### Provisions
- [ ] User can request provision
- [ ] System stores user's uniform sizes
- [ ] Supervisor can approve/reject
- [ ] Auto-create when approved

### Reports
- [ ] View inventory report
- [ ] Export any report to CSV
- [ ] CSV opens correctly in Excel

### Security
- [ ] Passwords encrypted with BCrypt
- [ ] Only authenticated users can access
- [ ] Images stored securely
- [ ] SQL injection prevented

---

## 11. References

- Legacy system: `/home/you/Work/AlmacenAdmin`
- Architectural docs: `/home/you/Work/Almacen/docs`
- Target workspace: `/home/you/Work/almacen2`
- SSOT workflow: `/home/you/Work/ssot`

---

*Document Version: 1.0.0*  
*Last Updated: 2026-03-18*
