Pular para conteúdo

Proposta de Melhoria para a API do AgroMart

Contexto e Objetivo

O projeto atual, é API de CMS utilizando Strapi e Docker Compose, são tecnologias que constroem uma plataforma rápida. Porém, para atender bem o seu público-alvo — vendedores de produtos agrícolas com pouca familiaridade tecnológica, são necessárias adaptações importantes.

O objetivo desta proposta é desenvolver um plano de ação claro para tornar o projeto significativamente mais acessível, intuitivo e funcional para o dia a dia do usuário, abordando desde a instalação inicial até a gestão de estoque de produtos.

Problemas Identificados

  1. Alta Barreira de Entrada Técnica: A ausência de um guia de configuração de ambiente ( .env.sample) torna a instalação um processo complexo e propenso a erros para não-desenvolvedores.
  2. Interface Pouco Intuitiva e em Inglês: A interface padrão do Strapi genérica é em inglês, representando uma barreira (idioma e complexidade) para o usuário final.
  3. Funcionalidade Essencial Ausente: O sistema possui uma funcionalidade complexa de criação de entidades, utilizando palavras muito técnicas, como "collection" e "single types".

Propostas de Melhoria

As melhorias foram reestruturadas em três frentes principais: Facilidade de Instalação, Experiência do Usuário (UX) e Funcionalidades e Capacitação.

Melhoria 1: Simplificar a Instalação

O primeiro contato do usuário com o sistema deve ser simples e positivo.

  • Ação 1: Criar um arquivo .env.sample didático e seguro
  • Descrição: Substituir a necessidade de conhecimento técnico por um guia passo a passo dentro de um arquivo modelo. Este arquivo explicará em linguagem simples como gerar as chaves de segurança necessárias.
  • Implementação (Conteúdo do novo .env.sample): Ini, TOML

Exemplo de solução:

# ===================================================================
# ARQUIVO DE CONFIGURAÇÃO DO PROJETO
# ===================================================================
# INSTRUÇÕES:
# 1. Copie este arquivo e renomeie a cópia para ".env".
# 2. Preencha os campos abaixo conforme as instruções.
# 3. NUNCA compartilhe o seu arquivo .env com ninguém!
# ===================================================================

# --- Configuração do Banco de Dados ---
# Se você usa o Docker do projeto, provavelmente só precisa mudar a senha.
DATABASE_NAME=carol_shaw
DATABASE_USERNAME=carol_shaw
DATABASE_PASSWORD=sua_senha_segura_aqui

# --- Chaves de Segurança do Aplicativo ---
# Pense nelas como senhas internas que protegem sua aplicação.
#
# COMO GERAR ESSAS CHAVES DE FORMA FÁCIL E SEGURA:
#   1. Acesse: https://1password.com/pt-br/password-generator/
#   2. Configure para gerar uma senha de 24 caracteres.
#   3. Gere, copie e cole aqui. REPITA para CADA chave abaixo.

# Gere DUAS senhas e cole-as separadas por vírgula. Ex: chave1,chave2
APP_KEYS=

# Gere uma chave no site e cole aqui.
JWT_SECRET=

# Gere outra chave diferente e cole aqui.
API_TOKEN_SALT=

# Gere a última chave e cole aqui.
ADMIN_JWT_SECRET=

  • Benefício: Elimina a principal barreira técnica na instalação, permitindo que qualquer pessoa configure o ambiente de forma segura e guiada.

  • Ação 2: Melhorar o README.md

  • Descrição: Atualizar o README.md para refletir a simplicidade do novo processo, focando no uso do .env.sample.

Melhoria 2: Adaptar a Experiência e Adicionar Funcionalidades Chave (UX)

É crucial que a ferramenta "fale a língua" do usuário e resolva seus problemas práticos, ou que pelo menos tenha a opção da lingua do usuário, que no caso atual, não possui.

  • Ação 1: Tradução (i18n) e Localização da Interface
  • Descrição: Ativar o português no Strapi e traduzir todos os nomes de coleções e campos para termos familiares ao agronegócio (ex: Product -> Produto, description -> Descrição/Origem, stock_quantity -> Quantidade em Estoque).
  • Benefício: Remove a barreira do idioma e torna a ferramenta imediatamente mais familiar.
  • Ação 2: Implementar um Gerenciador de Estoque Simplificado
  • Descrição: Adicionar uma funcionalidade clara para controle de estoque.
    • Implementação em duas etapas:
      1. Básica (Nativa): Adicionar um campo do tipo "Número" (Number) chamado Quantidade em Estoque no Content-Type "Produto". Isso já resolve a necessidade primária.
      2. Avançada (com Plugin): Para uma experiência superior, instalar um plugin de gerenciamento de estoque.
        • Plugin Recomendado:****strapi-plugin-stocks ou similar disponível no Marketplace do Strapi.
        • Visão Centralizada: Cria uma nova seção no menu do Strapi para ver o estoque de TODOS os produtos em uma única tela.
        • Gestão Rápida: Permite atualizações rápidas de quantidade sem precisar entrar em cada produto individualmente.
        • Histórico (em alguns plugins): Registra entradas e saídas, ajudando a entender o fluxo de vendas.
        • Ideal para o Vendedor: Facilita a visualização do que está acabando e precisa de reposição (nova colheita, compra, etc.).
        • Benefício: Transforma o CMS de um simples catálogo para uma ferramenta de gestão de negócios, agregando valor imenso ao usuário.
  • Ação 3: Criar uma Interface Simplificada (Frontend)
  • Descrição: Deixar a funcionalidade do lado do dono da CSA junto ao aplicativo ou em site, trazendo mais facilidade e com no seu uso.
  • Benefício: Aumenta a usabilidade e a taxa de adoção a longo prazo, sendo a evolução natural do projeto.

Melhoria 3: Capacitação e Suporte Contínuo

  • Ação: Criar Materiais de Treinamento Simples
  • Descrição: Produzir guias rápidos e visuais (vídeos curtos, PDFs com imagens) para as tarefas mais comuns, agora incluindo "Como atualizar o estoque".
  • Benefício: Empodera o usuário e reduz a carga de suporte.

Resumo dos Benefícios Esperados

  • Implantação Rápida: Qualquer usuário poderá configurar e iniciar o sistema sem ajuda técnica.
  • Usabilidade Máxima: Uma interface em português e com gestão de estoque resolve problemas reais do dia a dia do vendedor.
  • Decisões Informadas: A visão clara do estoque ajuda o vendedor a tomar melhores decisões de negócio.
  • Maior Adoção e Satisfação: Uma ferramenta que é fácil de usar e resolve problemas reais é uma ferramenta que será valorizada e utilizada.

Próximos Passos Sugeridos

  1. Curto Prazo (Imediato):

    • Criar o novo arquivo .env.sample e atualizar o README.md.
    • Traduzir os modelos de conteúdo e o painel do Strapi.
    • Instalar e configurar o plugin de gerenciamento de estoque.

  2. Médio Prazo:

    • Produzir os materiais de capacitação atualizados.
    • Realizar uma sessão de validação com um usuário-alvo para colher feedback sobre as novas funcionalidades.

  3. Longo Prazo (Estratégico):

    • Planejar e iniciar o desenvolvimento da interface de usuário simplificada (frontend).

📑 Histórico de Versão

Versão Data Descrição Autor
1.0 08/07/2025 Criação da página do proposta de solução Vinicius Mendes