Evandro Fonseca Junior
d3704602fd
refactor(ai): enhance item structure generation with schema validation feat(ai): add token usage tracking and cost calculation fix(ui): improve item card number formatting with locale support docs(items): add documentation for item value separation test(items): add tests for value field validation
42 lines
1.9 KiB
Markdown
42 lines
1.9 KiB
Markdown
# Itens sem valores associados
|
|
|
|
Esta entidade (`Item`) foi projetada para armazenar somente dados estáticos do item (nome, categoria, atributos e metadados) e **não** deve conter qualquer informação de preço/valor. Valores de compra, venda, lance, histórico de preços e afins pertencem ao modelo `Listing`.
|
|
|
|
## Estrutura do Item (obrigatórios e opcionais)
|
|
|
|
- `item_name` (obrigatório): Nome do item.
|
|
- `category` (obrigatório): Categoria normalizada (ex.: `weapon`, `armor`, `helmet`, `accessory`, etc.).
|
|
- `image_local_path` (opcional)
|
|
- `image_url` (opcional)
|
|
- `rarity` (opcional)
|
|
- `level` (opcional)
|
|
- `weight` (opcional)
|
|
- `slots` (opcional)
|
|
- `skill` (opcional)
|
|
- `metadata` (opcional): Campos dinâmicos e específicos do item (atributos, servidores, tags, descrição). **Nunca inclua campos de valor aqui.**
|
|
|
|
## Validação contra campos de valor
|
|
|
|
Qualquer tentativa de incluir campos de valor/preço no `metadata` do item é **rejeitada** pela validação no servidor.
|
|
|
|
Chaves bloqueadas (exemplos):
|
|
|
|
- `price`, `prices`, `valor`, `value`, `sell_value`, `sellPrice`, `buy`, `buy_price`
|
|
- Chaves de `Listing`: `price_pix`, `price_tibia_coins`, `price_gold_coins`, `initial_price_*`, `current_bid_amount`
|
|
|
|
Mensagem retornada: _"Itens não possuem campos de valor/preço no cadastro. Use listings para preços."_
|
|
|
|
## Por que separar?
|
|
|
|
- Consistência: O mesmo item pode ter múltiplos anúncios com preços diferentes.
|
|
- Integridade: Evita confusão e mistura de responsabilidades entre `Item` e `Listing`.
|
|
- Evolução: Permite histórico de preços e leilões sem alterar o cadastro estático do item.
|
|
|
|
## Fluxo recomendado
|
|
|
|
1. **Cadastre o Item** com seus atributos e metadados (sem preços).
|
|
2. **Crie Listings** para anunciar o item com preço, quantidade, leilão, etc.
|
|
|
|
---
|
|
|
|
Documentação criada para clarificar que `Item` é livre de valores associados e que as funções de criação/atualização validam esse contrato. |