# 02 - MARKETPLACE WEB (mkt.uppi.app.br)

## 1. ESTRUTURA DE DIRETORIOS

```
/var/www/mkt.uppi.app.br/
|-- public/                         # DocumentRoot Apache
|   |-- index.php                   # Entry point (Front Controller)
|   |-- .htaccess                   # Rewrite rules
|   |-- health.php                  # Health check endpoint
|   |-- css/
|   |   |-- app.css                 # CSS customizado (vars, product-card, seller layout)
|   |-- js/
|   |   |-- app.js                  # Inicializador Vue.js global
|   |   |-- vue/
|   |   |   |-- composables/
|   |   |   |   |-- useApi.js       # Cliente HTTP (Fetch + CSRF + 401 redirect)
|   |   |   |   |-- useCart.js      # Estado global carrinho (singleton closure)
|   |   |   |   |-- useToast.js     # Notificacoes flutuantes
|   |   |   |   |-- useAuth.js      # Helpers autenticacao (window.__UPPI__)
|   |   |   |-- components/
|   |   |   |   |-- MiniCart.js      # Offcanvas lateral direito
|   |   |   |   |-- ToastContainer.js
|   |   |   |   |-- SearchSuggestions.js  # Autocomplete debounce 300ms
|   |   |   |   |-- QuantitySelector.js  # Input +/- com min/max
|   |   |   |-- pages/
|   |   |   |   |-- ProductApp.js    # Variantes, frete, add-to-cart
|   |   |   |   |-- CartApp.js       # Cupom, totais reativos
|   |   |   |   |-- CheckoutApp.js   # Wizard 5 steps
|   |   |   |   |-- SellerDashboardApp.js  # KPIs, graficos
|   |-- vendors/
|   |   |-- bootstrap/               # Bootstrap 5.3
|   |   |-- vue/                     # Vue 3 ESM (vue.esm-browser.prod.js)
|   |   |-- sweetalert2/
|   |-- uploads/                     # Imagens de produtos, avatares
|
|-- app/
|   |-- Core/
|   |   |-- App.php                  # Bootstrap singleton, carrega config
|   |   |-- Router.php               # Rotas com params nomeados, groups, middleware
|   |   |-- Request.php              # Parse $_SERVER, $_GET, body JSON
|   |   |-- Response.php             # json(), redirect(), render()
|   |   |-- Controller.php           # Base: render(), json(), validate(), seo()
|   |   |-- Model.php                # Query builder: where(), join(), paginate()
|   |   |-- View.php                 # Renderiza template PHP
|   |   |-- Middleware.php           # Interface middleware
|   |   |-- Session.php              # Dot notation, flash, CSRF
|   |   |-- Database.php             # PDO pool lazy, prepared statements
|   |
|   |-- Controllers/
|   |   |-- HomeController.php
|   |   |-- CatalogController.php    # Catalogo, busca fulltext, filtros
|   |   |-- ProductController.php    # Detalhe produto, avaliacoes
|   |   |-- CartController.php       # CRUD carrinho (AJAX)
|   |   |-- CheckoutController.php   # Frete + finalizar compra
|   |   |-- OrderController.php      # Lista, detalhe, cancelar, tracking
|   |   |-- AuthController.php       # Login, registro, forgot/reset password
|   |   |-- AccountController.php    # Perfil, enderecos
|   |   |-- ReturnController.php     # Solicitar devolucao
|   |   |-- WishlistController.php   # Favoritos (AJAX)
|   |   |-- SearchController.php     # Autocomplete, trending
|   |   |-- Seller/
|   |   |   |-- DashboardController.php
|   |   |   |-- ProductController.php   # CRUD + publicar + estoque
|   |   |   |-- OrderController.php     # Aceitar/rejeitar/despachar
|   |   |   |-- FinanceController.php   # Dashboard, extrato, repasses
|   |   |   |-- AdsController.php       # Campanhas
|   |   |-- Admin/
|   |   |   |-- DashboardController.php
|   |   |   |-- SellerController.php    # Aprovar/suspender
|   |   |   |-- OrderController.php     # Forcar status
|   |   |   |-- FinanceController.php   # Aprovar repasses
|   |
|   |-- Models/
|   |   |-- User.php, Product.php, Category.php, Brand.php
|   |   |-- Cart.php, CartItem.php, Order.php, OrderItem.php, OrderSplit.php
|   |   |-- Seller.php, Review.php, Address.php, Coupon.php
|   |   |-- Notification.php, Wishlist.php, Conversation.php, Message.php
|   |
|   |-- Services/                    # COMPARTILHADO com API (symlink ou require)
|   |   |-- AuthService.php
|   |   |-- CatalogService.php
|   |   |-- CartService.php
|   |   |-- CheckoutService.php
|   |   |-- OrderService.php         # createFromCheckout, changeStatus, createSplits
|   |   |-- PaymentService.php       # processPayment, handleWebhook, refund
|   |   |-- StockService.php         # reserve, release, deduct, inbound
|   |   |-- LedgerService.php        # Double-entry: record, recordSale
|   |   |-- SettlementService.php    # generateSettlement, executeTransfer
|   |   |-- FiscalService.php        # emitNFe, signAndSubmit, cancel, emitCCe
|   |   |-- ReturnService.php        # request, approve, receiveAndInspect
|   |   |-- AdsService.php           # impressions, clicks, conversions, ranking
|   |   |-- ShippingService.php
|   |   |-- CouponService.php
|   |   |-- Shared/
|   |   |   |-- StateMachine.php     # Motor generico de transicoes
|   |   |   |-- EventDispatcher.php  # Singleton: listen, dispatch, event_store + Redis
|   |   |   |-- IdempotencyGuard.php # acquire/release lock
|   |   |   |-- OrderStateMachine.php
|   |   |-- Gateways/
|   |   |   |-- GatewayInterface.php
|   |   |   |-- MercadoPagoGateway.php
|   |   |   |-- GetnetGateway.php
|   |
|   |-- Middleware/
|   |   |-- AuthMiddleware.php       # Verifica sessao
|   |   |-- SellerMiddleware.php     # Verifica seller aprovado
|   |   |-- AdminMiddleware.php      # Verifica user_type admin
|   |   |-- CsrfMiddleware.php       # Valida token CSRF
|   |   |-- GuestMiddleware.php      # Redireciona se logado
|   |
|   |-- Config/
|   |   |-- app.php                  # app_name, timezone, paginacao, api_url
|   |   |-- database.php             # Conexao db_erp (banco unico)
|   |   |-- routes.php               # 80+ rotas organizadas por grupo
|
|-- resources/
|   |-- views/
|   |   |-- layouts/
|   |   |   |-- master.php           # Layout publico (navbar + footer + Vue)
|   |   |   |-- seller.php           # Layout sidebar fixa + topbar
|   |   |   |-- admin.php            # Layout admin
|   |   |   |-- auth.php             # Layout login/registro
|   |   |-- components/
|   |   |   |-- meta-tags.php        # SEO + Open Graph + Twitter Card
|   |   |   |-- navbar.php           # Busca, notificacoes, cart badge
|   |   |   |-- footer.php           # 4 colunas + pagamento
|   |   |   |-- product-card.php     # Card com badge, wishlist, add-to-cart
|   |   |   |-- rating-stars.php     # 0-5 com meia estrela
|   |   |   |-- breadcrumb.php
|   |   |   |-- pagination.php
|   |   |-- pages/
|   |   |   |-- home.php             # Hero + categorias + destaques
|   |   |   |-- catalog.php          # Filtros + grid + paginacao
|   |   |   |-- product.php          # Galeria + info + tabs
|   |   |   |-- cart.php             # Lista + resumo + cupom
|   |   |   |-- login.php            # Form centralizado
|   |   |   |-- register.php
|   |   |   |-- checkout.php         # Container Vue wizard
|   |   |   |-- orders/
|   |   |   |-- account/
|   |   |   |-- seller/              # Dashboard, produtos, pedidos, financeiro
|   |   |   |-- admin/               # Dashboard, sellers, pedidos
|   |   |-- errors/
|   |   |   |-- 404.php, 500.php, maintenance.php
|
|-- docs/                            # Documentacao do projeto (esta pasta)
```

---

## 2. ROTAS (80+)

### Publicas (sem auth)
```
GET  /                           HomeController@index
GET  /catalogo                   CatalogController@index
GET  /catalogo/{slug}            CatalogController@category
GET  /busca                      CatalogController@search
GET  /produto/{slug}             ProductController@show
GET  /loja/{slug}                CatalogController@seller
GET  /rastreio/{code}            OrderController@publicTracking
POST /ajax/produtos              CatalogController@ajaxProducts
POST /ajax/sugestoes             SearchController@suggestions
POST /ajax/frete                 ProductController@ajaxShipping
```

### Auth - Guest Only
```
GET  /login                      AuthController@loginForm
POST /login                      AuthController@login
GET  /cadastro                   AuthController@registerForm
POST /cadastro                   AuthController@register
GET  /esqueci-senha              AuthController@forgotForm
POST /esqueci-senha              AuthController@forgot
GET  /resetar-senha/{token}      AuthController@resetForm
POST /resetar-senha              AuthController@reset
```

### Auth - Cliente Logado
```
POST /logout                     AuthController@logout
GET  /carrinho                   CartController@index
POST /ajax/cart/add              CartController@addItem
PUT  /ajax/cart/update           CartController@updateItem
DELETE /ajax/cart/remove         CartController@removeItem
POST /ajax/cart/coupon           CartController@applyCoupon
GET  /checkout                   CheckoutController@index
POST /checkout                   CheckoutController@process
GET  /pedidos                    OrderController@index
GET  /pedidos/{uuid}             OrderController@show
POST /pedidos/{uuid}/cancelar    OrderController@cancel
GET  /devolucoes                 ReturnController@index
POST /devolucoes                 ReturnController@create
GET  /minha-conta                AccountController@index
PUT  /ajax/conta/perfil          AccountController@updateProfile
POST /ajax/enderecos             AccountController@addAddress
PUT  /ajax/enderecos/{id}        AccountController@updateAddress
DELETE /ajax/enderecos/{id}      AccountController@deleteAddress
POST /ajax/wishlist/toggle       WishlistController@toggle
GET  /favoritos                  WishlistController@index
POST /ajax/avaliacoes            ReviewController@create
GET  /notificacoes               NotificationController@index
```

### Seller Center (auth + seller)
```
GET  /seller                     Seller\DashboardController@index
GET  /seller/produtos            Seller\ProductController@index
GET  /seller/produtos/novo       Seller\ProductController@create
POST /seller/produtos            Seller\ProductController@store
GET  /seller/produtos/{uuid}     Seller\ProductController@edit
PUT  /seller/produtos/{uuid}     Seller\ProductController@update
POST /seller/produtos/{uuid}/publicar    Seller\ProductController@publish
POST /seller/produtos/{uuid}/despublicar Seller\ProductController@unpublish
GET  /seller/estoque             Seller\ProductController@stock
PUT  /ajax/seller/estoque/{uuid} Seller\ProductController@updateStock
GET  /seller/pedidos             Seller\OrderController@index
GET  /seller/pedidos/{id}        Seller\OrderController@show
POST /seller/pedidos/{id}/aceitar    Seller\OrderController@accept
POST /seller/pedidos/{id}/rejeitar   Seller\OrderController@reject
POST /seller/pedidos/{id}/despachar  Seller\OrderController@ship
GET  /seller/financeiro          Seller\FinanceController@index
GET  /seller/extrato             Seller\FinanceController@entries
GET  /seller/repasses            Seller\FinanceController@settlements
GET  /seller/anuncios            Seller\AdsController@index
GET  /seller/avaliacoes          Seller\OrderController@reviews
POST /ajax/seller/avaliacoes/{id}/responder  Seller\OrderController@replyReview
```

### Admin (auth + admin)
```
GET  /admin                      Admin\DashboardController@index
GET  /admin/sellers              Admin\SellerController@index
POST /admin/sellers/{id}/aprovar     Admin\SellerController@approve
POST /admin/sellers/{id}/suspender   Admin\SellerController@suspend
GET  /admin/pedidos              Admin\OrderController@index
GET  /admin/pedidos/{uuid}       Admin\OrderController@show
POST /admin/pedidos/{uuid}/forcar-status  Admin\OrderController@forceStatus
GET  /admin/financeiro           Admin\FinanceController@index
POST /admin/repasses/{id}/aprovar    Admin\FinanceController@approveSettlement
```

---

## 3. PADRAO PHP <-> VUE.JS

### Fluxo de Integracao
1. **PHP renderiza HTML completo** (SEO first)
2. PHP injeta dados via `data-*` attributes e `window.__UPPI__`
3. Vue.js monta nos `div#*-app` e assume interatividade
4. Interacoes AJAX via `/ajax/*` endpoints
5. Respostas atualizam estado Vue reativamente

### Objeto Global (injetado no master.php)
```javascript
window.__UPPI__ = {
    csrf: '{{ csrf_token }}',
    isLogged: true/false,
    user: { id, name, type },
    cartCount: 3,
    apiBase: '/ajax',
    cdnUrl: 'https://cdn.uppi.app.br'
};
```

### Script por Pagina
```php
// No controller:
$this->render('pages/product', [
    'product' => $product,
    'pageScripts' => ['vue/pages/ProductApp.js']
]);

// No layout master.php:
<?php foreach ($pageScripts as $script): ?>
<script type="module" src="<?= asset("js/{$script}") ?>"></script>
<?php endforeach; ?>
```

---

## 4. CSS CUSTOMIZADO (variaveis)

```css
:root {
    --uppi-primary: #4f46e5;       /* Indigo */
    --uppi-secondary: #06b6d4;     /* Cyan */
    --uppi-success: #10b981;       /* Emerald */
    --uppi-text: #1e293b;
    --uppi-border: #e2e8f0;
}
```

- Font: Inter + system fallback
- Product Card: hover translateY(-4px) + shadow
- Seller Layout: sidebar 250px fixa escura (#1e293b)
- Loading Skeleton: gradiente pulsante

---

## 5. LAYOUTS

| Layout | Uso | Estrutura |
|--------|-----|-----------|
| `master.php` | Marketplace publico | Navbar + conteudo + footer + MiniCart + Toast + Vue global |
| `seller.php` | Seller Center | Sidebar fixa + topbar + conteudo (offcanvas mobile) |
| `admin.php` | Admin | Similar ao seller |
| `auth.php` | Login/Registro | Centralizado, simplificado |