Gerar Documentação

Use este guia para gerar documentações padronizadas usando IA. Basta copiar o template abaixo e colar no seu prompt, preenchendo os campos solicitados.

Sobre a imagem (passo a passo)

A imagem mostra o fluxo sugerido para gerar a documentação com IA:

1. Selecione a pasta do projeto como contexto
   • Aponte para o repositório onde o componente está (ex.: force-web, force-mobile ou communication-server).
   • O contexto ajuda a IA a entender pastas, arquivos e nomenclaturas.
2. Ative o Modo Agente e escolha o modelo
   • Habilite o modo agente para permitir que a IA execute ações e navegue melhor pelo contexto.
   • Selecione o modelo desejado (qualquer LLM compatível com o seu fluxo interno).
3. Cole o template (abaixo) e preencha os campos ticket e título
   • Inclua detalhes suficientes do ticket e do que foi alterado/implementado.
4. Execute a geração
   • A IA irá propor o conteúdo da documentação com base no contexto e no template.

O que será gerado

• Um arquivo .md com título, metadados e seções padronizadas.
• Tabelas e exemplos conforme o template.
• Referências a arquivos e trechos de código quando disponíveis no contexto.

Como colocar a documentação neste projeto (vidya-docs)

Siga estes passos para versionar e publicar aqui o arquivo gerado:

1. Defina o local correto
   • Force Web: docs/force-web/ (ou docs/force-web/customizacoes-clientes/ para conteúdos por cliente)
   • Force Mobile: docs/force-mobile/
   • Communication Server: docs/communication-server/
   • Tutoriais (conteúdo genérico como este): docs/tutoriais/
2. Nomeie o arquivo em kebab-case
   • Ex.: comissao-vendedor-representante.md.
3. Imagens
   • Coloque em static/img/<area>/<assunto>/....
   • Referencie no Markdown com caminho absoluto: /img/<area>/<assunto>/arquivo.png.
4. Sidebar e ordenação
   • A sidebar é autogerada. Para ordenar dentro da pasta, use sidebar_position no frontmatter.
   • Para rotular pastas, crie/edite _category_.json na pasta correspondente.
5. Revisão
   • Verifique links, títulos e datas.
   • Garanta que os nomes de arquivos e caminhos existem neste repositório.

Dica: mantenha o frontmatter simples (ex.: title, description, sidebar_position) e evite caracteres especiais no nome do arquivo.

Template para copiar e colar no prompt

Copie tudo entre as linhas abaixo e cole na IA de sua preferência. Substitua os valores entre parênteses angulares.

Faça a documentação desse componente, crie um arquivo md na pasta de contexto.

ticket: <Link do ticket>
titulo: <Nome do ticket ou funcionalidade>

## siga como exemplo essa formatação

## sidebar_position: 1

# Comissão Vendedor/Representante

> **Ticket:** [FORCEWEB-1244](https://vidyacode.atlassian.net/browse/FORCEWEB-1244)
> **Última atualização:** 18 de setembro de 2025

## Visão Geral

Sistema personalizado de cálculo de comissão para a empresa **Lubrilages**, implementando regras diferenciadas conforme o perfil do vendedor e valores praticados na venda. A solução contempla dois tipos de vendedores com cálculos específicos e apresentação visual das comissões tanto por produto quanto no total do pedido.

### Tipos de Vendedor Suportados

| Tipo                      | Código CODFORM | Descrição                              |
| ------------------------- | -------------- | -------------------------------------- |
| **CLT**                   | 4              | Vendedor interno com carteira assinada |
| **Representante Externo** | 1              | Vendedor autônomo/representante        |

## Configuração de Campos

### Campos na Empresa (TGFEMP)

| Campo                            | Descrição                            | Tabela | Uso                                           |
| -------------------------------- | ------------------------------------ | ------ | --------------------------------------------- |
| `AD_DIVISAO_COMISSAO_REPRESENTE` | Percentual do Comissão Representante | TGFEMP | Define divisão entre vendedor interno/externo |
| `AD_COMISSAOMENOR`               | Percentual Comissão Mínima Menor     | TGFEMP | Comissão mínima para vendedores CLT           |
| `AD_COMISSAOMINIMA`              | Percentual Comissão Mínima           | TGFEMP | Comissão mínima para representantes           |
| `AD_COMISSAOMAXIMA`              | Percentual Comissão Máxima           | TGFEMP | Limite máximo de comissão                     |
| `AD_PRECOMAXIMO`                 | Percentual Preço Máximo              | TGFEMP | Limite para aplicação da comissão máxima      |

### Campos no Produto (TGFPRO)

| Campo              | Descrição           | Tabela | Uso                               |
| ------------------ | ------------------- | ------ | --------------------------------- |
| `COMVEND`          | % Comissão Vendedor | TGFPRO | Comissão base para representantes |
| `AD_COMISSAOMENOR` | Comissão Menor      | TGFPRO | Comissão base para vendedores CLT |

### Campos do Usuário (TSIUSU)

| Campo     | Descrição                  | Uso                                         |
| --------- | -------------------------- | ------------------------------------------- |
| `CODFORM` | Código do Tipo de Vendedor | Identifica o perfil: 1=Representante, 4=CLT |

---

## Arquivos Modificados

| Arquivo                                    | Localização             | Responsabilidade                           |
| ------------------------------------------ | ----------------------- | ------------------------------------------ |
| `price.products.sale.create.controller.ts` | Controllers             | Lógica principal do cálculo de comissão    |
| `index.tsx`                                | Components/ProductModal | Exibição da comissão por produto           |
| `FooterBar.tsx`                            | Components/Footer       | Exibição do total de comissão no rodapé    |
| `product.types.ts`                         | Types                   | Tipagem para campos de comissão do produto |
| `user.types.ts`                            | Types                   | Tipagem para campo CODFORM do usuário      |
| `login.service.ts`                         | Services                | Mapeamento do tipo de vendedor             |
| `permission.ts`                            | Utils                   | Verificação de permissão Lubrilages        |

---

## Algoritmo de Cálculo

### Fluxograma de Decisão

```mermaid
graph TD
    A[Início do Cálculo] --> B{Tipo de Vendedor}
    B -->|CODFORM = 4| C[Vendedor CLT]
    B -->|CODFORM = 1| D[Representante Externo]

    C --> F{Preço de Venda}
    F -->|≤ Preço Mínimo| G[Comissão = AD_COMISSAOMENOR empresa]
    F -->|≥ Preço Tabela| H[Comissão = AD_COMISSAOMENOR produto]
    F -->|Valor Intermediário| I[Regra de 3 Proporcional]

    D --> J{Preço de Venda}
    J -->|≤ Preço Mínimo| K[Comissão = AD_COMISSAOMINIMA]
    J -->|≥ Preço Tabela| L[Comissão = COMVEND]
    J -->|Valor Intermediário| M[Regra de 3 Proporcional]

    G --> N[Aplicar Limite Máximo]
    H --> N
    I --> N
    K --> N
    L --> N
    M --> N
    N --> P[Resultado Final]

### Fórmulas de Cálculo

#### Para Vendedores CLT (CODFORM = 4)

```typescript
if (precoVenda <= precoMinimo) {
  comissao = ad_comissaoMenor; ntual Comissão Mínima Menor (empresa)
} else if (precoVenda >= precoTabela) {
  comissao = AD_COMISSAOMENOR; são Menor (produto)
} else {
   de três proporcional
  comissao =
    ad_comissaoMenor +
    ((precoVenda - precoMinimo) Tabela - precoMinimo)) *
      (AD_COMISSAOMENOR - ad_comissaoMenor);
}
```

#### Para Representantes Externos (CODFORM = 1)

```typescript
if (precoVenda <= precoMinimo) {
  comissao = ad_comissaoMinima; ntual Comissão Mínima (empresa)
} else if (precoVenda >= precoTabela) {
  comissao = COMVEND; issão Vendedor (produto)
} else {
   de três proporcional
  comissao =
    ad_comissaoMinima +
    ((precoVenda - precoMinimo) Tabela - precoMinimo)) *
      (COMVEND - ad_comissaoMinima);
}
```

#### Aplicação de Limite Máximo

```typescript
const precoMaximo = precoTabela * (1 + ad_precoMaximo
if (precoVenda >= precoMaximo) {
  comissao = ad_comissaoMaxima;
} else {
  comissao = Math.min(comissao, ad_comissaoMaxima);
}
```

---

## Implementação Técnica

### Função Principal de Cálculo

<details>
<summary>calculateCommissionLubrilages - Código Completo</summary>

```typescript
ollers/sale/create/products/price.products.sale.create.controller.ts

const calculateCommissionLubrilages = (
  product: Product,
  header: any
): { valorComissao: number; percentage: number } => {
  const user = useSelector(getUser);
  const CODFORM = Number(user?.CODFORM); LT, 1 = Representante

  s do produto
  const AD_COMISSAOMENOR = product?.AD_COMISSAOMENOR || 0;
  const COMVEND = product?.COMVEND || 0;

  s da empresa
  const ad_comissaoMenor = Number(header?.CODEMP?.ad_comissaoMenor ?? "0") || 0;
  const ad_comissaoMinima =
    Number(header?.CODEMP?.ad_comissaoMinima ?? "0") || 0;
  const ad_comissaoMaxima =
    Number(header?.CODEMP?.ad_comissaoMaxima ?? "0") || 0;
  const ad_precoMaximo = Number(header?.CODEMP?.ad_precoMaximo ?? "0") || 0;

  es do produto
  const precoTabela = Number(product?.VLRUNIT) || 0;
  const precoMinimo = Number(product?.VLRUNIT) || 0;
  const precoVenda =
    Number(product?.VLRUNIT) + Number(product?.VLRDESC ?? "0") || 0;
  const QTDNEG = Number(product?.QTDNEG) || 0;

  let comissaoCalculada = 0;

  lo para CLT
  if (CODFORM === 4) {
    if (precoVenda <= precoMinimo) {
      comissaoCalculada = ad_comissaoMenor;
    } else if (precoVenda >= precoTabela) {
      comissaoCalculada = AD_COMISSAOMENOR;
    } else {
      comissaoCalculada =
        ad_comissaoMenor +
        ((precoVenda - precoMinimo) Tabela - precoMinimo)) *
          (AD_COMISSAOMENOR - ad_comissaoMenor);
    }
  }

  lo para Representante
  if (CODFORM === 1) {
    if (precoVenda <= precoMinimo) {
      comissaoCalculada = ad_comissaoMinima;
    } else if (precoVenda >= precoTabela) {
      comissaoCalculada = COMVEND;
    } else {
      comissaoCalculada =
        ad_comissaoMinima +
        ((precoVenda - precoMinimo) Tabela - precoMinimo)) *
          (COMVEND - ad_comissaoMinima);
    }
  }

  ação do limite máximo
  const precoMaximo = precoTabela * (1 + ad_precoMaximo   if (precoVenda >= precoMaximo) {
    comissaoCalculada = ad_comissaoMaxima;
  } else {
    comissaoCalculada = Math.min(comissaoCalculada, ad_comissaoMaxima);
  }

   da comissão em R$
  const valorComissao = (comissaoCalculada  precoVenda;

  return {
    percentage: Number(comissaoCalculada?.toFixed(2)),
    valorComissao: Number((valorComissao * QTDNEG)?.toFixed(2)),
  };
};
```

</details>

### Exibição no Interface

#### Modal do Produto

```tsx
creens /
  catalogo /
  components /
  ProductModal /
  components /
  Tabs /
  BusinessRulesTab /
  index.tsx;

const comissionisLubrilages = useSelector(
  getValueCommissionLubrilages(product?.CODPROD)
);

{
  permission?.permissionByCompany?.isLubrilages() &&
    !!comissionisLubrilages &&
    renderInfomation(
      "Comissão",
      formatMoney(comissionisLubrilages?.valorComissao ?? "0")
    );
}
```

#### Rodapé do Pedido

```tsx
creens / nova - venda / components / Footer / Bar / FooterBar.tsx;

const totalValueCommissionLubrilages = useSelector(
  getValueTotalCommissionLubrilages
);

{
  permission?.permissionByCompany?.isLubrilages() && (
    <div className="flex gap-2 justify-start items-center">
      <p className="text-lg font-medium text-[#4e4a52]">Comissão:</p>
      <p className="text-lg font-semibold text-[#009353]">
        R$ {formatMoney(totalValueCommissionLubrilages, 2)}
      </p>
    </div>
  );
}
```

---

## Exemplos Práticos

### Cenário: Produto 4746

Configurações do exemplo:

- **Preço de Tabela:** R$ 968,10
- **Preço Mínimo:** R$ 943,89
- **Comissão Menor (CLT):** 0,60%
- **Comissão Mínima Menor (CLT):** 0,40%
- **% Comissão Vendedor (Representante):** 2,90%
- **Comissão Mínima (Representante):** 1,50%

#### Vendedor CLT

| Preço de Venda            | Cálculo                                                               | Comissão Final |
| ------------------------- | --------------------------------------------------------------------- | -------------- |
| R$ 943,89 (mínimo)        | Comissão mínima                                                       | **0,40%**      |
| R$ 950,00 (intermediário) | Regra de três: 0,40% + [(950-943,89)/(968,10-943,89)] × (0,60%-0,40%) | **≈ 0,45%**    |
| R$ 968,10 (tabela)        | Comissão do produto                                                   | **0,60%**      |

#### Representante Externo

| Preço de Venda            | Cálculo                                                               | Comissão Final |
| ------------------------- | --------------------------------------------------------------------- | -------------- |
| R$ 943,89 (mínimo)        | Comissão mínima                                                       | **1,50%**      |
| R$ 950,00 (intermediário) | Regra de três: 1,50% + [(950-943,89)/(968,10-943,89)] × (2,90%-1,50%) | **≈ 1,85%**    |
| R$ 968,10 (tabela)        | Comissão do produto                                                   | **2,90%**      |

:::tip[Regra de Três Proporcional]
A fórmula utilizada para preços intermediários:

```
comissao = comissaoMinima +
  ((precoVenda - precoMinimo) precoTabela - precoMinimo)) ×
  (comissaoMaxima - comissaoMinima)
```

:::

### Limites de Comissão

#### Exemplo de Configuração

- **Comissão Máxima:** 35%
- **Preço Máximo:** 170% (do preço de tabela)

| Situação         | Preço de Venda                | Comissão Aplicada     |
| ---------------- | ----------------------------- | --------------------- |
| Dentro do limite | Até 170% do preço tabela      | Calculada normalmente |
| Acima do limite  | Acima de 170% do preço tabela | **Limitada a 35%**    |

:::warning[Atenção]
Os valores de **Comissão Máxima** e **Preço Máximo** podem ser alterados a qualquer momento via configuração no Sankhya.
:::

---

## Divisão de Comissão Interna

### Regra de Divisão 80/20

Para vendedores internos, a comissão total é dividida conforme os percentuais configurados:

| Destinatário         | Percentual Padrão | Campo de Configuração                      |
| -------------------- | ----------------- | ------------------------------------------ |
| **Vendedor Interno** | 80%               | `AD_DIVISAO_COMISSAO_REPRESENTE`           |
| **Vendedor Externo** | 20%               | Calculado automaticamente (100% - interno) |

:::note[Configuração Flexível]
Os percentuais de divisão podem ser alterados via campos específicos na aba Comissão da tela de Empresa no Sankhya.
:::

---

## Controle de Permissões

### Verificação Lubrilages

```typescript
/permission.ts
isLubrilages = () =>
  this?.baseImage?.includes?.("187.72.81.210:8080") ||
  this?.baseUrl?.includes?.("lubrilages");
```

## Integração com Redux

### Seletores Utilizados

```typescript
issão individual por produto
const comissionisLubrilages = useSelector(
  getValueCommissionLubrilages(product?.CODPROD)
);

al de comissão do pedido
const totalValueCommissionLubrilages = useSelector(
  getValueTotalCommissionLubrilages
);
```

---

## Tipagem TypeScript

### Interface do Produto

```typescript
/product/product.types.ts
export interface Product {
  pos básicos
  VLRUNIT?: number; ço unitário
  VLRDESC?: number; or do desconto
  QTDNEG?: number; ntidade negociada
  CODPROD?: string; igo do produto

  pos para comissão
  COMVEND?: number; omissão Vendedor (representantes)
  AD_COMISSAOMENOR?: number; issão Menor (CLT)
}
```

### Interface do Usuário

```typescript
/user/user.types.ts
export type User = {
  mpos existentes...
  CODFORM?: string; o do tipo de vendedor
};

export interface IUserData {
  mpos existentes...
  CODFORM?: string; o do tipo de vendedor
}
```

### Interface de Retorno da Função

```typescript
interface CommissionResult {
  valorComissao: number;  em R$ da comissão
  percentage: number; ntual de comissão aplicado
}
```

---

## Mapeamento de Dados

### Login Service

```typescript
ervice / auth / login.service.ts;
export function mapUserDataToUser(userData: IUserData): User {
  return {
    // ...campos existentes...
    CODFORM: userData?.CODFORM, // Mapeia tipo de vendedor
  };
}
```

---

## Observações

- A imagem acima está disponível em `/static/img/tutorial/gerar-documentacao/1.png` e é servida via `/img/tutorial/gerar-documentacao/1.png`.
- Caso precise de outro exemplo, crie novos arquivos `.md` dentro de `docs/tutoriais/` seguindo o mesmo padrão de frontmatter.

```

```