Diagramas UML - ime-usp-br/laravel_11_starter_kit GitHub Wiki
Esta seção apresenta os diagramas UML chave que descrevem a arquitetura, funcionalidades e fluxos principais do Projeto Base USP - Laravel 11. Estes diagramas servem como uma representação visual para facilitar o entendimento do sistema.
Os códigos-fonte dos diagramas são fornecidos no formato Mermaid. Você pode copiar e colar este código em editores que suportam Mermaid (incluindo o próprio GitHub, ou ferramentas como o Editor Online do Mermaid ou o Draw.io com seu plugin Mermaid) para visualizar e exportar os diagramas como imagens (PNG/SVG), que podem então ser inseridas nos locais indicados neste documento.
Este diagrama ilustra as principais funcionalidades oferecidas pelo projeto base e como os diferentes tipos de usuários (atores) interagem com elas.
Atores Principais:
- Usuário (Geral): Representa qualquer pessoa interagindo com a aplicação antes ou durante a autenticação.
- Usuário USP: Um membro da comunidade USP (aluno, docente, servidor).
- Usuário Externo: Um usuário sem vínculo formal com a USP.
- Administrador: Um usuário com privilégios elevados para gerenciar o sistema.
- Sistema Senha Única: O serviço centralizado de autenticação da USP (ator externo).
- Sistema Replicado: O banco de dados corporativo da USP (ator externo).
graph TD
%% 1. Subgraph Funcionalidades Administrativas (Topo)
subgraph FuncAdmin ["Funcionalidades Administrativas"]
direction LR
UC10("Acessar Área Admin")
UC11("Listar Usuários")
UC12("Criar Usuário USP\nvia Replicado")
UC13("Criar Usuário Manual\n(USP/Externo)")
UC14("Gerenciar Papéis/\nPermissões App")
end
%% 2. Subgraph Atores (Meio)
subgraph Atores
direction LR
UsuarioGeral["Usuário (Geral)"]
UsuarioUSP["Usuário USP"]
UsuarioExterno["Usuário Externo"]
Administrador["Administrador"]
SistemaSU["Sistema Senha Única"]
SistemaRep["Sistema Replicado"]
end
%% 3. Subgraph Funcionalidades Principais (Base)
subgraph FuncPrincipais ["Funcionalidades Principais"]
direction LR
UC01("Autenticar via\nSenha Única")
UC02("Autenticar via\nEmail/Senha Local")
UC03("Registrar Conta")
UC04("Verificar Email")
UC05("Solicitar Link\nSenha Local USP")
UC06("Definir Senha Local USP")
UC07("Acessar Dashboard")
UC08("Editar Perfil")
UC09("Fazer Logout")
end
%% Conexões (mantidas, Mermaid ajustará o layout)
UsuarioGeral --o UC01 & UC02 & UC03 & UC05
UsuarioUSP --> UC01 & UC02 & UC05 & UC06
UsuarioUSP --|> UsuarioGeral
UsuarioExterno --> UC02
UsuarioExterno --|> UsuarioGeral
UsuarioUSP --o UC07 & UC08 & UC09
UsuarioExterno --o UC07 & UC08 & UC09
Administrador --|> UsuarioUSP %% Admin é um tipo de Usuário USP
Administrador --o UC10
UC10 --> UC11 & UC12 & UC13 & UC14
UC01 --x SistemaSU
UC12 --x SistemaRep
UC03 -.-> UC04
%% Estilos e Classes (mantidos)
classDef ator fill:#e6f0ff,stroke:#84a9d1,stroke-width:1px,color:#000;
class UsuarioGeral,UsuarioUSP,UsuarioExterno,Administrador,SistemaSU,SistemaRep ator;
style UC01,UC02 fill:#ffffcc,stroke:#b3b300
style UC03,UC04 fill:#e6ffe6,stroke:#008000
style UC05,UC06 fill:#e6f7ff,stroke:#0077cc
style UC07,UC08,UC09 fill:#f0f0f0,stroke:#666
style UC10,UC11,UC12,UC13,UC14 fill:#ffe6e6,stroke:#cc0000
Estes diagramas detalham a ordem das interações entre os componentes para realizar casos de uso específicos.
Mostra o fluxo desde o clique no botão de login até o usuário ser autenticado e redirecionado.
sequenceDiagram
participant Usuario as Usuário
participant Navegador
participant App as Aplicação Base<br/>(Middleware/Controller)
participant Socialite as SenhaUnica<br/>Socialite Provider
participant SU as Sistema Senha Única<br/>(OAuth1 Server)
participant DB as Banco de Dados<br/>(User Model, Spatie)
Usuario->>Navegador: Clica em "Login com Senha Única" (em /login)
Navegador->>App: GET /socialite/login
App->>Socialite: Chama redirect()
Socialite->>SU: Solicita Request Token
SU-->>Socialite: Retorna Request Token/Secret
Socialite->>App: Guarda Secret na Sessão
App-->>Navegador: Redirect para SU/authorize?oauth_token=...&callback_id=...
Navegador->>SU: GET /wsusuario/oauth/authorize?oauth_token=...
Usuario->>SU: Insere Credenciais USP
SU-->>Navegador: Redirect para App/callback?oauth_token=...&oauth_verifier=...
Navegador->>App: GET /callback?oauth_token=...&oauth_verifier=...
App->>Socialite: Chama user() [handleProviderCallback]
Socialite->>SU: Solicita Access Token (usando Request Token + Verifier)
SU-->>Socialite: Retorna Access Token/Secret
Socialite->>SU: Solicita Dados do Usuário (/usuariousp)
SU-->>Socialite: Retorna dados (JSON com codpes, nome, email, vinculos)
Socialite->>App: Retorna Objeto User Socialite
App->>DB: User::firstOrNew(['codpes' => codpes])
App->>DB: Atualiza/Preenche dados (nome, email)
App->>DB: user->save()
opt Marca Email como Verificado (se for novo ou nulo)
App->>DB: user->email_verified_at = now()
App->>DB: user->save()
end
opt Aplica Permissões (se config('senhaunica.permission'))
App->>App: user->aplicarPermissoes(dadosSU)
App->>DB: Sync roles/permissions (Spatie)
end
App->>App: Auth::login(user)
App-->>Navegador: Redirect para Dashboard ('/')
Navegador->>App: GET /
App-->>Navegador: Exibe página autenticada
Detalha o fluxo de registro quando um usuário seleciona "Comunidade USP".
sequenceDiagram
participant Usuario as Usuário
participant Navegador
participant App as Aplicação Base<br/>(Request/Controller)
participant DB as Banco de Dados<br/>(User, Role)
participant Mailer as Sistema de Email<br/>(Notification)
Usuario->>Navegador: Preenche formulário /register (Tipo=USP, inclui CodPes, email @usp.br)
Navegador->>App: POST /register (RegistrationRequest)
App->>App: Validação (RegistrationRequest::rules) - Verifica unicidade email/codpes, formato email
alt Validação Falha
App-->>Navegador: Retorna com Erros
else Validação OK
App->>DB: User::create(dados validados) - Cria usuário, Hashea senha
App->>DB: Role::firstOrCreate('usp_user')
App->>DB: user->assignRole('usp_user')
App->>App: Dispara evento Registered(user)
App->>Mailer: Queue(new VerifyUserEmail(user)) - Envia email de verificação
App->>App: Auth::login(user)
App-->>Navegador: Redirect para /verify-email (verification.notice)
Navegador->>App: GET /verify-email
App-->>Navegador: Exibe página "Verifique seu Email"
end
Ilustra como um administrador cria um usuário buscando dados no Replicado.
sequenceDiagram
participant Admin as Administrador
participant Navegador
participant App as Aplicação Base<br/>(AdminUserController)
participant Replicado as Fachada Replicado<br/>(Pessoa::fetch, Pessoa::email)
participant DB as Banco de Dados<br/>(User, Role)
participant Logger
Admin->>Navegador: Acessa /admin/users/create/usp
Navegador->>App: GET /admin/users/create/usp
App-->>Navegador: Exibe formulário (input codpes)
Admin->>Navegador: Insere CodPes e Submete
Navegador->>App: POST /admin/users/create/usp (StoreUspUserRequest)
App->>App: Validação (StoreUspUserRequest - codpes required, numeric, unique)
alt Validação Falha (ex: já existe)
App-->>Navegador: Redirect Back com Erros
else Validação OK
App->>Replicado: Pessoa::fetch(codpes)
Replicado-->>App: Retorna dados da pessoa (ou null)
alt Pessoa Não Encontrada
App-->>Navegador: Redirect Back com Erro ('Nº USP não encontrado')
else Pessoa Encontrada
App->>Replicado: Pessoa::email(codpes)
Replicado-->>App: Retorna email principal (ou vazio)
alt Email Vazio
App-->>Navegador: Redirect Back com Erro ('Usuário sem email principal')
else Email Encontrado
App->>DB: Verifica se email já existe (User::where('email', email)->exists())
alt Email Já Existe
App-->>Navegador: Redirect Back com Erro ('Usuário já cadastrado por Email')
else Email OK
App->>App: Gera senha aleatória (Str::password)
App->>DB: User::create(codpes, nome, email, hash(senha), email_verified_at=now())
App->>DB: Role::firstOrCreate('usp_user')
App->>DB: user->assignRole('usp_user')
App->>App: Adiciona Flash Message com Sucesso + Senha Inicial
App-->>Navegador: Redirect para /admin/dashboard
end
end
end
end
opt Exceção no Replicado
App->>Logger: Log::error(...)
App-->>Navegador: Redirect Back com Erro ('Erro ao conectar/processar Replicado')
end
Este diagrama mostra a estrutura das classes de modelo centrais (User, Role, Permission) e seus relacionamentos, incluindo os traits relevantes.
classDiagram
class User {
+int id
+string name
+string email
+int codpes nullable
+string password nullable
+timestamp email_verified_at nullable
+timestamp created_at
+timestamp updated_at
+string $appNs = 'web'
+string $hierarquiaNs = 'senhaunica'
+string $vinculoNs = 'senhaunica'
+array $permissoesHierarquia
+array $permissoesVinculo
+trait HasRoles~Spatie~
+trait HasSenhaunica~Uspdev~
+trait Notifiable
+trait HasFactory
+interface MustVerifyEmail
+getEnvAttribute() bool|string
+getLevelAttribute() string
+labelLevel(string $level = null) string
+hasSenhaunicaJson() bool
+aplicarPermissoes(UserSocialite $userSenhaUnica) void
+listarPermissoesHierarquicas() array
+listarPermissoesApp() array
+listarPermissoesVinculo(array $vinculos) array
+criarPermissoesPadrao() void
+findOrCreateFromReplicado(int $codpes) User|string
+verificaUsuarioLocal(int $codpes) bool
+roles() BelongsToMany
+permissions() BelongsToMany
+sendEmailVerificationNotification() void
+sendPasswordResetNotification(string $token) void
}
class Role {
<<Spatie\Permission\Models\Role>>
+int id
+string name
+string guard_name
+timestamp created_at
+timestamp updated_at
+permissions() BelongsToMany
+users() MorphToMany
}
class Permission {
<<Spatie\Permission\Models\Permission>>
+int id
+string name
+string guard_name
+timestamp created_at
+timestamp updated_at
+roles() BelongsToMany
+users() MorphToMany
}
User " * " -- " * " Role : via model_has_roles
User " * " -- " * " Permission : via model_has_permissions (direta)
Role " * " -- " * " Permission : via role_has_permissions
User ..> MustVerifyEmail : implements
User ..> HasRoles : uses
User ..> HasSenhaunica : uses
User ..> Notifiable : uses
User ..> HasFactory : uses
note for User "Usa traits de Spatie\Permission\Traits\HasRoles e Uspdev\SenhaunicaSocialite\Traits\HasSenhaunica"
Este diagrama ilustra o fluxo de decisão durante o processo de registro de um novo usuário.
graph TD
A[Início: Acessa /register] --> B{Preenche Formulário};
B --> C{Seleciona Tipo de Usuário};
C -- Externo --> D[Valida Dados Comuns];
C -- Comunidade USP --> E{Preenche Nº USP};
E --> F[Valida Dados Comuns, Email, e Nº USP];
D --> G{Validação OK?};
F --> G;
G -- Não --> H[Exibe Erros no Formulário];
H --> B;
G -- Sim --> I[Cria Usuário no BD];
I --> J{Tipo USP?};
J -- Sim --> K[Atribui Papel 'usp_user'];
J -- Não --> L[Atribui Papel 'external_user'];
K --> M[Dispara Evento Registered];
L --> M;
M --> N[Envia Email de Verificação];
N --> O[Loga Usuário];
O --> P[Redireciona para /verify-email];
P --> Q[Fim do Fluxo de Registro];
style H fill:#f9f,stroke:#333,stroke-width:2px
Para uma documentação ainda mais completa, especialmente à medida que aplicações mais complexas são construídas sobre este base, os seguintes diagramas PODERIAM ser considerados:
- Diagrama de Componentes: Mostrar os principais pacotes de software (Laravel Framework, SenhaunicaSocialite, Spatie Permission, UspTheme, Replicado) e suas dependências, ajudando a entender a arquitetura de alto nível e possíveis pontos de acoplamento.
- Diagrama de Implantação (Deployment): Visualizar como a aplicação seria implantada em um ambiente típico da USP, mostrando servidores web (Apache/Nginx), servidor de banco de dados (MySQL/PostgreSQL/SQLServer), servidor de cache (Redis/Memcached), servidor de filas e a interação com sistemas externos (Senha Única, Replicado).
- Diagrama de Estados (State Machine): Se houvesse entidades com ciclos de vida complexos (ex: um processo de aprovação com múltiplos estados), um diagrama de estados para o Model correspondente seria útil. Para o projeto base atual, talvez não seja essencial.
Estes diagramas adicionais PODERIAM ser adicionados conforme a necessidade e a evolução do projeto base ou das aplicações derivadas.