248 lines
9.2 KiB
Markdown
248 lines
9.2 KiB
Markdown
# 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)
|
|
```
|
|
|
|
## 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. 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: Mensagem padrão definada anteriormente para enviar a equipe |
|
|
| 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.
|
|
|