Índice
maxLevel 2

Objetivo

Propor e definir um padrão de documentação para o PDVSync, considerando integração com o PDV, organização clara dos dados e alinhamento entre os times envolvidos.

Descrição

Atualmente, a documentação do PDVSync apresenta problemas de fluidez e clareza, especialmente em relação às diferentes versões existentes e à integração com tabelas do PDV. Por vezes, dados relacionados a tabelas distintas do PDV são tratados na mesma API do Sync, o que resulta em descentralização de informações e dificuldade de uso.

...

• APIs Online:
  • Fluxos de dados em tempo real entre o PDV e a retaguarda.
• Baixa de Dados:
  • Processos de transferência de informações da retaguarda para o PDV.
• Envio de Dados:
  • Processos de envio de informações do PDV para a retaguarda.
• As etapas incluem:
  • Criação dos modelos
    • Desenvolver propostas claras e organizadas para documentar os três fluxos mencionados, integrando informações relacionadas às tabelas do PDV de forma centralizada.
  • Comparação com a documentação atual do Sync
    • Avaliar os modelos propostos em relação à documentação existente, identificando melhorias necessárias.
  • Alinhamento entre times
    • Compartilhar os modelos com os times PDV e Sync, promovendo uma discussão colaborativa para chegar a um consenso sobre o padrão mais eficiente.
  • Unificação ou independência
    • Decidir, em conjunto, se a documentação do Sync será unificada com a documentação do PDV ou seguirá um modelo independente.

...

Em discussões identificamos até o momento duas soluções de como resolver este problema, conforme descritas abaixo.

Soluções

Solução 1 - Documentação separada: PDVSync 

• Primeira versão criada de documentação PDVSync: Microserviços - TOTVS Varejo PDV Omni - TDN . Nesta documentação como pode ser vista é focada apenas no PDVSync abordando os seguintes pontos:
  • Como implementar a integração
  • O que é e detalhes dos Microsserviços
  • APIs separadas por microsserviços
  • APIs com detalhes de seus métodos (POST, GET, PUT, DELETE e PATCH)
  • Payloads detalhados com seus tipos (Tabelas com tipos de campos, limites de caracteres, versões, etc...)
  • Detalhe do retorno esperado para sucesso (200 ok) e erro (400 Bad Request) 
  • Englobanco o processo offline e online
  • Troubleshooting

• Modelo 1 →
• Image Added

Critérios de Aceite

• Modelos de documentação elaborados para os três fluxos principais:
  • APIs Online.
  • Baixa de Dados.
  • Envio de Dados.
• Comparação estruturada entre os novos modelos e a documentação atual do Sync, com registro das melhorias propostas.
• Reunião realizada com os times PDV e Sync, com feedback documentado e consenso sobre o melhor modelo.
• Definição clara sobre unificação ou independência da documentação do Sync em relação ao PDV.
• Entrega de um documento consolidado com o padrão aprovado e plano de implementação.

...

• ✅ Vantagens:
  • ✔ Liberdade para estruturação da documentação - Sem depender de como a documentação do PDV esta disposta.
  • ✔ Maior visibilidade para desenvolvedores externos – Facilita o acesso para parceiros, startups e integradores focado na integração.
  • ✔ Facilidade de versionamento – É mais fácil gerenciar e documentar versões diferentes da API sem interferir no produto.
• ❌ Desvantagens:
  • ✖ Pode gerar desconexão do produto – Se não houver sincronização eficiente, a documentação pode ficar desatualizada em relação ao produto.
  • ✖ Exige manutenção separada – A equipe pode precisar de um esforço adicional para manter a documentação alinhada com as mudanças do produto.
• Modelo 1 →
• Image Removed
  • ✔ Nessa documentação estamos conseguimos separar os envios conforme os micros serviços
  • ✔ Demonstrar estrutura do PDVSync e seu funcionamento
  • ✔ ProcessosDescida de dados
  • Subida de dados
  • Processo Online
  • Consultas específicas LojaLoteRetorno (GET)
  • Integração de nova Loja
  • Entre outros
  • ✔ Troubleshooting
  • ✔ Instalação do Sync

Pontos de Melhoria

• Necessidade de atrelar essa doc na documentação do PDV para ter de referência
• Melhorar algumas informações em ordem de prioridade
  • Precisamos realmente de tantas abas na interface principal do produto?
  • Dificuldade de instruir o usuario com tantas informações logo de cara
    • Baixa
    • Envio
    • Online
• Ajustes no modelo da doc das API's
  • Adicionar campos do PDV?
  • Adicionar as informações referentes a v3 de forma clara
  • centralizar todos os tipos de Dados existentes em apenas um lugar
  • Melhor descrição das API's, para que serve e a sua relação entre elas
    • Exemplo: ProcessoOnline com fluxos dependentes que não são claros NotaEntrada + NotaSaida

1️⃣ Modelo da Doc da API 1: Apenas os dados da API

...

• ✅ Vantagens Modelo 1:
  • ✔ Mais objetiva e técnica – Evita informações desnecessárias para desenvolvedores que só precisam da API.
  • ✔ Fácil manutenção – Não precisa ser alterada caso a interface do produto mude.
  • ✔ Facilidade para integradores externos – Desenvolvedores que não usam o produto podem entender os dados sem precisar de contexto extra.

• ❌ Desvantagens Modelo 1:
• • ✖ Desconexão com o produto – Quem usa o produto pode não saber como esses dados se refletem na interface.
  • ✖ Pouca usabilidade para equipes internas – Se um analista de suporte ou um gerente de produto precisar entender os dados da API, pode ter dificuldades.
    
    

2️⃣ Modelo da Doc da API 2: Relacionando os dados da API com o produto

...

✅ Vantagens Modelo 2:

• ✔ Maior clareza para usuários do produto – Ajuda a entender como os dados da API afetam a interface.
• ✔ Melhor suporte para equipes internas – Suporte técnico, gerentes de produto e QA podem relacionar os dados da API com o que veem no sistema.
• ✔ Facilita a integração com o front-end – Desenvolvedores que trabalham na interface do produto sabem exatamente onde cada campo é usado. (No nosso caso o banco de dados do PDV)
  
  

❌ Desvantagens Modelo 2:

• ✖ Pode ficar mais complexa e extensa – Mais informações significam mais detalhes para manter e atualizar.
• ✖ Maior chance de desatualização – Se o produto mudar, a documentação pode ficar obsoleta rapidamente.
• ✖ Menos útil para integradores externos – Quem não usa o produto pode achar irrelevante a relação dos campos com a interface.
  
  

Pontos de melhoria - Solução 1

• Incluir referências de link da documentação do PDV, onde a integração pode ser utilizada. Isto auxilia ao desenvolvedor a identificar melhor a necessidade dos campos a serem utilizados e melhor entendimento da API. 
• Melhoria na estrutura de como está o layout da documentação atualmente:
  • Precisamos realmente de tantas abas na interface principal do produto?
  • Dificuldade de instruir o usuario com tantas informações logo de cara
    • Baixa
    • Envio
    • Online
• Ajustes no modelo da doc das API's
  
  • Adicionar as informações referentes a versões de forma clara
  • Centralizar todos os tipos de Dados existentes em apenas um lugar
  • Melhor descrição das API's, para que serve e a sua relação entre elas
    • Exemplo: ProcessoOnline com fluxos dependentes que não são claros NotaEntrada + NotaSaida

Solução 2 - Unificando a documentação: PDVSync com PDV

• Uma ideia de unificar as documentações, visando em facilitar aos desenvolvedores externos uma consulta unica, segue exemplo atual de uma documentação unificada: Produto.
• A documentação é separada nas seguintes abas:
  • Descrição dos campos e regras:  Exclusiva para detalhes de campos e regras referente as tabelas do banco PDV.
  • Como integrar: Sessão PDVSync, contém os seguintes dados referente a API especifica:
    • Métodos POST ou GET (Até o momento mais ou unicamente utilizados no PDV)
    • Payloads detalhados com seus tipos (Tabelas com tipos de campos, limites de caracteres, versões, etc...)
    • Detalhe do retorno esperado para sucesso (200 ok) e erro (400 Bad Request) 

• Modelo 2 →
• Image Added

• ✅ Vantagens:
  
  • ✔ Experiência unificada e facilidade no entendimento de como os dados serão integrados no PDV– Usuários do produto encontram a documentação no mesmo local, sem precisar buscar em fontes externas.
  • ✔ Maior alinhamento com a evolução do produto – Mudanças na API acompanham "automaticamente" as mudanças no produto.
  • ✔ Facilidade de acesso para clientes – Se a API for utilizada por clientes do próprio produto, o acesso integrado simplifica a adoção.
  • ✔ Melhor suporte e integração – Pode estar conectada a fóruns, FAQs e suporte técnico dentro do mesmo ecossistema.

...

• ❌ Desvantagens:
  • ✖ Pode dificultar a adoção por terceiros – Se a API for aberta, desenvolvedores externos podem ter dificuldade em encontrá-la.
  • ✖ Menos flexibilidade na organização da documentação – Pode ser difícil criar uma documentação modular e expansível dentro da estrutura do produto.
  • ✖ Risco de desatualização – Caso o foco esteja no produto principal, a documentação da API pode ficar desatualizada.
  • ✖ Estrutura pré-definida com base na documentação do PDV - Uma documentação pensada no negócio em si ao invés de API
• Modelo 2 →
• Image Removed
  • ✔ Documentação mais resumida
  • ✔ Pensada nos tipos de dados que o PDVOmni pode receber da retaguarda
    • ✔ Processo inicial
    • ✔ Fluxos de Baixa
    • ✔ Processos Online (pendente incluir)

...

Pontos de melhoria - Solução 2

• Estrutura separado pelos tipos de dados, sendo que o PDVSync é separado por micros serviçosmicrosserviços
• Em cada tipo de dados existe uma quantidade enorme de informações do PDV na primeira aba + as informações da API, pode ser tornar confuso para o usuário
  • Necessidade de dar foco para a API e foco para o PDV quando o usuario for procurar uma informações especificas
• Ausência de processo de instalação do Sync
• Ausência de processo Troubleshooting
• Fluxos de subida de forma separada
• Em cada fluxo precisa adicionar a informação do micros serviçomicrosserviço, pois atualmente temos apenas o endPoint oque o que pode se tornar confuso na hora de montar uma requisição
• Estudo de como implementar o processo online