---
name: estoque-inventory
description: Gerencia o inventário do mini-ERP Estoque — listar/buscar itens, criar/editar, ajustar quantidade, sinalizar estoque baixo e somar totais via a API REST local.
version: 1.0.0
platforms: [linux, macos]
metadata:
  hermes:
    tags: [inventory, erp, rest-api, estoque]
    category: business
    requires_toolsets: [terminal]
    config:
      - key: estoque.api_url
        description: URL base da API do Estoque
        default: http://localhost:3001
---

# Estoque — gestão de inventário

Permite operar o mini-ERP **Estoque** (API Go + SQLite puro-Go via
`modernc.org/sqlite`) por linguagem natural. Toda chamada à API passa pelo wrapper
`scripts/estoque.sh` — **nunca monte `curl` à mão**. O script lê a env var
`ESTOQUE_API_URL` (default `http://localhost:3001`) e sempre devolve JSON no stdout;
erros vão para o stderr no formato `{"error":"..."}` com código de saída ≠ 0.

## Quando usar

Use esta skill quando o usuário quiser consultar ou mexer no estoque: listar/buscar
itens, ver detalhes, cadastrar produto, editar dados, ajustar quantidade (entrada/
saída), ver o que está com estoque baixo, ou pedir totais (itens, unidades, valor).

## Pré-requisito

A API precisa estar no ar (porta 3001). Verifique com `estoque.sh health` →
`{"ok":true,...}`. Se falhar, oriente o usuário a subir o servidor:
`cd server && go run .` (requer Go 1.25+).

## Modelo do item

`id`, `sku`, `name`, `description`, `category`, `unit` (default `un`), `cost_price`,
`price`, `quantity`, `min_stock`, `created_at`, `updated_at`.

Regras importantes:
- `name` é **obrigatório**; `cost_price`/`price`/`quantity`/`min_stock` **não podem
  ser negativos**.
- O `sku` é **gerado e imutável no servidor** (ex.: `FER-000001`, prefixo de 3 letras
  da categoria) — nunca envie `sku` em create/update.
- **Estoque baixo** = `quantity <= min_stock`.

## Comandos (`scripts/estoque.sh`)

| Comando | Ação |
|---|---|
| `health` | Healthcheck da API |
| `list [busca]` | Lista itens; `busca` filtra por nome/sku/categoria |
| `get <id>` | Detalhe de um item |
| `create` | Cria item — **corpo JSON via stdin** |
| `update <id>` | Edita item — **corpo JSON via stdin** (sem `sku`) |
| `adjust <id> <delta>` | Soma `delta` à quantidade (negativo = saída) |
| `setqty <id> <quantity>` | Define quantidade absoluta |
| `delete <id>` | Remove item |
| `low-stock` | Itens com `quantity <= min_stock` |
| `summary` | Totais: itens, unidades, valor do estoque, nº em baixo estoque |

## Exemplos

```bash
# Buscar
scripts/estoque.sh list parafuso

# Cadastrar (SKU é gerado pelo servidor)
echo '{"name":"Parafuso 4mm","category":"Ferragens","unit":"cx","cost_price":1.2,"price":2.5,"quantity":100,"min_stock":10}' \
  | scripts/estoque.sh create

# Entrada de 50 unidades / saída de 3 unidades
scripts/estoque.sh adjust 7 50
scripts/estoque.sh adjust 7 -3

# Editar dados (mantém o SKU)
echo '{"name":"Parafuso 4mm zincado","category":"Ferragens","unit":"cx","cost_price":1.3,"price":2.9,"quantity":147,"min_stock":20}' \
  | scripts/estoque.sh update 7

# Visões agregadas
scripts/estoque.sh low-stock
scripts/estoque.sh summary
```

## Boas práticas

- Antes de `update`, faça `get <id>` para preservar os campos que o usuário não quer
  mudar (o PUT substitui todos os dados editáveis do item).
- Para entrada/saída de mercadoria prefira `adjust` (relativo) a `setqty` (absoluto).
- Ao criar/editar, confirme valores numéricos não-negativos; o servidor rejeita com
  `{"error":"..."}` em português — repasse a mensagem ao usuário.
- Detalhes completos de endpoints e validação em `references/api.md`.