Cadastro de Item

Seis escolhas foram fechadas com o time e são premissa de tudo abaixo — a quinta revisada e a sexta acrescentada em 06/09/2026, a segunda alinhada às outras duas árvores do produto em 08/09/2026. Cada uma altera o documento anterior do Catálogo.

Sete agregados novos, um deles de configuração. O Item é o centro; tudo que varia por fornecedor, por categoria ou por operação fica fora dele.

O CostCenter não aparece no cadastro de item — a amarração contábil acontece na requisição, não no catálogo. Ver Impacto na aprovação.

O Item é dono de anexo desde 09/09/2026 (ownerType = Item): a evidência avulsa do cadastro — laudo, catálogo do fabricante, e-mail de especificação. Foto e ficha técnica continuam entidade do catálogo (ItemPhoto, ItemDocument), com perfil próprio no GrydFiles: arquivo com metadado seu é entidade de domínio, arquivo que é só prova é Attachment. As onze respostas do descritor estão declaradas na página do Anexo, em O dono polimórfico — este módulo implementa, não redecide.

Convenção de nomes. O documento é em português; os identificadores são em inglês — entidades, atributos, valores de enum, rotas, permissões e códigos de erro. A exceção são os dados de negócio brasileiros, que ficam como são no mundo real: identificadores fiscais (cnpj, cpf, primaryCnae), nomes de regime tributário (SimplesNacional, LucroReal), siglas de unidade (UN, CX, KG), tipos de certidão e os exemplos de taxonomia — esses são conteúdo, não código.

ItemType não é um enum: é entidade de configuração por tenant, seguindo o padrão do material type do SAP e do item model group do D365. O tipo dirige field selection — quais grupos de campos aparecem, quais são obrigatórios e o que o domínio recusa.

Campos do ItemType

Tipos-semente por tenant

Legenda de obrigatoriedade: obrig sempre · cond conforme ItemType ou categoria · opc opcional · gerado calculado pelo sistema.

Identificação

Classificação e descrição

Unidades e características físicas

Comercial

Recorrência — quando allowsRecurrence

Vigência real, data de renovação, aviso prévio e regra de reajuste não ficam no item — ficam no contrato e são copiados para a linha do pedido. A mesma licença tem vigências diferentes por fornecedor; renewalDate no item master é dado que nasce errado.

Política de compra

Ciclo de vida e controle

Coleções filhas

Fornecedores preferidos não são mais uma coleção do item — viraram o agregado ItemSupplier, com preço, prazo e status próprios.

Um único tipo, auto-relacionado por parentId. Nenhuma taxonomia de referência de compras tem dois níveis — UNSPSC, eCl@ss, GPC e CATMAT têm quatro; as spend taxonomies corporativas convergem em três a quatro. E nenhum produto pesquisado usa profundidade fixa: Ariba, Coupa, Dynamics e Oracle usam todos lista de adjacência.

A mecânica da árvore é a do Centro de Custo, revisada em 08/09/2026 para ser idêntica nas três árvores do produto: caminho materializado em texto, depth, duas portas de status com cascata assimétrica, move só por PATCH /parent com path como guarda, version como token e teto de profundidade como política do tenant. Nada disso depende do banco — a arquitetura ainda não o escolheu. O que distingue a categoria das outras duas árvores é a carga do nó: conta sugerida, NCM, tipo default, exigências regulatórias e esquema de atributos.

É o mecanismo que faz "parafuso precisa de bitola, rosca e material" e "notebook precisa de processador, RAM e tela" conviverem sem explodir a taxonomia. Quatro implementações independentes chegaram ao mesmo desenho — eCl@ss properties, SAP characteristics, Oracle attribute groups por item class e o PDM do CATMAT.

Definição do atributo

Vínculo categoria × atributo

categoria      FIXADORES › PARAFUSOS › SEXTAVADOS
basicName      PARAFUSO
atributos      tipo_cabeca   = Sextavado          (ordem 1)
               diametro      = M8                 (ordem 2, Measure)
               comprimento   = 40 mm              (ordem 3, Measure)
               material      = Aço inox 304       (ordem 4, List restritiva)
               rosca         = Parcial            (ordem 5, List restritiva)

standardDescription  →  "PARAFUSO SEXTAVADO M8 X 40MM AÇO INOX 304 ROSCA PARCIAL"
attributeSignature   →  sha256("PARAFUSO|7f3c…c1|comprimento=0.04:MT|diametro=0.008:MT
                                |material=INOX304|rosca=PARCIAL|tipo_cabeca=SEXTAVADO")

Esta é a seção que paga ou cobra no comparativo de cotações. Se o fornecedor A cota R$ 120 / CX(12 UN) e o B cota R$ 11 / UN, o comprador precisa ver R$ 10,00/UN vs R$ 11,00/UN sem calculadora.

Classes de unidade

ItemSupplier preserva o relacionamento de qualificação e preferência. ItemSupplierOffer identifica uma apresentação comercial versionada: o mesmo fornecedor pode vender caixa de 12, caixa de 24 e unidade avulsa simultaneamente. ItemSupplierPrice referencia a versão da oferta, com condição comercial e vigência próprias.

Resolver relação por estabelecimento exato e depois genérico; selecionar a oferta explicitamente; dentro dela, a condição comercial solicitada e o preço vigente. Prioridade total: empresa exata antes da genérica; dentro de cada uma, UF exata antes da genérica. Nunca consultar preço de outra empresa. Impedir cruzamento de vigência para a mesma oferta, empresa, UF e commercialConditionKey, com nulos equivalentes e trava de publicação.

Incoterm é condicional. Aplicável quando a compra de mercadoria adota regras Incoterms, com local nomeado e modal compatíveis. Serviço e assinatura podem ter incoterm nulo; frete doméstico declarado não é automaticamente FOB ou CIF internacional. O código não substitui os componentes do custo total. A ICC define regras para entrega de mercadorias; não são uma classificação universal de todo preço.

UF é um critério inicial de tabela, não a afirmação de que dois endereços na mesma cidade custam igual. Oferta/proposta deve explicitar frete e restrições para o destino real. Divergência entre condição genérica e destino impede tratar o valor como custo final. Contrato tem revisão e linha referenciadas; não sobrepõe silenciosamente preço ou quantidade de pedido emitido.

Código comercial identifica a oferta no fornecedor; ofertas alternativas podem compartilhar item e relação. Evitar duplicidade por fornecedor, estabelecimento, código, variante e identidade da oferta, permitindo revisões históricas. Referências de ERP usam ExternalReference de Contratos transacionais, e não um externalCode ambíguo. A linha do documento congela relação, oferta/revisão, preço, componentes, quantidade original, unidade, ambos os fatores e condições.

O Nexio é o lado do comprador: a maioria dos atributos fiscais não é dado que se cadastra, é dado que chega na nota. Cada campo abaixo está em um de três baldes.

Mercadorias — quando requiresGoodsTaxCode

Serviços — quando requiresServiceTaxCode

Reforma tributária — o único campo que nasce no comprador

O parser preserva IBS/CBS quando informados e tolera ausência conforme a versão vigente do leiaute e regras de autorização. A comunicação oficial de agosto de 2026 anunciou flexibilização; cronograma e obrigatoriedade não devem ser fixados a partir de uma data anterior. Cada integração registra versão do esquema e regra fiscal aplicada.

Regulatório — ItemCompliance e ItemDocument

Quase nada disso é "um campo no item". A regra de decisão: flag quando a política é universal e binária; atributo de categoria quando é específica de um tipo de produto; objeto com validade quando tem número, órgão emissor e vencimento; documento anexo quando o que importa é o arquivo.

ItemCompliance: kind, agency, registrationNumber, issuedAt, expiresAt, documentId? (continua apontando para ItemDocument, nunca para o arquivo), blocksPurchaseWhenExpired. Um job diário varre vencimentos e notifica os responsáveis pelo catálogo via GrydNotifications.

Três eixos ortogonais, seguindo a Oracle, que separa Status, Lifecycle Phase e Approval Status como atributos distintos. Colapsar os três num único enum é o erro que obriga a inventar estados como "ativo mas em revisão e bloqueado para pedido".

Eixo 1 — aprovação do cadastro

Eixo 2 — fase do ciclo de vida

Configurável por tenant (ItemLifecyclePhase). Fases-semente: New, Active, PhasingOut, Obsolete, Superseded. Fase não é status de aprovação nem bloqueio — é onde o item está na vida dele.

Eixo 3 — matriz processo × política

Cada fase declara, por processo, uma das três políticas do modelo do D365: permitido, aviso ou bloqueado.

Recebimento permanece permitido em todas as fases finais: bloquear o recebimento de um pedido legítimo já colocado transforma uma decisão de catálogo num problema operacional. E Superseded sempre exibe o successorItemId ao requisitante — bloquear sem oferecer alternativa gera compra fora do processo.

Seis camadas, três pontos de disparo. O modelo de dois limiares vem do SAP MDG: abaixo do limiar baixo nada é sinalizado; entre os dois, apresenta-se como candidato; no ou acima do alto, considera-se idêntico — e ainda assim se apresenta ao usuário, nunca se decide sozinho.

Prefixo api/v{version}/nexio. Todos exigem [Authorize] e uma permissão explícita via [RequirePermission]. Sucesso é 200, inclusive nos POST, seguindo o padrão já estabelecido no módulo Admin.

Item

Coleções do item

Configuração do catálogo

Listagem de itens — filtros e ordenação

Página padrão 20, teto 100, valores fora da faixa ajustados. sortBy inválido responde 400 SORT_FIELD_INVALID com a lista permitida na mensagem. includeDeleted=true é recusado. A busca cobre standardDescription, basicName, internalCode, externalCode, mpn, gtin e keywords. As DTOs resolvem nomes de fornecedor e de categoria pelo diretório — nunca devolvem só Guids.

Payload de erro: code, traceId e type, com mensagem resolvida em pt-BR, en e es-ES. Onde a tela precisa de dados para agir — lista de duplicatas, campos incompatíveis — ela consulta antes; o erro fica como guarda de corrida.

Padrão do produto, fechado em 08/09/2026 e revisto no fim do dia contra o código da plataforma: <verbo>:<recurso>[-<sub-recurso>] — verbo em kebab-case singular, recurso em kebab-case plural. O plural é de 09/09/2026 e alinha ao catálogo semeado do GrydAuth (read:users, update:tenants, create:permissions); até então o acervo inteiro estava no singular. Duas classes ficam no singular, porque não são coleção: o que nomeia o módulo (read:catalog — o tenant tem um catálogo, não N) e o que nomeia a trilha de auditoria (read:catalog-audit, read:supplier-audit — é uma trilha, não N auditorias). O PermissionCodeParser do GrydAuth lê o que vem antes do : como ação e monta o rótulo da tela de papéis quebrando em hífen, nunca em ponto — daí o sub-recurso com hífen. O recurso é declarado uma vez no controlador; o verbo vem do método HTTP por [AutoPermission] quando é CRUD, e é nomeado quando é ato de negócio (approve, import, clone). Um endpoint declara exatamente uma permissão; nada é implicado por outra.

Grupos sugeridos: Nexio - Catálogo (read/create/update/clone/import/export), Nexio - Curadoria de Catálogo (+ approve, category, attribute, itemtype, price) e Nexio - Consulta de Catálogo (read). Um teste compara o conjunto seedado pelo atributo com o exigido pelo [RequirePermission], como já é feito no módulo Admin.

É o maior gargalo de adoção: o cliente chega com uma planilha de dezenas de milhares de linhas de texto livre. O desenho abaixo assume isso.

O fluxo de aprovação é impactado por este cadastro em cinco pontos. Vale fixá-los agora, porque cada um é uma decisão que o motor de aprovação vai herdar pronta ou vai ter que improvisar.

A relação mantém suas rotas de status e preferência. Acrescentar consulta e publicação de /catalog/items/{id}/suppliers/{supplierItemId}/offers, com revisão, validade e expectedVersion. Preços são mantidos sob /offers/{offerId}/prices; a rota anterior de preços da relação é substituída por este contrato antes de implementar. manage:catalog-suppliers governa ofertas; manage:catalog-prices governa preços e componentes. Sem endpoints implementados nesta revisão documental.