Setup do Ambiente Local

Guia passo a passo para configurar o ambiente de desenvolvimento local do projeto UNICEF Portugal.

Pré-requisitos

Ferramenta	Versão mínima	Notas
Visual Studio	2019	Com workload ASP.NET e desenvolvimento web
Docker Desktop	-	Para SQL Server local
Git	-	Acesso ao Azure DevOps
Azure CLI	-	Para acesso a recursos Azure (backups, etc.)

1. Clonar o repositório

git clone https://dev.azure.com/double-pt/Unicef/_git/Unicef C:/repos/unicef
cd C:/repos/unicef

# O repositório é um bare repo, criar working copy:
git worktree add ../unicef-work main
cd ../unicef-work

2. Configurar SQL Server com Docker

Iniciar uma instância de SQL Server 2019 via Docker na porta 1434 (para não conflitar com eventuais instâncias locais na porta 1433):

docker run \
  -e "ACCEPT_EULA=Y" \
  -e "SA_PASSWORD=Str0ngP@ss!" \
  -p 1434:1433 \
  --name unicef-sql \
  -d mcr.microsoft.com/mssql/server:2019-latest

Para verificar que o container está a correr:

docker ps --filter name=unicef-sql

3. Importar bases de dados

Instalar sqlpackage (se necessário)

dotnet tool install -g microsoft.sqlpackage

Importar a base de dados Umbraco

O ficheiro databaseUmb.bacpac tem aproximadamente 60MB e a importação demora cerca de 1 minuto:

sqlpackage /Action:Import \
  /SourceFile:"databaseUmb.bacpac" \
  /TargetServerName:localhost,1434 \
  /TargetDatabaseName:unc \
  /TargetUser:sa \
  /TargetPassword:'Str0ngP@ss!' \
  /TargetTrustServerCertificate:True

Importar a base de dados EasyPay

O ficheiro databaseEasyPay.bacpac tem aproximadamente 1MB:

sqlpackage /Action:Import \
  /SourceFile:"databaseEasyPay.bacpac" \
  /TargetServerName:localhost,1434 \
  /TargetDatabaseName:EasyPay \
  /TargetUser:sa \
  /TargetPassword:'Str0ngP@ss!' \
  /TargetTrustServerCertificate:True

4. Configurar connection strings

Editar o ficheiro Web/Web.config e atualizar a secção connectionStrings:

<connectionStrings>
  <remove name="umbracoDbDSN" />
  <add name="umbracoDbDSN"
       connectionString="Server=localhost,1434;Database=unc;User Id=sa;Password=Str0ngP@ss!"
       providerName="System.Data.SqlClient" />
  <add name="Payments"
       connectionString="Server=localhost,1434;Database=EasyPay;User Id=sa;Password=Str0ngP@ss!"
       providerName="System.Data.SqlClient" />
</connectionStrings>

Atenção

Não fazer commit destas alterações ao Web.config. Estas connection strings são apenas para desenvolvimento local.

5. Restaurar pacotes NuGet

O projeto usa o modelo antigo de packages.config. Alguns pacotes são proprietários (CreateIt.Toolkit) e não existem no nuget.org.

# Descarregar nuget.exe
curl -sL -o nuget.exe https://dist.nuget.org/win-x86-commandline/latest/nuget.exe

# Restaurar pacotes
./nuget.exe restore UNC.PublicPortal.sln

Resolvido na branch feature/local-dev-setup

A branch feature/local-dev-setup no Azure DevOps já inclui o NuGet.config e os pacotes CreateIt.Toolkit necessários. Se estiver a usar esta branch, o NuGet restore funciona sem passos adicionais.

Pacotes CreateIt.Toolkit (apenas se necessário manualmente)

Os pacotes CreateIt.Toolkit.UmbracoCms, CreateIt.Toolkit.UmbracoCms.Foyer e CreateIt.Toolkit.Mvc são proprietários e não estão disponíveis no NuGet público. Os DLLs podem ser obtidos a partir do site em produção via Kudu:

# Obter credenciais de deploy
az webapp deployment list-publishing-credentials \
  --name uncwebprd --resource-group unc-prd \
  --subscription 2e6c7ed6-c6f8-4058-901c-c3113a4df82a \
  --query "{user:publishingUserName,pass:publishingPassword}" -o json

# Descarregar DLLs do site em produção
curl -u '$uncwebprd:<password>' \
  "https://uncwebprd.scm.azurewebsites.net/api/vfs/site/wwwroot/bin/CreateIt.Toolkit.UmbracoCms.dll" \
  -o packages/CreateIt.Toolkit.UmbracoCms.2.2.4/lib/net452/CreateIt.Toolkit.UmbracoCms.dll

curl -u '$uncwebprd:<password>' \
  "https://uncwebprd.scm.azurewebsites.net/api/vfs/site/wwwroot/bin/CreateIt.Toolkit.UmbracoCms.Foyer.dll" \
  -o packages/CreateIt.Toolkit.UmbracoCms.Foyer.2018.6.28.1/lib/net452/CreateIt.Toolkit.UmbracoCms.Foyer.dll

curl -u '$uncwebprd:<password>' \
  "https://uncwebprd.scm.azurewebsites.net/api/vfs/site/wwwroot/bin/CreateIt.Toolkit.Mvc.dll" \
  -o packages/CreateIt.Toolkit.Mvc.2018.6.28.1/lib/net452/CreateIt.Toolkit.Mvc.dll

Criar as pastas de destino antes de executar os comandos acima.

6. Compilar e executar

1. Abrir UNC.PublicPortal.sln no Visual Studio 2019 (recomendado para .NET Framework 4.5.2)
2. Build: Ctrl+Shift+B
3. Executar com debug: F5 (usa IIS Express na porta SSL 44388)
4. O site abre em https://localhost:44388

Como funciona o frontend

O AngularJS não corre como processo separado. É carregado pelo template Umbraco StartView.cshtml, que serve a página HTML com o ng-app="unicef". O Angular faz bootstrap e toma conta da navegação, chamando a API /umbraco/Api/ContentApi/GetData/ para cada página. Ver secção AngularJS Frontend para mais detalhes.

Obtenção de Backups da Base de Dados

Não utilizar os ficheiros .bacpac do repositório

Os ficheiros databaseUmb.bacpac e databaseEasyPay.bacpac existentes no repositório são antigos e não devem ser utilizados para desenvolvimento ativo. A presença de ficheiros binários grandes no repositório Git é uma má prática que aumenta desnecessariamente o tamanho do clone. Estes ficheiros devem ser removidos do repositório numa futura limpeza.

Para trabalhar com dados atualizados, exportar um backup fresco diretamente da base de dados Azure SQL.

Obter backup fresco da produção

az sql db export \
  --name uncdb-prd \
  --server uncsqlsrv-prd \
  --resource-group unc-prd \
  --subscription 2e6c7ed6-c6f8-4058-901c-c3113a4df82a \
  --storage-key-type StorageAccessKey \
  --storage-key "<key>" \
  --storage-uri "https://uncstorageprd.blob.core.windows.net/backups/uncdb-prd.bacpac" \
  --admin-user "<admin>" \
  --admin-password "<password>"

Substituir <key>, <admin> e <password> pelos valores reais (disponíveis junto da equipa — o Key Vault unc-prd-vault existe mas não é utilizado pelo projeto).

Media (imagens)

As imagens do site estão no Azure Blob Storage (uncstorageprd, container media, ~4.023 ficheiros, ~2.2 GB). O site funciona sem imagens locais, mas para desenvolvimento visual completo:

mkdir -p Web/media
az storage blob download-batch \
  --destination Web/media --source media \
  --account-name uncstorageprd \
  --subscription 2e6c7ed6-c6f8-4058-901c-c3113a4df82a

Nota

Algumas imagens referenciadas no conteúdo podem não existir no blob storage (referências órfãs). Isto não afeta o funcionamento do site — apenas resultam em imagens em falta (404).

Problemas Conhecidos

"Unable to load virtual directory"

Causa: A pasta .vs/ contém configuração de IIS Express com caminhos inválidos.

Solução: Fechar o Visual Studio, eliminar a pasta .vs/ na raiz do projeto e reabrir.

rm -rf .vs/

Pacotes NuGet "CreateIt.Toolkit" não encontrados

Causa: São pacotes proprietários do desenvolvedor original (CreateIT/BetacodeTech) e não existem no NuGet público.

Solução: Usar a branch feature/local-dev-setup que já inclui o NuGet.config e os pacotes .nupkg. Alternativamente, descarregar os DLLs directamente da produção via Kudu API (ver secção 5).

Primeiro arranque demora 1-2 minutos

Causa: O Umbraco 7 reconstrói a cache XML de conteúdo na primeira execução. Com ~4.468 nós e tabelas com centenas de milhares de registos, este processo é demorado.

Solução: Aguardar. Após o primeiro arranque, os carregamentos seguintes são mais rápidos (desde que o processo não seja terminado).

Imagens em falta (404)

Causa: Imagens referenciadas no conteúdo que podem não existir no blob storage ou que estão em caminhos diferentes localmente.

Solução: Descarregar media do blob storage (ver secção acima). Algumas imagens podem ser referências órfãs — isto não afeta o funcionamento.

Estrutura do projeto

UNC.PublicPortal.sln
├── Web/                       # Projeto principal (Umbraco + API controllers)
│   ├── Views/                # Razor views do Umbraco
│   ├── Controllers/          # API e MVC controllers
│   ├── Assets/               # CSS, imagens estáticas
│   ├── App_Plugins/          # Plugins Umbraco
│   ├── App_Data/             # Dados runtime Umbraco
│   └── Web.config            # Configuração principal
├── Business/                  # ViewModels e lógica de negócio
├── Definitions/               # Modelos e interfaces
├── DB/                        # Projeto SQL Server
├── PaymentsManager/           # Gestão de pagamentos
├── Payments/                  # DAL para pagamentos
├── Templates/                 # AngularJS frontend
│   ├── app/                  # Source (index.html, Assets/js/, Assets/ngviews/)
│   └── dist/                 # Build de produção (minificado)
├── MassiveLuceneAnalyser/     # Analisador Lucene personalizado
├── databaseUmb.bacpac        # Backup da BD Umbraco
└── databaseEasyPay.bacpac    # Backup da BD EasyPay

Descrição dos projetos

Projeto	Descrição
Web	Projeto principal ASP.NET com Umbraco CMS. Contém controllers, views Razor e configuração
Business	Camada de lógica de negócio e ViewModels partilhados
Definitions	Modelos de dados e interfaces/contratos
DB	Projeto SQL Server Database (schema e migrations)
PaymentsManager	Lógica de gestão de pagamentos (EasyPay, PayPal)
Payments	Data Access Layer para a base de dados de pagamentos
Templates	Frontend AngularJS — páginas públicas do site
MassiveLuceneAnalyser	Analisador Lucene personalizado para pesquisa no site