# Implementação: Tabela de Itens do Pedido

## Visão Geral

Esta documentação descreve a implementação da funcionalidade que permite visualizar os itens (produtos) de um pedido em uma tabela separada abaixo da tabela principal de pedidos.

## Objetivo

Permitir que o usuário clique em um pedido na tabela principal e visualize todos os produtos/itens daquele pedido em uma tabela detalhada logo abaixo.

## Arquitetura

```mermaid
graph TD
    A[OrderTable] -->|onClick| B[selectedOrderId]
    B -->|prop| C[OrderItemsTable]
    C -->|usa| D[useOrderItems hook]
    D -->|chama| E[orderService.findOrderItems]
    E -->|GET| F[API: /api/v1/orders/itens/:id]
    F -->|retorna| G[orderItemsResponseSchema]
    G -->|valida| H[OrderItem[]]
    H -->|renderiza| I[OrderItemsTableColumns]
```

## Arquivos Criados

### 1. Schema de Validação

**Arquivo:** `src/features/orders/schemas/order.item.schema.ts`

Define a estrutura de dados dos itens do pedido usando Zod:

```typescript
export const orderItemSchema = z.object({
  productId: z.coerce.number(), // Código do produto
  description: z.string(), // Descrição
  pacth: z.string(), // Unidade de medida
  color: z.coerce.number(), // Código da cor
  stockId: z.coerce.number(), // Código do estoque
  quantity: z.coerce.number(), // Quantidade
  salePrice: z.coerce.number(), // Preço unitário
  deliveryType: z.string(), // Tipo de entrega
  total: z.coerce.number(), // Valor total
  weight: z.coerce.number(), // Peso
  department: z.string(), // Departamento
  brand: z.string(), // Marca
});
```

**Importante:** Usa `z.coerce.number()` para converter strings em números automaticamente, pois a API retorna valores numéricos como strings.

---

### 2. Serviço de API

**Arquivo:** `src/features/orders/api/order.service.ts` (linha 145)

Adiciona método para buscar itens do pedido:

```typescript
findOrderItems: async (orderId: number): Promise<OrderItem[]> => {
  try {
    const response = await ordersApi.get(`/api/v1/orders/itens/${orderId}`);
    return unwrapApiData(response, orderItemsResponseSchema, []);
  } catch (error) {
    console.error(`Erro ao buscar itens do pedido ${orderId}:`, error);
    return [];
  }
};
```

**Endpoint:** `GET /api/v1/orders/itens/{orderId}`

**Resposta esperada:**

```json
{
  "success": true,
  "data": [
    {
      "productId": 2813,
      "description": "TELHA ONDINA 2,44X50MM 4MM",
      "pacth": "UN",
      "color": null,
      "stockId": 12,
      "quantity": 1,
      "salePrice": 25.99,
      "deliveryType": "ENTREGA",
      "total": 25.99,
      "weight": null,
      "department": "MATERIAIS DE CONSTRUCAO",
      "brand": "BRASILIT"
    }
  ]
}
```

---

### 3. Hook React Query

**Arquivo:** `src/features/orders/hooks/useOrderItems.ts`

Gerencia o estado e cache dos itens:

```typescript
export function useOrderItems(orderId: number | null | undefined) {
  return useQuery({
    queryKey: ['orderItems', orderId],
    enabled: orderId != null && orderId > 0,
    queryFn: () => orderService.findOrderItems(orderId!),
    staleTime: 1000 * 60 * 5, // Cache de 5 minutos
    retry: 1,
    retryOnMount: false,
    refetchOnWindowFocus: false,
  });
}
```

**Características:**

- Cache de 5 minutos
- Só executa quando há `orderId` válido
- Retry automático (1 tentativa)
- Não refaz requisição ao focar janela

---

### 4. Definição de Colunas

**Arquivo:** `src/features/orders/components/OrderItemsTableColumns.tsx`

Define 12 colunas para a tabela:

| Campo          | Cabeçalho      | Tipo   | Agregável | Formatação         |
| -------------- | -------------- | ------ | --------- | ------------------ |
| `productId`    | Cód. Produto   | number | Não       | -                  |
| `description`  | Descrição      | string | Não       | -                  |
| `pacth`        | Unidade        | string | Não       | Centralizado       |
| `color`        | Cor            | number | Não       | Centralizado       |
| `stockId`      | Cód. Estoque   | number | Não       | -                  |
| `quantity`     | Qtd.           | number | Sim       | `formatNumber()`   |
| `salePrice`    | Preço Unitário | number | Não       | `formatCurrency()` |
| `total`        | Valor Total    | number | Sim       | `formatCurrency()` |
| `deliveryType` | Tipo Entrega   | string | Não       | -                  |
| `weight`       | Peso (kg)      | number | Sim       | `formatNumber()`   |
| `department`   | Departamento   | string | Não       | -                  |
| `brand`        | Marca          | string | Não       | -                  |

**Agregação:** Colunas marcadas com "Sim" suportam totalização automática.

---

### 5. Componente da Tabela

**Arquivo:** `src/features/orders/components/OrderItemsTable.tsx`

Componente principal que renderiza a tabela de itens:

```typescript
interface OrderItemsTableProps {
  orderId: number;
}

export const OrderItemsTable = ({ orderId }: OrderItemsTableProps) => {
  const { data: items, isLoading, error } = useOrderItems(orderId);
  // ... renderização
};
```

**Estados:**

- **Loading:** Exibe spinner + mensagem "Carregando itens..."
- **Erro:** Exibe Alert vermelho com mensagem de erro
- **Vazio:** Exibe Alert azul "Nenhum item encontrado"
- **Sucesso:** Renderiza DataGrid com os itens

---

### 6. Integração na Tabela Principal

**Arquivo:** `src/features/orders/components/OrderTable.tsx`

**Mudanças realizadas:**

#### a) Estado para pedido selecionado

```typescript
const [selectedOrderId, setSelectedOrderId] = useState<number | null>(null);
```

#### b) Handler de clique na linha

```typescript
onRowClick={(params) => {
  const orderId = params.row.orderId;
  setSelectedOrderId(orderId === selectedOrderId ? null : orderId);
}}
```

#### c) Classe CSS para linha selecionada

```typescript
getRowClassName={(params) =>
  params.row.orderId === selectedOrderId ? 'Mui-selected' : ''
}
```

#### d) Estilo visual da linha selecionada

```typescript
'& .MuiDataGrid-row.Mui-selected': {
  backgroundColor: 'primary.light',
  '&:hover': {
    backgroundColor: 'primary.light',
  },
},
```

#### e) Renderização condicional da tabela de itens

```typescript
{selectedOrderId && <OrderItemsTable orderId={selectedOrderId} />}
```

## Fluxo de Execução

1. **Usuário clica** em uma linha da tabela de pedidos
2. **`onRowClick`** captura o evento e atualiza `selectedOrderId`
3. **`getRowClassName`** adiciona classe `Mui-selected` à linha
4. **CSS** aplica `backgroundColor: 'primary.light'` na linha
5. **Renderização condicional** monta `<OrderItemsTable orderId={selectedOrderId} />`
6. **`useOrderItems`** hook é ativado (enabled: true)
7. **React Query** executa `queryFn` → `orderService.findOrderItems(orderId)`
8. **API** retorna dados: `{ success: true, data: [...] }`
9. **Zod** valida com `orderItemsResponseSchema`
10. **`unwrapApiData`** extrai array de itens
11. **DataGrid** renderiza tabela com os dados

## Problemas Encontrados e Soluções

### Problema 1: "Nenhum item encontrado"

**Sintoma:** Mesmo com dados na API, a mensagem "Nenhum item encontrado" aparecia.

**Causa:** A API retorna campos numéricos como strings (`"123"` ao invés de `123`), mas o schema Zod esperava `number`.

**Solução:** Usar `z.coerce.number()` em todos os campos numéricos:

```diff
- productId: z.number(),
+ productId: z.coerce.number(),
```

**Resultado:** Validação passa e dados são convertidos automaticamente.

---

### Problema 2: Nomes de colunas genéricos

**Sintoma:** Colunas com nomes pouco descritivos ("Código", "Lote").

**Solução:** Renomear baseado nos dados reais:

- `Código` → `Cód. Produto`
- `Lote` → `Unidade` (campo contém unidade de medida)
- `Estoque` → `Cód. Estoque`
- `Quantidade` → `Qtd.`
- `Preço Unit.` → `Preço Unitário`
- `Total` → `Valor Total`

## Estilização

### Cabeçalho da Tabela

```typescript
'& .MuiDataGrid-columnHeaders': {
  backgroundColor: 'grey.50',
  fontWeight: 600,
  fontSize: '0.75rem',
  borderBottom: '2px solid',
  borderColor: 'divider',
}
```

### Linhas

```typescript
'& .MuiDataGrid-row': {
  minHeight: '36px !important',
  maxHeight: '36px !important',
  cursor: 'pointer',
}

'& .MuiDataGrid-row:nth-of-type(even)': {
  backgroundColor: 'grey.50', // Zebra striping
}
```

### Células

```typescript
'& .MuiDataGrid-cell': {
  fontSize: '0.75rem',
  lineHeight: 1.2,
  borderRight: '1px solid',
  borderColor: 'divider',
}
```

## Exemplo de Uso

```typescript
// Pedido 9998034076 retorna:
{
  "success": true,
  "data": [
    {
      "productId": 2813,
      "description": "TELHA ONDINA 2,44X50MM 4MM",
      "pacth": "UN",
      "quantity": 1,
      "salePrice": 25.99,
      "total": 25.99,
      "department": "MATERIAIS DE CONSTRUCAO",
      "brand": "BRASILIT"
    }
  ]
}
```

**Resultado na tabela:**

| Cód. Produto | Descrição                  | Unidade | Qtd. | Preço Unitário | Valor Total | Departamento            | Marca    |
| ------------ | -------------------------- | ------- | ---- | -------------- | ----------- | ----------------------- | -------- |
| 2813         | TELHA ONDINA 2,44X50MM 4MM | UN      | 1    | R$ 25,99       | R$ 25,99    | MATERIAIS DE CONSTRUCAO | BRASILIT |

## Checklist de Implementação

- [x] Criar schema de validação (`order.item.schema.ts`)
- [x] Adicionar método na API (`orderService.findOrderItems`)
- [x] Criar hook React Query (`useOrderItems.ts`)
- [x] Definir colunas da tabela (`OrderItemsTableColumns.tsx`)
- [x] Criar componente da tabela (`OrderItemsTable.tsx`)
- [x] Integrar na tabela principal (`OrderTable.tsx`)
- [x] Adicionar estado de seleção
- [x] Implementar visual feedback
- [x] Corrigir validação de schema (coerce)
- [x] Renomear colunas para nomes descritivos
- [x] Testar com dados reais
- [x] Documentar implementação

## Próximas Melhorias

- [ ] Adicionar exportação para Excel/CSV
- [ ] Incluir imagens dos produtos
- [ ] Adicionar filtros na tabela de itens
- [ ] Mostrar histórico de alterações
- [ ] Adicionar ações (editar, remover)
- [ ] Implementar paginação server-side
- [ ] Adicionar busca/filtro por produto
- [ ] Mostrar estoque disponível em tempo real

## Referências

- [React Query Documentation](https://tanstack.com/query/latest)
- [Zod Documentation](https://zod.dev/)
- [MUI DataGrid Premium](https://mui.com/x/react-data-grid/)
- [Axios Documentation](https://axios-http.com/)
