# WEBSPOT ASSETS - GUIA PARA CLAUDE CODE

Sistema centralizado de componentes WebSpot. Layout principal: `theme-assets::layouts.webspot`.

> **Documentacao completa em [`docs/`](docs/README.md).** Este arquivo e um indice + as regras criticas que voce **precisa** ter em mente o tempo todo.

## Mapa rapido da documentacao

| Eu quero... | Vou para |
|-------------|----------|
| Comecar/migrar/quickstart | [docs/getting-started/](docs/getting-started/README.md) |
| Internals do package | [docs/architecture/](docs/architecture/README.md) |
| Lista de componentes (47) | [docs/components/](docs/components/README.md) |
| Cores/tokens/temas/dark mode | [docs/design/](docs/design/README.md) |
| Controllers, services, traits, helpers | [docs/backend/](docs/backend/README.md) |
| JS globals, vendors, padroes JS | [docs/frontend/](docs/frontend/README.md) |
| Menu, user_menu, env vars | [docs/configuration/](docs/configuration/README.md) |
| Seguranca, best practices, troubleshooting | [docs/quality/](docs/quality/README.md) |

## Estrutura

```
/var/www/assets/
├── laravel-package/        # Package Laravel (ServiceProvider, controllers, traits, views)
├── css/                    # CSS dos componentes (servido via CDN)
├── js/                     # JavaScript dos componentes (servido via CDN)
├── themes/                 # Temas, icones e vendors (Bootstrap, jQuery 3.7.1)
└── docs/                   # Documentacao organizada em 8 subpastas
```

Detalhes em [docs/architecture/overview.md](docs/architecture/overview.md).

## Regras criticas (memorize)

### NAO faca

1. **NAO** crie componentes duplicados nos projetos — use os do assets ([lista](docs/components/README.md)).
2. **NAO** use `<x-webspot-products-menu>` — foi REMOVIDO. Use `<x-webspot-products-menu-server>`.
3. **NAO** use `{!! !!}` em Blade com dados de usuario — use `{{ }}` para escape automatico.
4. **NAO** faca catch blocks vazios — sempre logue com `\Log::warning()` ou `\Log::error()` e contexto.
5. **NAO** concatene URL do CDN manualmente — use `asset_cdn('path')`.
6. **NAO** use `{{ session(...) }}` em contexto JS — use `@json(session(...))`.
7. **NAO** use `console.log()` em codigo de producao.
8. **NAO** use `alert()` para erros — use `WebSpotNotify.error()`.
9. **NAO** atribua dados de usuario a `.innerHTML` — use `.textContent`.
10. **NAO** hardcode URLs do CDN nos componentes — use `asset_cdn()`.
11. **NAO** use RemixIcon (`ri-`) ou Line Awesome (`la-`) — use Bootstrap Icons (`bi-`).
12. **NAO** crie funcoes JS globais em componentes reutilizaveis — escope ao container.

### SEMPRE faca

1. **SEMPRE** use os componentes WebSpot disponiveis ([lista completa](docs/components/README.md)).
2. **SEMPRE** configure menus via `config/theme-assets.php` (`label`, `active_pattern`, `items`).
3. **SEMPRE** use `@json()` ao inserir dados PHP em JS.
4. **SEMPRE** logue erros em catch blocks com contexto.
5. **SEMPRE** use `asset_cdn('path')` para URLs de assets.
6. **SEMPRE** use `userTimezone()` para exibir datas (respeita fuso horario).
7. **SEMPRE** verifique `response.ok` em `fetch()` antes de `response.json()`.
8. **SEMPRE** valide inputs nos controllers (`$request->validate(...)`) — IDs como `integer|min:1`.
9. **SEMPRE** valide dominios em redirects (`str_ends_with($host, '.webspot.com.br')`).
10. **SEMPRE** use Bootstrap Icons (`bi-`) como padrao.

Detalhamento e exemplos: [docs/quality/best-practices.md](docs/quality/best-practices.md), [docs/quality/security.md](docs/quality/security.md), [docs/quality/pr-checklist.md](docs/quality/pr-checklist.md).

## Layout basico (referencia rapida)

```blade
@extends('theme-assets::layouts.webspot')

@section('title', 'Pagina')

@section('sidebar')
    <x-webspot-sidebar-nav />
@endsection

@section('header-left')
    <x-webspot-products-menu-server />
@endsection

@section('header-right')
    <x-webspot-user-menu />
@endsection

@section('content')
    {{-- Seu conteudo --}}
@endsection
```

Exemplo completo + sections disponiveis: [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md).

## Comandos uteis

```bash
# Apos modificar componentes
php artisan cache:clear && php artisan view:clear && php artisan config:clear

# Publicar config / views / assets
php artisan vendor:publish --tag=theme-assets-config
php artisan vendor:publish --tag=theme-assets-views
php artisan vendor:publish --tag=theme-assets-errors
php artisan vendor:publish --tag=theme-assets-js
php artisan vendor:publish --tag=theme-assets-css
```

Mais comandos e cenarios em [docs/getting-started/installation.md](docs/getting-started/installation.md).

## Helpers globais (resumo)

```php
asset_cdn('css/foo.css')                   // URL completa do CDN
userTimezone($model->created_at)           // Data no fuso do usuario
userTimezoneAbbr()                          // 'BRT' (etc)
webspot_placeholder(200, 100)              // URL de imagem placeholder
```

Detalhes em [docs/backend/helpers.md](docs/backend/helpers.md).

## JS globals (resumo)

```js
WebSpotNotify.success('Salvo!');
WebSpotConfirm.show('id', () => { /* on confirm */ });
WebSpotLoading.show('#area');
```

Detalhes em [docs/frontend/js-globals.md](docs/frontend/js-globals.md).

## Trait obrigatoria no User

```php
use Webspot\ThemeAssets\Traits\HasWebSpotClients;

class User extends Authenticatable
{
    use HasWebSpotClients;
}
```

Sem isso, `<x-webspot-client-selector>` nao funciona. Outras traits em [docs/backend/traits.md](docs/backend/traits.md).

## Arquivos-chave

| Arquivo | Descricao |
|---------|-----------|
| `laravel-package/src/ThemeAssetsServiceProvider.php` | Entry point — registra 53 componentes, view composers, rotas |
| `laravel-package/src/config/theme-assets.php` | Configuracao principal (menu, produtos, CDN) |
| `laravel-package/src/config/webspot-ui.php` | Cores e icones (1030 linhas) |
| `laravel-package/src/resources/views/layouts/webspot.blade.php` | Layout principal |
| `laravel-package/src/resources/views/components/` | 53 componentes Blade |
| `laravel-package/src/Http/Controllers/` | ClientSelector, ProductSelector, Upload |
| `laravel-package/src/Traits/` | HasDataTable, HandlesPagination, ExportsData, HasWebSpotClients |
| `laravel-package/src/helpers.php` | Helpers globais: `asset_cdn()`, `userTimezone()`, `webspot_placeholder()` |
| `laravel-package/src/Services/HubProductsService.php` | Integracao com API do HUB |

## Links externos

- Documentacao publica: https://assets.webspot.com.br/
- Demo: https://assets.webspot.com.br/themes/webspot/default/demo.html
- **Vitrine de componentes**: https://assets.webspot.com.br/themes/webspot/default/showcase.html — todos os 53 componentes com preview, codigo copy-paste, props e contagem de adocao por produto