Diagramas do Sistema - gabrafo/ohara-imoveis GitHub Wiki

@startuml
' --- Direção e Estilo ---
left to right direction
skinparam packageStyle rectangle

' --- Atores ---
' A hierarquia de generalização representa os níveis de permissão.
actor Cliente
actor Corretor
actor Administrador

Corretor --|> Cliente
Administrador --|> Corretor

' --- Casos de Uso do Sistema ---
rectangle "Sistema Imobiliário" {

  ' --- Notas Explicativas ---
  note as GeneralNote
    **Convenção de Nomenclatura:**
    O termo "**Gerenciar**" nos casos de uso refere-se ao
    conjunto completo de operações CRUD:
    (Cadastrar, Consultar, Alterar e Excluir).
  end note

  note as AuthNote
    **Requisito de Autenticação:**
    A funcionalidade "Buscar Propriedades" é pública.
    Todas as outras funcionalidades exigem que o
    usuário esteja devidamente autenticado.
  end note

  ' --- Módulos e Funcionalidades ---
  package "Propriedades" {
    usecase "Buscar Propriedades" as (SearchProperties)
    usecase "Gerenciar Propriedades" as (ManageProperties)
    usecase "Gerenciar Características de Propriedades" as (ManageFeatureTypes)
    usecase "Gerenciar Proprietários" as (ManageOwners)
  }

  package "Visitas" {
    usecase "Gerenciar Minhas Visitas" as (ManageSelfVisits)
    usecase "Gerenciar Todas as Visitas" as (ManageAllVisits)
  }

  package "Usuários" {
    usecase "Gerenciar Meus Dados" as (ManageSelf)
    usecase "Gerenciar Todos os Usuários" as (ManageAllUsers)
  }

}

(ManageProperties) <.. (ManageFeatureTypes) : <<extend>>

' --- Relações Atores e Casos de Uso ---
' Cliente
Cliente --> (SearchProperties)
Cliente --> (ManageSelfVisits)
Cliente --> (ManageSelf)

' Corretor (herda as funções de Cliente)
Corretor --> (ManageProperties)
Corretor --> (ManageOwners)
Corretor --> (ManageFeatureTypes)

' Administrador (herda as funções de Corretor)
Administrador --> (ManageAllUsers)
Administrador --> (ManageAllVisits)

@enduml

@startuml
' Diagrama de Pacotes - Ohara Imóveis API

top to bottom direction

' Pacote de autenticação e autorização
package "Auth" <<application service>> {
  [AuthController]
  [AuthService]
  [Guards]
  [Strategies]
}

' Pacote de usuários
package "Users" <<domain service>> {
  [UsersController]
  [UsersService]
  package "entity" as entitiesUsers {
    [User]
  }
}

' Pacote de imóveis
package "Properties" <<domain service>> {
  [PropertyController]
  [PropertyService]
  package "entity" as entitiesProperties {
    [Property]
    [Owner]
    [PropertyFeature]
    [FeatureType]
    [Address]
  }
}

' Pacote de visitas
package "Visits" <<domain service>> {
  [VisitController]
  [VisitService]
  package "entity" as entitiesVisits {
    [Visit]
  }
}

' Pacote comum (enums, validadores, utilitários)
package "Common" <<shared kernel>> {
  [Enums]
  [Validators]
}

' Dependências entre pacotes
Auth ..> Users : <<usa>>
Auth ..> Common : <<usa>>
Users ..> Common : <<usa>>
Properties ..> Users : <<referencia proprietário>>
Properties ..> Common : <<usa enums/validators>>
Visits ..> Users : <<referencia visitante>>
Visits ..> Properties : <<referencia imóvel>>
Visits ..> Common : <<usa enums>>

' Observação sobre DTOs
note as note
  DTOs (Data Transfer Objects) são
  definidos por pacote, seguindo o padrão:
  src/<modulo>/dto/request|response
end note

@enduml

@startuml
' Diagrama de Pacotes - Ohara Imóveis Frontend

' Pacote de autenticação
package "Auth" <<feature>> {
  [LoginScreen]
  [RegisterScreen]
  [AuthService] as AuthAPI
}

' Pacote principal
package "Home" <<feature>> {
  [HomeScreen]
  [HomeComponents]
}

' Pacote de imóveis (planejado)
package "Properties" <<feature>> {
  [PropertyManagementScreen]
  [PropertyDetailsScreen]
  [PropertySearchScreen]
  [PropertyService] as PropertyAPI
}

' Pacote de visitas (planejado)
package "Visits" <<feature>> {
  [VisitManagementScreen]
  [VisitService] as VisitAPI
}

' Pacote de clientes (planejado)
package "Clients" <<feature>> {
  [ClientManagementScreen]
  [ClientService] as ClientAPI
}

' Pacote comum (componentes, serviços, utilitários)
package "Common" <<shared>> {
  [Components]
  [Utils]
  [Types]
  [Assets]
}

' Pacote de API
package "API" <<shared>> {
  [HttpClient]
  [ApiConfig]
  [Interceptors]
}

' Dependências entre pacotes
Auth ..> API : <<usa>>
Home ..> Common : <<usa>>
Properties ..> Common : <<usa>>
Properties ..> API : <<usa>>
Visits ..> Common : <<usa>>
Visits ..> API : <<usa>>
Clients ..> Common : <<usa>>
Clients ..> API : <<usa>>

' Observação sobre estrutura
note as note
  Estrutura atual do projeto:
  - Implementando: Auth e Home
  - Planejado: Properties, Visits e Clients
  - Usando React + TypeScript + Vite
  - Services são responsáveis pela comunicação com a API
end note

@enduml

@startuml
!theme materia

title Diagrama de Implantação - Projeto Ohara Imóveis

node "Dispositivo do Cliente" as client_device {
  artifact "Navegador Web\n(Ex: Chrome v126+, Firefox v127+)" as browser
}

cloud "Provedor de Nuvem (Ex: AWS, GCP, Azure)" {
    node "Node 1: Servidor Frontend" as frontend_node {
        node "Container Docker (web)" as frontend_container {
            artifact "Aplicação ReactJS (v19.1.0)" as frontend_app
            collections "Build Tool: Vite (v6.3.5)" as vite
        }
    }

    node "Node 2: Servidor Backend" as backend_node {
        node "Container Docker (api)" as backend_container {
            artifact "API NestJS (v11.1.3)\nServidor: Express.js" as backend_app
        }
    }

    node "Node 3: Servidor de Banco de Dados" as db_node {
        node "Container Docker (db)" as db_container {
            database "PostgreSQL (v15)" as db
        }
    }
}

' Relacionamentos e Fluxo de Comunicação
browser ..> frontend_container : <<HTTPS>>\nRequisição de páginas web
frontend_container ..> backend_container : <<HTTPS>>\nChamadas para a API REST
backend_container ..> db_container : <<TCP/IP>>\nQueries SQL

@enduml

@startuml
!theme materia

' =================================================================
' Diagrama de Sequência 1: RF001 - Cadastro de Usuário pelo Admin
' =================================================================

title Diagrama de Sequência - RF001: Admin Cria um Novo Usuário

actor "Administrador" as Admin
participant "<<Controller>>\nUsersController" as UsersController
participant "<<Service>>\nUsersService" as UsersService
participant "<<Repository>>\nUserRepository" as UserRepo
database "Banco de Dados" as DB

Admin -> UsersController : 1. POST /users com CreateUserDto
activate UsersController

UsersController -> UsersService : 2. create(dto)
activate UsersService

' O serviço agora é responsável por verificar duplicados
UsersService -> UserRepo : 3. findOne({ where: { email } })
activate UserRepo
UserRepo -> DB : 4. SELECT * FROM users WHERE email = ...
DB --> UserRepo : 5. Retorna nulo (e-mail não existe)
deactivate DB
deactivate UserRepo

UsersService -> UserRepo : 6. findOne({ where: { phone } })
activate UserRepo
UserRepo -> DB : 7. SELECT * FROM users WHERE phone = ...
DB --> UserRepo : 8. Retorna nulo (telefone não existe)
deactivate DB
deactivate UserRepo


UsersService -> UserRepo : 9. create(dto)
activate UserRepo
UserRepo --> UsersService : 10. Retorna nova instância de User
deactivate UserRepo

UsersService -> UserRepo : 11. save(newUser)
activate UserRepo
UserRepo -> DB : 12. INSERT INTO users (...)
DB --> UserRepo : 13. Retorna usuário criado com ID
deactivate DB
UserRepo --> UsersService : 14. Retorna User completo
deactivate UserRepo

UsersService --> UsersController : 15. Retorna User completo (sem a senha)
deactivate UsersService

note right of UsersController
  O Controller remove os campos
  sensíveis (password, tokenVersion)
  antes de retornar a resposta.
end note

UsersController --> Admin : 16. Resposta 201 Created com os dados do usuário criado
deactivate UsersController

@enduml

@startuml
!theme materia

' =================================================================
' Diagrama de Sequência 2: RF005 - Cliente Agenda uma Visita
' =================================================================

title Diagrama de Sequência - RF005: Agendar Visita

actor "Cliente" as Customer
participant "<<Controller>>\nVisitsController" as VisitsController
participant "<<Service>>\nVisitsService" as VisitsService
participant "<<Repository>>\nPropertiesRepository" as PropertiesRepo
participant "<<Repository>>\nVisitsRepository" as VisitsRepo
database "Banco de Dados" as DB

Customer -> VisitsController : 1. POST /visits com AgendarVisitaDto\n(inclui propertyId, dateTime)
activate VisitsController

VisitsController -> VisitsService : 2. scheduleVisit(dto, user.userId)
activate VisitsService

' O serviço primeiro verifica se a propriedade existe e está disponível
VisitsService -> PropertiesRepo : 3. findOneAvailable(dto.propertyId)
activate PropertiesRepo
PropertiesRepo -> DB : 4. SELECT * FROM properties WHERE id = ... AND status = 'Disponível'
DB --> PropertiesRepo : 5. Retorna dados da Propriedade
deactivate DB
PropertiesRepo --> VisitsService : 6. Retorna a Propriedade
deactivate PropertiesRepo

' Em seguida, verifica se já não há uma visita no mesmo horário para aquele imóvel
VisitsService -> VisitsRepo : 7. findByPropertyAndDateTime(dto.propertyId, dto.dateTime)
activate VisitsRepo
VisitsRepo -> DB : 8. SELECT * FROM visits WHERE propertyId = ... AND dateTime = ...
DB --> VisitsRepo : 9. Retorna nulo (horário livre)
deactivate DB
VisitsRepo --> VisitsService : 10. Retorna nulo
deactivate VisitsRepo

' Com tudo validado, a visita é criada
VisitsService -> VisitsRepo : 11. create({ propertyId, userId, dateTime })
activate VisitsRepo
VisitsRepo --> VisitsService : 12. Retorna nova instância de Visit
deactivate VisitsRepo

VisitsService -> VisitsRepo : 13. save(newVisit)
activate VisitsRepo
VisitsRepo -> DB : 14. INSERT INTO visits (...)
DB --> VisitsRepo : 15. Retorna visita criada com ID
deactivate DB
VisitsRepo --> VisitsService : 16. Retorna Visit completa
deactivate VisitsRepo

VisitsService --> VisitsController : 17. Retorna Visit confirmada
deactivate VisitsService

VisitsController --> Customer : 18. Resposta 201 Created com os dados da visita
deactivate VisitsController

@enduml