diff --git a/projects/README.md b/projects/README.md new file mode 100644 index 0000000..c090172 --- /dev/null +++ b/projects/README.md @@ -0,0 +1,61 @@ +# Projetos documentados + + + + + +## Roteiro de revisão dos PRs de documentação n8n + +### Objetivo + +Orientar quem completa, revisa e aprova a documentação gerada pelo Bootstrap antes do merge. + +### Estrutura que deve ser revisada + +- `projects//README.md`: visão geral e links. +- `projects//docs/TECHNICAL.md`: arquitetura e operação. +- `projects//docs/INTERNAL.md`: dados humanos e organizacionais. +- `projects//docs/workflows/`: detalhes de cada workflow. + +### Dados humanos obrigatórios + +- [ ] Nome e tipo do projeto. +- [ ] Data de início e término ou status atual. +- [ ] Responsáveis e seus papéis. +- [ ] Cliente, empresa ou confirmação de que não se aplica. +- [ ] Relacionamento, prazos, frequência de respostas e pedidos fora do escopo. +- [ ] Escopo, decisões, riscos e pendências internas. + +### Validação técnica + +- [ ] Arquitetura e dependências correspondem aos workflows reais. +- [ ] Gatilhos, entradas, integrações, dados, saídas e erros estão corretos. +- [ ] O Mermaid renderiza no GitHub. +- [ ] Cada workflow do `project.json` possui documento individual. + +### Segurança + +- [ ] Não existem tokens, senhas, IDs privados ou URLs internas. +- [ ] Credenciais são citadas somente por tipo. +- [ ] Dados pessoais e empresariais estão adequados à visibilidade do repositório. + +### Como preparar o PR + +1. Substitua `Precisa de confirmação` por informação validada ou por `Não se aplica`. +2. Faça as correções na mesma branch do PR. +3. Revise o diff completo e confirme que arquivos humanos não foram removidos indevidamente. +4. Marque o PR como pronto para revisão e solicite o aprovador responsável. + +### Critérios para aprovação + +- [ ] Todos os dados obrigatórios foram preenchidos. +- [ ] Documento técnico validado por quem conhece a automação. +- [ ] Documento interno validado por quem conhece o projeto ou cliente. +- [ ] Verificação de segurança concluída. +- [ ] Links e Mermaid renderizam corretamente. + +### Como finalizar + +Aprove o PR conforme a política da equipe e prefira **Squash and merge** para consolidar os commits automáticos e humanos. Depois do merge, a Maintenance altera somente workflows sanitizados e `project.json`. + + diff --git a/projects/agente-mej/README.md b/projects/agente-mej/README.md index 4936803..a7be6b9 100644 --- a/projects/agente-mej/README.md +++ b/projects/agente-mej/README.md @@ -1,55 +1,65 @@ # Agente Mej -## Visão Geral -O projeto Agente Mej consiste em um workflow automatizado que utiliza inteligência artificial para interagir com mensagens de chat, especificamente através do Telegram. O sistema é capaz de identificar mensagens, processar conteúdo e responder de forma inteligente. +## Visão geral + +O projeto Agente Mej é uma implementação de um workflow automatizado que utiliza inteligência artificial para interagir com mensagens de chat, especificamente através do Telegram. O sistema é projetado para identificar mensagens, processar conteúdo e responder de forma inteligente. Este projeto inclui um workflow principal chamado MVP, que contém diversos nós responsáveis pela lógica de processamento e resposta. ## Componentes -O projeto inclui um workflow principal chamado MVP, que contém diversos nós responsáveis pela lógica de processamento e resposta. -## Fluxo Principal +- **[MVP](docs/workflows/mvp.md)** — Workflow. + +## Fluxo principal + 1. Recebimento de mensagem do Telegram. 2. Verificação se a mensagem contém um arquivo de áudio. 3. Processamento da mensagem utilizando modelos de linguagem e ferramentas de IA. 4. Armazenamento e recuperação de informações relevantes. 5. Envio de resposta através do Telegram. -## Entradas e Saídas -- **Entrada:** Mensagens de chat do Telegram. -- **Saída:** Respostas processadas enviadas de volta ao chat do Telegram. +## Entradas e saídas + +### Entradas + +O gatilho principal é o recebimento de mensagens através do Telegram. As entradas incluem mensagens de texto e, potencialmente, arquivos de áudio. + +### Saídas + +As saídas são respostas processadas que são enviadas de volta ao chat do Telegram. ## Integrações + - Telegram para recebimento e envio de mensagens. - Google Gemini e OpenAI para processamento de linguagem natural. - Supabase para armazenamento de dados. ## Operação -O workflow é ativado por eventos de mensagens recebidas no Telegram e processa as informações conforme configurado nos nós do workflow. - -## Riscos -- Dependência de serviços externos como Telegram e APIs de IA. -- Gestão de privacidade e segurança das informações processadas. -## Pontos que Precisam de Confirmação -- Detalhes específicos sobre a configuração e uso das APIs de terceiros. -- Políticas de segurança e privacidade aplicadas ao projeto. +O workflow é ativado por eventos de mensagens recebidas no Telegram e processa as informações conforme configurado nos nós do workflow. ## Arquitetura ```mermaid flowchart TD - Telegram[Telegram API] -->|Recebe mensagens| ChatTrigger[When chat message received] - ChatTrigger -->|Verifica áudio| CheckAudio[Check if Audio file] - CheckAudio -->|Texto| Assistant[Assistant Agent] - Assistant -->|Resposta| MsgTelegram[Mensagem do Telegram] - MsgTelegram -->|Envia resposta| ReplyTelegram[Reply in Telegram] - Assistant -->|Consulta| Supabase[Supabase Vector Store2] - Supabase -->|Dados| KnowledgeMEJ[Conhecimento - MEJ] - Assistant -->|Usa modelo| GoogleModel[Google Gemini Chat Model] - GoogleModel -->|Processa| Embeddings[Embeddings OpenAI1] + Telegram["Telegram API"] -->|Recebe mensagens| ChatTrigger["When chat message received"] + ChatTrigger -->|Verifica áudio| CheckAudio["Check if Audio file"] + CheckAudio -->|Texto| Assistant["Assistant Agent"] + Assistant -->|Resposta| MsgTelegram["Mensagem do Telegram"] + MsgTelegram -->|Envia resposta| ReplyTelegram["Reply in Telegram"] + Assistant -->|Consulta| Supabase["Supabase Vector Store2"] + Supabase -->|Dados| KnowledgeMEJ["Conhecimento - MEJ"] + Assistant -->|Usa modelo| GoogleModel["Google Gemini Chat Model"] + GoogleModel -->|Processa| Embeddings["Embeddings OpenAI1"] Embeddings -->|Dados vetorizados| Supabase - Supabase -->|Consulta| KnowledgeEJs[Conhecimento - EJs] + Supabase -->|Consulta| KnowledgeEJs["Conhecimento - EJs"] KnowledgeEJs -->|Dados| Assistant - Assistant -->|Memória| SimpleMemory[Simple Memory] + Assistant -->|Memória| SimpleMemory["Simple Memory"] ``` -[Abrir a fonte do diagrama](docs/architecture.mmd) +## Documentação detalhada + +- [Documentação técnica completa](docs/TECHNICAL.md) +- [Contexto interno](docs/INTERNAL.md) +- [Roteiro de revisão do PR](../README.md#pr-review) +- [Documentação individual dos workflows](docs/workflows/) + +Documentação gerada pelo Bootstrap do n8n. A revisão humana é obrigatória antes da aprovação do PR. diff --git a/projects/agente-mej/docs/INTERNAL.md b/projects/agente-mej/docs/INTERNAL.md new file mode 100644 index 0000000..63e88ed --- /dev/null +++ b/projects/agente-mej/docs/INTERNAL.md @@ -0,0 +1,35 @@ +# Contexto interno — Agente Mej +## Identificação do projeto +### Nome do projeto +Agente Mej +### Tipo de projeto +Desenvolvimento de software +### Data de início +Precisa de confirmação +### Término ou status +Em desenvolvimento +### Responsáveis +Precisa de confirmação +### Repositório +https://github.com/jhvlima/n8n-workflows/blob/test/n8n-docs/projects/agente-mej/README.md +## Cliente ou empresa +### Nome do cliente +Precisa de confirmação +### Descrição da empresa +Precisa de confirmação +### Perfil e dinâmica de relacionamento +#### Flexibilidade com prazos +Precisa de confirmação +#### Frequência de respostas +Precisa de confirmação +#### Pedidos fora do escopo +Precisa de confirmação +## Descrição do produto +O produto é um sistema automatizado que utiliza inteligência artificial para interagir com mensagens de chat do Telegram, identificando, processando e respondendo mensagens de forma inteligente. +## Escopo e decisões +O escopo inclui o desenvolvimento do workflow MVP com integração ao Telegram e uso de modelos de IA para processamento de linguagem. Decisões sobre ferramentas e tecnologias específicas precisam de confirmação. +## Riscos internos +Dependência de serviços externos e gestão de privacidade e segurança das informações processadas. +## Pendências internas +- Detalhes específicos sobre a configuração e uso das APIs de terceiros. +- Políticas de segurança e privacidade aplicadas ao projeto. diff --git a/projects/agente-mej/docs/TECHNICAL.md b/projects/agente-mej/docs/TECHNICAL.md new file mode 100644 index 0000000..58de8ff --- /dev/null +++ b/projects/agente-mej/docs/TECHNICAL.md @@ -0,0 +1,58 @@ +# Documentação técnica — Agente Mej +## Visão técnica +O projeto Agente Mej é uma implementação de um workflow automatizado que utiliza inteligência artificial para interagir com mensagens de chat, especificamente através do Telegram. O sistema é projetado para identificar mensagens, processar conteúdo e responder de forma inteligente. +## Objetivo e escopo +O objetivo do projeto é automatizar a interação com mensagens de chat através do Telegram, utilizando inteligência artificial para processar e responder mensagens de forma inteligente. O escopo inclui o recebimento de mensagens, a verificação de conteúdo, o processamento utilizando modelos de linguagem e ferramentas de IA, e o envio de respostas. +## Usuários e canais +O principal canal de interação é o Telegram, onde os usuários podem enviar mensagens que serão processadas e respondidas pelo sistema. +## Gatilhos e entradas +O gatilho principal é o recebimento de mensagens através do Telegram. As entradas incluem mensagens de texto e, potencialmente, arquivos de áudio. +## Fluxo principal +1. Recebimento de mensagem do Telegram. +2. Verificação se a mensagem contém um arquivo de áudio. +3. Processamento da mensagem utilizando modelos de linguagem e ferramentas de IA. +4. Armazenamento e recuperação de informações relevantes. +5. Envio de resposta através do Telegram. + +## Workflows documentados + +- [MVP](workflows/mvp.md) — Workflow. + +## Arquitetura do fluxo + +```mermaid +flowchart TD + Telegram["Telegram API"] -->|Recebe mensagens| ChatTrigger["When chat message received"] + ChatTrigger -->|Verifica áudio| CheckAudio["Check if Audio file"] + CheckAudio -->|Texto| Assistant["Assistant Agent"] + Assistant -->|Resposta| MsgTelegram["Mensagem do Telegram"] + MsgTelegram -->|Envia resposta| ReplyTelegram["Reply in Telegram"] + Assistant -->|Consulta| Supabase["Supabase Vector Store2"] + Supabase -->|Dados| KnowledgeMEJ["Conhecimento - MEJ"] + Assistant -->|Usa modelo| GoogleModel["Google Gemini Chat Model"] + GoogleModel -->|Processa| Embeddings["Embeddings OpenAI1"] + Embeddings -->|Dados vetorizados| Supabase + Supabase -->|Consulta| KnowledgeEJs["Conhecimento - EJs"] + KnowledgeEJs -->|Dados| Assistant + Assistant -->|Memória| SimpleMemory["Simple Memory"] +``` + +## Integrações e APIs +- Telegram para recebimento e envio de mensagens. +- Google Gemini e OpenAI para processamento de linguagem natural. +- Supabase para armazenamento de dados. +## Modelo e lógica de IA +Utilização de modelos de linguagem natural da Google Gemini e OpenAI para processar as mensagens recebidas e gerar respostas. +## Dados e persistência +Utilização do Supabase para armazenamento e recuperação de informações processadas e relevantes. +## Saídas +As saídas são respostas processadas que são enviadas de volta ao chat do Telegram. +## Operação e observabilidade +O workflow é ativado por eventos de mensagens recebidas no Telegram e processa as informações conforme configurado nos nós do workflow. +## Tratamento de erros +Gestão de erros relacionados à falha nos serviços externos e erros de processamento de IA. +## Limitações técnicas +Dependência de serviços externos como Telegram e APIs de IA. +## Pontos técnicos que precisam de confirmação +- Detalhes específicos sobre a configuração e uso das APIs de terceiros. +- Políticas de segurança e privacidade aplicadas ao projeto. diff --git a/projects/agente-mej/docs/workflows/mvp.md b/projects/agente-mej/docs/workflows/mvp.md new file mode 100644 index 0000000..1c4dcb0 --- /dev/null +++ b/projects/agente-mej/docs/workflows/mvp.md @@ -0,0 +1,24 @@ +# MVP +## Papel no projeto +O workflow MVP é o componente central do projeto Agente Mej, responsável por toda a lógica de processamento e resposta às mensagens recebidas via Telegram. +## Gatilhos e entradas +O gatilho principal é o recebimento de mensagens através do Telegram. As entradas incluem mensagens de texto e, potencialmente, arquivos de áudio. +## Etapas principais +1. Recebimento de mensagem do Telegram. +2. Verificação se a mensagem contém um arquivo de áudio. +3. Processamento da mensagem utilizando modelos de linguagem e ferramentas de IA. +4. Armazenamento e recuperação de informações relevantes. +5. Envio de resposta através do Telegram. +## Integrações e credenciais +- Telegram para recebimento e envio de mensagens. +- Google Gemini e OpenAI para processamento de linguagem natural. +- Supabase para armazenamento de dados. +## Dependências +Não há dependências externas além das integrações mencionadas. +## Saídas +As saídas são respostas processadas que são enviadas de volta ao chat do Telegram. +## Tratamento de erros +Gestão de erros relacionados à falha nos serviços externos e erros de processamento de IA. +## Limitações e pontos de confirmação +- Detalhes específicos sobre a configuração e uso das APIs de terceiros. +- Políticas de segurança e privacidade aplicadas ao projeto. diff --git a/projects/agente-mej/project.json b/projects/agente-mej/project.json index 57f1c0c..1405006 100644 --- a/projects/agente-mej/project.json +++ b/projects/agente-mej/project.json @@ -5,7 +5,7 @@ "sourceOfTruth": "github", "bootstrapCompleted": true, "aiMode": "bootstrap", - "currentVersion": "2026.07.11.1", + "currentVersion": "2026.07.21.1", "functionalHash": "2320a6964f03866c", "workflows": [ { @@ -25,5 +25,7 @@ ], "dependencies": [], "reviewRequired": true, - "bootstrapAt": "2026-07-12T01:28:55.393Z" + "documentationLayout": "separated", + "documentationSchemaVersion": 2, + "bootstrapAt": "2026-07-21T22:55:36.933Z" } \ No newline at end of file