Refund é um sistema web moderno e seguro para gerenciamento de solicitações de reembolso de despesas. O projeto foi desenvolvido com foco em arquitetura limpa, princípios SOLID, segurança OWASP e baixo acoplamento.
Este aplicativo permite que você:
- ✅ Registre despesas com nome, categoria e valor
- ✅ Categorize gastos (Alimentação, Hospedagem, Serviços, Transporte, Outros)
- ✅ Acompanhe o total de despesas automaticamente
- ✅ Gerencie reembolsos de forma organizada
- ✅ Armazene dados localmente no navegador (sem necessidade de servidor)
Ideal para:
- Funcionários que precisam solicitar reembolso de despesas corporativas
- Freelancers que precisam controlar gastos de projetos
- Estudantes aprendendo desenvolvimento web profissional
- Desenvolvedores estudando arquitetura de software
Este projeto REQUER um servidor HTTP para funcionar!
- Abra o VS Code
- Instale a extensão "Live Server" (por Ritwick Dey)
- Vá em Extensions (Ctrl+Shift+X)
- Busque por "Live Server"
- Clique em "Install"
- Abra a pasta do projeto no VS Code
- File → Open Folder → Selecione a pasta
refund
- File → Open Folder → Selecione a pasta
- Clique com botão direito no arquivo
index.html - Selecione "Open with Live Server"
- Pronto! O navegador abrirá automaticamente
Este projeto usa ES6 Modules (import/export), que não funcionam com o protocolo file:// por questões de segurança (CORS).
❌ NÃO funciona: Abrir index.html diretamente
✅ FUNCIONA: Usar Live Server ou outro servidor HTTP
📖 Outras opções de servidor: Veja SERVER.md
O projeto segue uma arquitetura profissional com separação clara de responsabilidades:
src/
├── models/ # 📦 Modelos de Dados (Entities)
│ └── Expense.js # Modelo de despesa com validação
│
├── interfaces/ # 🔌 Contratos e Abstrações
│ └── IStorage.js # Interface de armazenamento (DIP)
│
├── adapters/ # 🔄 Adaptadores (Adapter Pattern)
│ └── LocalStorageAdapter.js # Implementação de storage
│
├── repositories/ # 💾 Camada de Acesso a Dados
│ └── ExpenseRepository.js # Repository Pattern (CRUD)
│
├── services/ # 🎯 Lógica de Negócios
│ └── ExpenseService.js # Regras de negócio + Observer Pattern
│
├── validators/ # 🔒 Validação e Segurança (OWASP)
│ └── InputValidator.js # Sanitização e validação de inputs
│
├── utils/ # 🛠️ Utilitários Reutilizáveis
│ ├── CurrencyFormatter.js # Formatação de valores monetários
│ └── DOMHelper.js # Manipulação segura do DOM
│
├── views/ # 🎨 Camada de Apresentação (MVC)
│ ├── ExpenseListView.js # Renderização da lista
│ └── ExpenseSummaryView.js # Renderização do resumo
│
├── controllers/ # 🎮 Controladores (MVC)
│ ├── ExpenseFormController.js # Controle do formulário
│ └── ExpenseListController.js # Controle da lista
│
└── app.js # 🚀 Bootstrap e Injeção de Dependências
| Princípio | Descrição | Implementação |
|---|---|---|
| SRP | Single Responsibility | Cada classe tem UMA responsabilidade |
| OCP | Open/Closed | Extensível sem modificar código existente |
| LSP | Liskov Substitution | Implementações substituíveis (ex: LocalStorageAdapter) |
| ISP | Interface Segregation | Interfaces específicas e coesas (IStorage) |
| DIP | Dependency Inversion | Dependências injetadas via abstrações |
Implementações de segurança seguindo OWASP Top 10 2021:
- ✅ Proteção contra XSS - Sanitização de inputs + uso de
textContent - ✅ Proteção contra Injection - Validação com whitelist
- ✅ Content Security Policy - Headers de segurança configurados
- ✅ Validação em múltiplas camadas - UI, Service, Model, Repository
- ✅ Manipulação segura do DOM - DOMHelper previne XSS
- Repository Pattern - Abstração de acesso a dados
- Observer Pattern - Sistema de eventos entre componentes
- Adapter Pattern - Adaptação de localStorage
- MVC Pattern - Separação Model-View-Controller
- Dependency Injection - Baixo acoplamento via DI
- Factory Pattern - Criação de objetos (Expense.fromJSON)
- HTML5 - Estrutura semântica com acessibilidade (ARIA)
- CSS3 - Estilização responsiva
- JavaScript ES6+ - Programação orientada a objetos
- Módulos ES6 (import/export)
- Classes e herança
- Arrow functions
- Destructuring
- Template literals
- LocalStorage API - Persistência de dados no navegador
- ✅ Adicionar despesas com validação robusta
- ✅ Categorização de despesas (5 categorias)
- ✅ Formatação automática de valores em BRL (R$)
- ✅ Cálculo automático do total
- ✅ Persistência local (dados salvos no navegador)
- ✅ Remoção de despesas com confirmação
- ✅ Interface responsiva (desktop e mobile)
- ✅ Acessibilidade (ARIA labels, navegação por teclado)
- ✅ Sanitização de inputs (proteção contra XSS)
- ❌ 1 arquivo JavaScript monolítico (215 linhas)
- ❌ Código procedural sem organização
- ❌ Alto acoplamento
- ❌ Sem validação robusta
- ❌ Vulnerável a XSS
- ❌ Impossível testar unitariamente
- ✅ 13 classes organizadas (~1200 linhas)
- ✅ Código orientado a objetos
- ✅ Baixo acoplamento
- ✅ Validação robusta (OWASP)
- ✅ Protegido contra XSS
- ✅ 100% testável
- ✅ Escalável e manutenível
- ✅ Documentação completa
| Documento | Descrição |
|---|---|
| README.md | Este arquivo - Visão geral |
| SERVER.md | Como executar o servidor HTTP |
| QUICKSTART.md | Guia rápido de início |
| ARCHITECTURE.md | Arquitetura detalhada |
| SECURITY.md | Segurança OWASP |
| COMPARISON.md | Antes vs Depois |
| SUMMARY.md | Resumo executivo |
Este projeto é ideal para estudar:
- ✅ Arquitetura de Software (Layered Architecture)
- ✅ Princípios SOLID
- ✅ Design Patterns (6 padrões implementados)
- ✅ Segurança Web (OWASP Top 10)
- ✅ JavaScript Moderno (ES6+ Modules)
- ✅ Programação Orientada a Objetos
- ✅ Baixo Acoplamento e Alta Coesão
- ✅ Clean Code
Este projeto é de código aberto e está disponível para fins educacionais.
Refund is a modern and secure web system for managing expense reimbursement requests. The project was developed with a focus on clean architecture, SOLID principles, OWASP security, and low coupling.
This application allows you to:
- ✅ Record expenses with name, category, and amount
- ✅ Categorize spending (Food, Accommodation, Services, Transport, Others)
- ✅ Track total expenses automatically
- ✅ Manage reimbursements in an organized way
- ✅ Store data locally in the browser (no server needed)
Ideal for:
- Employees who need to request corporate expense reimbursement
- Freelancers who need to track project expenses
- Students learning professional web development
- Developers studying software architecture
This project REQUIRES an HTTP server to work!
- Open VS Code
- Install the "Live Server" extension (by Ritwick Dey)
- Go to Extensions (Ctrl+Shift+X)
- Search for "Live Server"
- Click "Install"
- Open the project folder in VS Code
- File → Open Folder → Select the
refundfolder
- File → Open Folder → Select the
- Right-click on the
index.htmlfile - Select "Open with Live Server"
- Done! The browser will open automatically
This project uses ES6 Modules (import/export), which don't work with the file:// protocol due to security reasons (CORS).
❌ DOESN'T work: Opening index.html directly
✅ WORKS: Using Live Server or another HTTP server
📖 Other server options: See SERVER.md
The project follows a professional architecture with clear separation of concerns:
src/
├── models/ # 📦 Data Models (Entities)
│ └── Expense.js # Expense model with validation
│
├── interfaces/ # 🔌 Contracts and Abstractions
│ └── IStorage.js # Storage interface (DIP)
│
├── adapters/ # 🔄 Adapters (Adapter Pattern)
│ └── LocalStorageAdapter.js # Storage implementation
│
├── repositories/ # 💾 Data Access Layer
│ └── ExpenseRepository.js # Repository Pattern (CRUD)
│
├── services/ # 🎯 Business Logic
│ └── ExpenseService.js # Business rules + Observer Pattern
│
├── validators/ # 🔒 Validation and Security (OWASP)
│ └── InputValidator.js # Input sanitization and validation
│
├── utils/ # 🛠️ Reusable Utilities
│ ├── CurrencyFormatter.js # Currency formatting
│ └── DOMHelper.js # Safe DOM manipulation
│
├── views/ # 🎨 Presentation Layer (MVC)
│ ├── ExpenseListView.js # List rendering
│ └── ExpenseSummaryView.js # Summary rendering
│
├── controllers/ # 🎮 Controllers (MVC)
│ ├── ExpenseFormController.js # Form control
│ └── ExpenseListController.js # List control
│
└── app.js # 🚀 Bootstrap and Dependency Injection
| Principle | Description | Implementation |
|---|---|---|
| SRP | Single Responsibility | Each class has ONE responsibility |
| OCP | Open/Closed | Extensible without modifying existing code |
| LSP | Liskov Substitution | Substitutable implementations (e.g., LocalStorageAdapter) |
| ISP | Interface Segregation | Specific and cohesive interfaces (IStorage) |
| DIP | Dependency Inversion | Dependencies injected via abstractions |
Security implementations following OWASP Top 10 2021:
- ✅ XSS Protection - Input sanitization +
textContentusage - ✅ Injection Protection - Whitelist validation
- ✅ Content Security Policy - Security headers configured
- ✅ Multi-layer Validation - UI, Service, Model, Repository
- ✅ Safe DOM Manipulation - DOMHelper prevents XSS
- Repository Pattern - Data access abstraction
- Observer Pattern - Event system between components
- Adapter Pattern - localStorage adaptation
- MVC Pattern - Model-View-Controller separation
- Dependency Injection - Low coupling via DI
- Factory Pattern - Object creation (Expense.fromJSON)
- HTML5 - Semantic structure with accessibility (ARIA)
- CSS3 - Responsive styling
- JavaScript ES6+ - Object-oriented programming
- ES6 Modules (import/export)
- Classes and inheritance
- Arrow functions
- Destructuring
- Template literals
- LocalStorage API - Browser data persistence
- ✅ Add expenses with robust validation
- ✅ Expense categorization (5 categories)
- ✅ Automatic BRL currency formatting (R$)
- ✅ Automatic total calculation
- ✅ Local persistence (data saved in browser)
- ✅ Expense removal with confirmation
- ✅ Responsive interface (desktop and mobile)
- ✅ Accessibility (ARIA labels, keyboard navigation)
- ✅ Input sanitization (XSS protection)
- ❌ 1 monolithic JavaScript file (215 lines)
- ❌ Unorganized procedural code
- ❌ High coupling
- ❌ No robust validation
- ❌ Vulnerable to XSS
- ❌ Impossible to unit test
- ✅ 13 organized classes (~1200 lines)
- ✅ Object-oriented code
- ✅ Low coupling
- ✅ Robust validation (OWASP)
- ✅ Protected against XSS
- ✅ 100% testable
- ✅ Escalável e manutenível
- ✅ Documentação completa
| Document | Description |
|---|---|
| README.md | This file - Overview |
| SERVER.md | How to run HTTP server |
| QUICKSTART.md | Quick start guide |
| ARCHITECTURE.md | Detailed architecture |
| SECURITY.md | OWASP security |
| COMPARISON.md | Before vs After |
| SUMMARY.md | Executive summary |
This project is ideal for studying:
- ✅ Software Architecture (Layered Architecture)
- ✅ SOLID Principles
- ✅ Design Patterns (6 patterns implemented)
- ✅ Web Security (OWASP Top 10)
- ✅ Modern JavaScript (ES6+ Modules)
- ✅ Object-Oriented Programming
- ✅ Low Coupling and High Cohesion
- ✅ Clean Code
Contributions are welcome! Feel free to:
- Fork the project
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
⭐ Se este projeto foi útil para você, considere dar uma estrela!
⭐ If this project was useful to you, consider giving it a star!