Adds documentation and fixes
This commit is contained in:
269
docs/frontend-app.md
Normal file
269
docs/frontend-app.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Documentação da Aplicação Frontend
|
||||
|
||||
Este documento descreve a aplicação web Streamlit localizada na pasta `front/app`, que fornece uma interface de chat conversacional para o assistente de produtos e serviços baseado em IA.
|
||||
|
||||
## Estrutura de Diretórios
|
||||
|
||||
```
|
||||
front/app/
|
||||
├── front.py # Aplicação principal Streamlit (74 linhas)
|
||||
├── st_auth.py # Módulo de autenticação AWS Secrets Manager (28 linhas)
|
||||
└── __pycache__/ # Bytecode Python compilado
|
||||
```
|
||||
|
||||
## Visão Geral da Arquitetura
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Interface Web Streamlit │
|
||||
│ (Executa na porta 8501 via Docker) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ [Autenticação de Usuário via AWS Cognito OIDC] │
|
||||
│ (Token JWT no header x-amzn-oidc-data) │
|
||||
│ ↓ │
|
||||
│ [Seletor de Idioma] [Campo de Entrada do Chat] │
|
||||
│ ↓ │
|
||||
│ ┌──────────────────────────────────────────┐ │
|
||||
│ │ Gerenciamento de Estado da Sessão │ │
|
||||
│ │ - user_prompt_history │ │
|
||||
│ │ - chat_answer_history │ │
|
||||
│ │ - chat_history (conversa completa) │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌──────────────────────────────────────────┐ │
|
||||
│ │ Manipulador de Requisições API │ │
|
||||
│ │ - Busca chave API do AWS Secrets Mgr │ │
|
||||
│ │ - POST para AWS API Gateway │ │
|
||||
│ │ - Inclui contexto do usuário e histórico│ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Backend AWS (Serviço Externo) │
|
||||
│ API Gateway → Lambda → Assistente IA │
|
||||
│ (Retorna JSON com chat_history e mensagem) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Descrição dos Arquivos
|
||||
|
||||
### st_auth.py - Integração com AWS Secrets Manager
|
||||
|
||||
**Propósito:** Recupera chaves de API e segredos sensíveis do AWS Secrets Manager.
|
||||
|
||||
#### Função: `get_secret()`
|
||||
|
||||
Conecta ao AWS Secrets Manager e recupera os segredos da aplicação.
|
||||
|
||||
```python
|
||||
def get_secret() -> str:
|
||||
"""
|
||||
Recupera o segredo 'assistente-produtos-servicos' do AWS Secrets Manager.
|
||||
|
||||
Retorna:
|
||||
str: A string do segredo (formato JSON) contendo chaves de API e credenciais.
|
||||
|
||||
Exceções:
|
||||
ClientError: Se o segredo não puder ser recuperado da AWS.
|
||||
"""
|
||||
```
|
||||
|
||||
**Detalhes Importantes:**
|
||||
- Conecta ao AWS Secrets Manager na região `us-east-1`
|
||||
- Recupera o segredo chamado `"assistente-produtos-servicos"`
|
||||
- Retorna o segredo como string (formato JSON esperado)
|
||||
- Usa sessão boto3 para operações do SDK AWS
|
||||
- Inclui tratamento de erros para exceções `ClientError`
|
||||
|
||||
**Dependências:**
|
||||
- `boto3` - SDK AWS para Python
|
||||
- `botocore.exceptions` - Tratamento de erros para operações AWS
|
||||
|
||||
---
|
||||
|
||||
### front.py - Aplicação Principal Streamlit
|
||||
|
||||
**Propósito:** Interface de chatbot interativa para assistência de produtos/serviços com autenticação AWS Cognito e respostas baseadas em IA.
|
||||
|
||||
#### Componentes
|
||||
|
||||
##### 1. Autenticação e Contexto do Usuário (Linhas 1-27)
|
||||
|
||||
Extrai informações do usuário da autenticação AWS ALB OIDC:
|
||||
|
||||
- Extrai token JWT do header `x-amzn-oidc-data`
|
||||
- Decodifica token JWT sem verificação de assinatura
|
||||
- Extrai identificação do usuário de múltiplos campos JWT:
|
||||
- `sub` (Subject - campo JWT padrão)
|
||||
- `cognito:username` (nome de usuário Cognito)
|
||||
- `username` (campo alternativo de nome de usuário)
|
||||
- `user_id` (campo customizado)
|
||||
- Recupera email do usuário do token decodificado
|
||||
|
||||
##### 2. Elementos da Interface
|
||||
|
||||
| Elemento | Descrição |
|
||||
|----------|-----------|
|
||||
| Seletor de Idioma | Dropdown com opções English, Portuguese, Spanish |
|
||||
| Cabeçalho Principal | "Assistente Produtos Servicos" |
|
||||
| Entrada do Chat | Campo de texto com placeholder em português |
|
||||
|
||||
##### 3. Gerenciamento de Estado da Sessão
|
||||
|
||||
A aplicação mantém três variáveis de estado de sessão:
|
||||
|
||||
| Variável | Tipo | Descrição |
|
||||
|----------|------|-----------|
|
||||
| `user_prompt_history` | `List[str]` | Lista de perguntas do usuário |
|
||||
| `chat_answer_history` | `List[str]` | Lista de respostas da IA |
|
||||
| `chat_history` | `List[dict]` | Histórico completo da conversa com papéis |
|
||||
|
||||
##### 4. Função Utilitária: `create_sources_string()`
|
||||
|
||||
```python
|
||||
def create_sources_string(source_urls: Set[str]) -> str:
|
||||
"""
|
||||
Formata fontes de citação para exibição.
|
||||
|
||||
Args:
|
||||
source_urls: Conjunto de URLs de fontes únicas para formatar.
|
||||
|
||||
Retorna:
|
||||
str: Lista numerada de fontes para exibição.
|
||||
"""
|
||||
```
|
||||
|
||||
*Nota: Atualmente definida mas não utilizada ativamente no código.*
|
||||
|
||||
##### 5. Fluxo Principal do Chat
|
||||
|
||||
Quando um usuário envia uma mensagem, a seguinte sequência ocorre:
|
||||
|
||||
1. **Exibe mensagem do usuário** - Mostra a pergunta na interface imediatamente
|
||||
2. **Faz requisição à API:**
|
||||
- Constrói payload com mensagem, histórico do chat, nome de usuário, email, origem, idioma
|
||||
- Envia requisição POST para endpoint AWS API Gateway
|
||||
- Inclui chave API nos headers obtida do AWS Secrets Manager
|
||||
3. **Processa resposta:**
|
||||
- Analisa resposta JSON
|
||||
- Atualiza histórico do chat da resposta se fornecido
|
||||
- Extrai conteúdo da mensagem da estrutura de resposta
|
||||
- Trata erros de timeout com mensagem amigável ao usuário
|
||||
4. **Atualiza estado:**
|
||||
- Adiciona pergunta do usuário ao histórico
|
||||
- Adiciona resposta da IA ao histórico
|
||||
- Atualiza histórico do chat com registros de conversa baseados em papéis
|
||||
|
||||
## Fluxo de Dados
|
||||
|
||||
```
|
||||
1. Acesso do Usuário → AWS ALB injeta token JWT nos headers
|
||||
↓
|
||||
2. Autenticação → Extrai user_id e email do JWT
|
||||
↓
|
||||
3. Entrada do Usuário → Mensagem de chat com preferência de idioma
|
||||
↓
|
||||
4. Chamada API → POST para AWS Lambda via API Gateway com:
|
||||
- Conteúdo da mensagem
|
||||
- Histórico do chat
|
||||
- Metadados do usuário (username, email, origin, language)
|
||||
↓
|
||||
5. Processamento Backend → Assistente IA gera resposta
|
||||
↓
|
||||
6. Resposta → JSON com chat_history e conteúdo da mensagem
|
||||
↓
|
||||
7. Exibição → Atualiza interface e mantém estado da sessão
|
||||
```
|
||||
|
||||
## Comunicação com API
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
POST https://xexm2wsz07-vpce-05915540d0592b921.execute-api.us-east-1.amazonaws.com/dev
|
||||
```
|
||||
|
||||
### Payload da Requisição
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Pergunta ou mensagem do usuário",
|
||||
"chat_history": [
|
||||
{"role": "user", "content": "Mensagem anterior do usuário"},
|
||||
{"role": "assistant", "content": "Resposta anterior do assistente"}
|
||||
],
|
||||
"username": "user_id_do_jwt",
|
||||
"email": "usuario@exemplo.com",
|
||||
"origin": "streamlit",
|
||||
"language": "Portuguese"
|
||||
}
|
||||
```
|
||||
|
||||
### Headers da Requisição
|
||||
|
||||
```
|
||||
x-api-key: <Chave API do AWS Secrets Manager>
|
||||
```
|
||||
|
||||
### Formato da Resposta
|
||||
|
||||
```json
|
||||
{
|
||||
"chat_history": [...],
|
||||
"message": {
|
||||
"content": "Texto de resposta do assistente"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dependências
|
||||
|
||||
| Pacote | Versão | Propósito |
|
||||
|--------|--------|-----------|
|
||||
| `streamlit` | ^1.49.1 | Framework de interface web |
|
||||
| `boto3` | ^1.40.37 | SDK AWS |
|
||||
| `requests` | - | Cliente HTTP para chamadas API |
|
||||
| `PyJWT` | - | Decodificação de tokens JWT |
|
||||
| `pyyaml` | - | Parsing de YAML |
|
||||
|
||||
## Configuração
|
||||
|
||||
### Ambiente
|
||||
|
||||
- **Porta:** 8501 (porta padrão do Streamlit)
|
||||
- **Região AWS:** us-east-1
|
||||
- **Nome do Segredo:** `assistente-produtos-servicos`
|
||||
|
||||
### Idiomas Suportados
|
||||
|
||||
- English (Inglês)
|
||||
- Portuguese (Português)
|
||||
- Spanish (Espanhol)
|
||||
|
||||
## Tratamento de Erros
|
||||
|
||||
| Cenário | Comportamento |
|
||||
|---------|---------------|
|
||||
| Timeout da API | Exibe: "Desculpe, a busca pode ter demorado mais que o esperado. Por favor tente novamente." |
|
||||
| Erros gerais da API | Resposta pode não ser exibida corretamente |
|
||||
|
||||
## Comportamento da Sessão
|
||||
|
||||
- Histórico do chat persiste dentro de uma única sessão do navegador
|
||||
- Histórico é limpo ao atualizar a página ou fechar a aba
|
||||
- Não há armazenamento persistente de conversas
|
||||
|
||||
## Notas de Implantação
|
||||
|
||||
A aplicação foi projetada para executar atrás de um AWS Application Load Balancer (ALB) com autenticação Cognito configurada. O ALB injeta o header `x-amzn-oidc-data` contendo o token JWT para usuários autenticados.
|
||||
|
||||
### Docker
|
||||
|
||||
A aplicação executa em um container Docker (veja `front/Dockerfile`) e expõe a porta 8501.
|
||||
|
||||
## Considerações Conhecidas
|
||||
|
||||
1. **Endpoint de API Hardcoded:** A URL do AWS API Gateway está hardcoded no código fonte
|
||||
2. **Funcionalidades Não Utilizadas:** Dependências `streamlit-authenticator` e `sseclient` são importadas mas não utilizadas
|
||||
3. **Sem Validação de Entrada:** Perguntas dos usuários e respostas da API não são validadas antes do uso
|
||||
4. **Persistência Apenas na Sessão:** Conversas não persistem entre sessões
|
||||
Reference in New Issue
Block a user