SCPRI - Documentação Protegida

📋 Resumo Executivo

🎯 Objetivo

Sistema inteligente baseado em IA (RAG) que permite funcionários consultar políticas, procedimentos e regras internas via chat conversacional, reduzindo em 60% o volume de tickets para RH.

🏗️ Arquitetura

Microserviços com Next.js (Frontend), NestJS/Python FastAPI (Backend), PostgreSQL + pgvector (Dados), Redis (Cache), e integração com LLMs via RAG.

⏱️ Cronograma

MVP em 16 semanas (4 meses), dividido em 8 sprints de 2 semanas. Go-live planejado com capacidade para 1000 requisições/minuto.

50

Req. Funcionais

40

Req. Não-Funcionais

57

User Stories

99.9%

SLA

📑 Especificação de Requisitos (SRS)

Módulo de Chat Inteligente

ID	Requisito	Prioridade	Métrica
RF-001	Login via SSO corporativo	Alta	Login < 2s
RF-002	Chatbot linguagem natural	Alta	85% precisão
RF-003	Técnica RAG	Alta	Score > 0.8
RF-004	Citação de fontes	Alta	100% respostas
RF-005	Avaliação thumbs up/down	Média	Registrado
RF-006	Histórico conversas	Média	90 dias
RF-007	Sugestões relacionadas	Média	3 sugestões
RF-008	Detecção não-saber + RH	Alta	Escalonamento < 5s
RF-009	Multi-idioma PT/EN/ES	Baixa	v2.0
RF-010	Compartilhar respostas	Média	Link expirável

Requisitos Não-Funcionais

ID	Requisito	Métrica	Estratégia
RNF-001	Tempo resposta	< 3s	Redis + Streaming
RNF-002	Disponibilidade	99.9%	K8s HA
RNF-003	Throughput	1000 req/min	Auto-scaling
RNF-011	TLS	1.3	Cert-Manager
RNF-012	Criptografia	AES-256	HashiCorp Vault
RNF-014	RBAC	Row-level	Casbin + PG RLS
RNF-020	LGPD/GDPR	Privacy by Design	Anonimização

📦 Backlog do Produto

Sprint 1-2

Fundação Técnica + Autenticação

Setup K8s, CI/CD, SSO, estrutura base (US-001 a US-010)

Sprint 3-4

Chat Core + Base de Conhecimento

Pipeline RAG, CRUD docs, upload (US-011 a US-030)

Sprint 5-6

IA + Administração

Fine-tuning, dashboard, relatórios (US-031 a US-044)

Sprint 7-8

Integrações + Lançamento

APIs, Slack/Teams, testes (US-045 a US-057)

ID	User Story	Pts	Sprint	Status
US-006	Login com conta corporativa	8	2	To Do
US-011	Perguntas linguagem natural	13	2	To Do
US-021	Cadastrar políticas	5	3	To Do
US-031	Implementar RAG	13	3	To Do
US-038	Dashboard métricas	8	5	To Do

🔗 Matriz de Rastreabilidade

Requisito	Caso Uso	User Story	Componente	Teste
RF-001 (Login)	UC-01	US-006	Auth Service	TC-001
RF-002 (Chat)	UC-02	US-011	Chat Engine	TC-002
RF-003 (RAG)	UC-02	US-031	RAG Pipeline	TC-003
RF-004 (Fontes)	UC-03	US-012	Chat Engine	TC-004
RF-021 (CRUD)	UC-20	US-021	Document Service	TC-021
RF-036 (Dash)	UC-35	US-038	Dashboard	TC-036

📊 Cobertura

0/104 testes
RF: 0/50 | RNF: 0/40

🎯 Aceitação

Precisão: 85%
Tempo: < 3s
SLA: 99.9%
NPS: > 50

🎭 Casos de Uso (UML)

🏗️

Visão Geral

Atores: Funcionário, Gestor, Admin, Auditor, RH

Sistemas: SSO, Serviço de IA

💬 Módulo de Chat

UC-01: Autenticar
UC-02: Consultar Política
UC-03: Visualizar Fonte
UC-04: Avaliar Resposta
UC-05: Ver Histórico
UC-06: Sugestões
UC-07: Escalar RH
UC-08: Modo Anônimo

📚 Base de Conhecimento

UC-20: Cadastrar Doc
UC-21: Versionar
UC-22: Categorizar
UC-23: Indexar Auto
UC-24: Upload
UC-25: Aprovar
UC-26: Gerar FAQ
UC-27: Métricas

⚙️ Administração

UC-35: Dashboard
UC-36: Gerenciar Users
UC-37: Integrações
UC-38: Treinar IA
UC-39: Config Prompts
UC-42: Não Respondidas
UC-43: Relatórios
UC-44: Auditoria

Pipeline RAG

# UC-02: Consultar Política
class RAGPipeline:
    def process_query(self, query, user_context):
        intent = self.intent_classifier.classify(query)
        query_embedding = self.encoder.encode(query)
        contexts = self.vector_store.similarity_search(
            query_embedding, k=5, 
            filter={"department": user_context.department}
        )
        prompt = self.build_prompt(query, contexts, user_context)
        response_stream = self.llm.generate_stream(prompt)
        return self.format_response(response_stream, contexts)
            

🏗️ Documento de Arquitetura

🖥️

C4 Model - Nível 1

Next.js → Kong → NestJS/FastAPI

PostgreSQL+pgvector | Redis | ES | MinIO

OpenAI/LLM | Azure AD | Slack | LDAP

🎨 Frontend

Next.js 14
Tailwind + shadcn/ui
TanStack Query
Zustand
Socket.io

⚙️ Backend

Kong/AWS ALB
NestJS (Auth/Docs)
FastAPI (Chat)
Celery + Redis

🗄️ Dados

PostgreSQL 15
pgvector
Redis
Elasticsearch
MinIO/S3

🤖 IA/ML

LangChain
OpenAI/Local LLM
text-embedding-3
RAG Pipeline
LoRA/QLoRA

ADRs

ADR	Decisão	Justificativa
ADR-001	RAG vs Fine-tuning	Sem re-treinamento, menor custo, transparência
ADR-002	pgvector vs Pinecone	Menor complexidade, ACID, custo reduzido
ADR-003	Microserviços	Python ML + Node.js I/O, escala independente

🗃️ Diagrama Entidade-Relacionamento

🗄️

Modelo ER

👤 users

id (PK)
email (UK)
name
department_id (FK)
role_id (FK)
preferences (JSONB)

💬 conversations

id (PK)
user_id (FK)
is_anonymous
context (JSONB)
satisfaction_score
Particionado mês

📄 documents

id (PK)
author_id (FK)
title, slug (UK)
status, visibility
content_text (FULLTEXT)
file_hash

🔍 embeddings

id (PK)
chunk_id (FK)
embedding (VECTOR 1536)
model_name
ivfflat index

Schema pgvector

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE embeddings (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    chunk_id UUID REFERENCES chunks(id) ON DELETE CASCADE,
    embedding VECTOR(1536),
    model_name VARCHAR(100) NOT NULL
);
CREATE INDEX ON embeddings 
USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);
            

📖 Dicionário de Dados

users

Campo	Tipo	Tam.	Obrig.	Default	Regras
id	UUID	36	Sim	uuid_generate_v4()	PK
email	VARCHAR	255	Sim	-	UK, válido
name	VARCHAR	255	Sim	-	Min 2 chars
department_id	UUID	36	Sim	-	FK
role_id	UUID	36	Sim	-	FK
is_active	BOOLEAN	-	Sim	true	-
preferences	JSONB	-	Não	{}	Tema
created_at	TIMESTAMP	-	Sim	CURRENT_TIMESTAMP	-

conversations

Campo	Tipo	Obrig.	Default	Descrição
id	UUID	Sim	uuid_generate_v4()	PK
user_id	UUID	Não	NULL	FK (NULL=anônimo)
is_anonymous	BOOLEAN	Sim	false	LGPD
context	JSONB	Não	{}	Intenções
satisfaction_score	INTEGER	Não	NULL	NPS 0-10

messages

Campo	Tipo	Obrig.	Descrição
id	UUID	Sim	PK
conversation_id	UUID	Sim	FK
type	ENUM	Sim	user, assistant, system, error
content	TEXT	Sim	Max 4000 chars
sources	JSONB	Não	Citações
latency_ms	FLOAT	Não	Tempo ms

🎨 Wireframes

1. Chat Funcionário

[Logo] SCPRI [🔔] [👤] [⚙️]

🤖 Assistente

Olá! Como posso ajudar?

🏖️ Férias 💰 Benefícios

👤 Você

Quanto tempo de férias tenho?

🤖 Assistente

Você tem direito a 30 dias de férias.

📄 Fontes:
[1] Política Férias 2024 - Seção 3.2

👍 👎 [💬 Fale com RH]

💬 Digite... [📎] [🎤] [➤]

2. Dashboard Admin

[Logo] SCPRI Admin [Dashboard] [Docs] [Users] [Config]

1,247

📊 Total Chats

87%

✅ Taxa Acerto

2.3s

⏱️ Tempo Médio

📈 Volume

[Gráfico]

🎯 Top Perguntas

1. Férias (234x)
2. Benefícios (189x)

3. Gestão Documentos

Documentos

+ Novo

📄 Política de Férias 2024

📁 RH | ✅ Publicado | v2.3

[✏️] [🗑️]

📄 Código de Conduta

📁 Compliance | 🟡 Em Revisão