# Donc -- Arquitetura IA-First

**Versao:** v2.0 -- Mar 2026

## 01 -- Visao Geral

Plataforma de gestao de servicos tecnicos (Field Service Management).

**Projetos Ativos na Solution CrowdsFull.sln:**

| Projeto | Framework | Tipo |
|---------|-----------|------|
| Admin/ | .NET 4.8 | Dashboard (WebForms) |
| ApiV2/ | .NET 4.8 | API externa (Web API) |
| WebHubDonc/ | .NET 6.0 | Hub integracoes (ASP.NET Core) |
| DoncMobile.API/ | .NET 8.0 | API mobile (ASP.NET Core, migrar .NET 10) |
| DoncMobile.App/ | .NET 10.0 | App Android (MAUI) |
| Servico/ | .NET 4.8 | Jobs background (Console) |
| Api/ | .NET 4.8 | Core lib (EF6 / Go4YouEntities) |

## 02 -- Mapa de Projetos

### Aplicacoes Web (publicadas)

| Projeto | Framework | Tipo | ORM | Proposito | Status |
|---------|-----------|------|-----|-----------|--------|
| Admin | .NET 4.8 | WebForms | EF6 | Dashboard administrativo principal | Ativo |
| ApiV2 | .NET 4.8 | Web API | EF6 | API externa v2 -- agendamento, jobs, webhooks | Ativo |
| WebHubDonc | .NET 6.0 | ASP.NET Core | EF6 + EF Core 7 | Hub de integracoes (.NET 6 fora de suporte desde Nov/2024) | Ativo |
| DoncMobile.API | .NET 8.0 | ASP.NET Core | Dapper | Backend do app mobile -- sync, auth JWT, uploads | Ativo |
| Avulsos | .NET 4.8 | WebForms | EF6 | Pagina de avaliacao enviada via SMS/WhatsApp | Migrar |
| ApiPrj | .NET 4.8 | ASMX | EF6 | Servicos legados -- app antigo em migracao | Legado |
| Gsr (Prestador) | .NET 4.8 | WebForms | EF6 | Portal do prestador -- nao publicado mais | Morto |

### Background Service

| Projeto | Framework | Tipo | Proposito |
|---------|-----------|------|-----------|
| Servico | .NET 4.8 (Console) | Task Scheduler | Jobs de integracao ERP (HubSoft, IXC, MK, Cybelar, Berlanda, LojasMM, SSW) e automacoes periodicas |

### Mobile

| Projeto | Framework | Proposito |
|---------|-----------|-----------|
| DoncMobile.App | .NET 10.0 MAUI | App para tecnicos em campo (Android) |

### Bibliotecas

| Projeto | Framework | Proposito | Status |
|---------|-----------|-----------|--------|
| Api | .NET 4.8 | Core -- Go4YouEntities (EF6 DbContext), models, logica de negocio | Ativo |
| DoncRouter | .NET 4.8 | Algoritmo de roteamento e distribuicao inteligente | Ativo |
| ChartJS.Helpers | .NET 4.8 | Helpers Chart.js para Admin | Avaliar |
| eNotas, iugu.net, pagarMe, SigmaSegware, Movidesk.ApiClient, WebHubDoncNavagador | -- | Nao usados | Remover |

## 03 -- Problemas Identificados

- **Zero testes** -- Nenhum projeto de teste. Sem testes, refatoracao e suicidio.
- **Zero CI/CD** -- Sem GitHub Actions. Deploy manual. Impossibilita pipeline automatizado.
- **WebHubDonc fora de suporte** -- .NET 6 LTS perdeu suporte em Nov/2024.
- **4 frameworks diferentes** -- .NET 4.8, 6.0, 8.0 e 10.0 convivendo.
- **Projetos sobrepostos** -- ApiV2, Servico, WebHubDonc e ApiPrj tem responsabilidades que se cruzam.
- **ORM inconsistente** -- EF6 nos legados, Dapper no mobile, EF Core no WebHub.
- **Sem contexto IA** -- Nao existe CLAUDE.md, AI_CONTEXT.md ou glossario de dominio.
- **8 projetos mortos** -- Projetos inativos poluem a solution.

## 04 -- Grafo de Dependencias

O projeto Api (Go4YouEntities / EF6) e o coracao da solucao. E referenciado por 6 projetos.

```
                  Api (Go4YouEntities / EF6 / .NET 4.8)
                    |
    +-------+-------+-------+-----------+
    |       |       |       |           |
  Admin   ApiV2  ApiPrj  Servico   WebHubDonc
  (.NET 4.8) (.NET 4.8) (.NET 4.8) (.NET 4.8) (.NET 6.0)
    |
    +--- DoncRouter (algoritmo de rotas)

// Projetos independentes (nao referenciam Api)
  DoncMobile.API (.NET 8.0 / Dapper)  -- acessa banco direto, migrar para .NET 10
  DoncMobile.App (.NET 10.0 / MAUI)   -- consome DoncMobile.API
```

> **ALERTA:** Risco critico: Go4YouEntities. Se alguem alterar uma entidade no projeto Api sem testes, 6 projetos podem quebrar ao mesmo tempo.

## 05 -- Clean Architecture (Alvo)

A arquitetura alvo segue o padrao Clean Architecture (Onion Architecture).

| Camada | Descricao | Dependencia |
|--------|-----------|-------------|
| Donc.Domain | Entities, Enums, Value Objects, Interfaces de repositorio. Zero dependencias externas. | O coracao do sistema |
| Donc.Application | Commands, Queries (CQRS via MediatR), DTOs, Validators (FluentValidation), Mappings. | Referencia Domain |
| Donc.Infrastructure | DoncDbContext (EF Core 10), Repositories, servicos externos, clients de API. | Referencia Application |
| Apresentacao | Admin (Razor Pages), Donc.Integracoes (API REST), DoncMobile.API, Donc.Workers, DoncMobile.App | Referencia App + Infra |

**Regra de Ouro:** Domain nao referencia nada. Application referencia so Domain. Infrastructure implementa as interfaces.

**Por que CQRS com MediatR?**
- Cada feature em um arquivo isolado (Command + Handler) -- a IA cria/modifica sem impactar outras
- Testes simples: 1 handler = 1 teste unitario
- Codigo previsivel -- a IA sabe exatamente onde criar coisas novas
- Separacao leitura/escrita reduz bugs e conflitos

## 05b -- Decisao Arquitetural: Modular Monolith com MediatR

> ADR completo: [adr-001-modular-monolith.md](adr-001-modular-monolith.md)

**Decisao aprovada em 2026-05-29.**

Toda funcionalidade nova entra no padrao **Modular Monolith com MediatR (CQRS Leve)**, adotavel imediatamente nos projetos existentes e compativel com a Clean Architecture alvo (Etapa 4).

### Mapa de Modulos e Bounded Contexts

| Modulo | Responsabilidade Principal | Entidades-raiz |
|--------|---------------------------|----------------|
| `OrdemServico` | Ciclo de vida da OS, checklist, produtos, filas | `Pedido`, `PedidoItem`, `TipoJob` |
| `Profissional` | Profissionais, parceiros, cobertura geografica | `Motoqueiro`, `Parceiro`, `FaixaCEP` |
| `Agendamento` | Janelas, reservas, reagendamento | `DisponibilidadeAgenda` |
| `Roteirizacao` | Distribuicao, rotas, DoncRouter | `Saida`, `RotaContrato` |
| `Financeiro` | Fechamento diario, comissoes | `FechamentoDiario` |
| `Integracoes` | ERPs externos, fila de importacao | `FilaIntegracaoPedido`, `IntegracaoJob` |
| `Notificacao` | Webhooks de saida, push, e-mail | `PostSchedule`, `Gatilho` |
| `Tenancy` | Isolamento multi-tenant, usuarios | `ContratoSaa`, `Estabelecimento` |

> Detalhes completos de cada modulo: [modulos.md](modulos.md)

### Regras de Comunicacao entre Modulos

1. Modulo A chama modulo B apenas pela **interface publica** (`IServicoX`)
2. Modulo A nunca executa `SELECT` diretamente em tabela do modulo B
3. Reacoes assincronas usam **eventos de dominio** (`INotification` do MediatR)
4. Nenhum modulo passa `ContratoSaasId` como parametro — vem sempre de `IContextoTenant`

### Como o Tenant e Resolvido na Nova Arquitetura

```
Requisicao chega (api_key / JWT / host)
  -> Middleware TenancyMiddleware resolve ContratoSaasId + EstabelecimentoId
    -> Popula IContextoTenant (scoped por request)
      -> Todos os handlers injetam IContextoTenant
        -> Nunca passam contratoSaasId como parametro
```

```csharp
// Interface central do modulo Tenancy
public interface IContextoTenant
{
    int ContratoSaasId { get; }
    int EstabelecimentoId { get; }
    string AppName { get; }
}
```

> Guia pratico com exemplos de Command, Query, Controller e anti-patterns: [nova-funcionalidade.md](nova-funcionalidade.md)

---

## 06 -- Estrutura de Projetos (Alvo)

```
Donc.sln
├── src/
│   ├── Donc.Domain/                  -- Entities, Enums, Interfaces (zero dependencias)
│   ├── Donc.Application/             -- Commands, Queries (CQRS), DTOs, Validators
│   ├── Donc.Infrastructure/          -- EF Core 10, Repositories, APIs externas
│   ├── Donc.Admin/                   -- Dashboard (Razor Pages .NET 10)
│   ├── Donc.Integracoes/             -- APIs + Webhooks + Avaliacao
│   ├── Donc.Workers/                 -- Background Jobs (Hangfire)
│   ├── DoncMobile.API/               -- API Mobile (.NET 8 -> migrar .NET 10)
│   └── DoncMobile.App/               -- App MAUI Android
├── tests/
│   ├── Donc.UnitTests/               -- xUnit + Moq
│   └── Donc.IntegrationTests/
├── docs/
├── .github/workflows/                -- CI/CD pipelines
├── CLAUDE.md
├── AI_CONTEXT.md
└── DOMAIN_GLOSSARY.md
```

## 07 -- Stack Tecnologico

| Camada | Tecnologia | Versao | Justificativa |
|--------|-----------|--------|---------------|
| Framework | .NET 10 | LTS | Suporte ate Nov 2028. DoncMobile.App ja usa. |
| ORM | EF Core 10 | 10.x | Substitui EF6 gradualmente. |
| Micro-ORM | Dapper | 2.x | Queries de alta performance. Mantem no DoncMobile.API. |
| Mediator/CQRS | MediatR | 12.x | Separa leitura/escrita. Features isoladas. |
| Validacao | FluentValidation | 11.x | Regras declarativas e testaveis. |
| Mapeamento | Mapster | 7.x | Mais performatico que AutoMapper. |
| Testes | xUnit + Moq | 2.x / 4.x | Padrao da industria .NET. |
| Logs | Serilog | 3.x | Log estruturado. |
| Background Jobs | Hangfire | 1.8.x | Substitui Task Scheduler. Dashboard visual. |
| API Docs | Swagger / OpenAPI | 6.x | Documentacao automatica de endpoints. |
| Frontend Admin | Razor Pages | .NET 10 | Mais adotado que Blazor. IA trabalha melhor. |
| Mobile | .NET MAUI | .NET 10 | App Android para tecnicos. |

## 08 -- Mapa de Deploy

| Deploy | Projeto | Producao | Teste | IIS |
|--------|---------|----------|-------|-----|
| WEB | Donc.Admin | admin.donc.com.br | teste-admin.donc.com.br | Site 1 |
| API | Donc.Integracoes | api.donc.com.br | teste-api.donc.com.br | Site 2 |
| API | DoncMobile.API | app-api.donc.com.br | teste-app-api.donc.com.br | Site 3 |
| WORKER | Donc.Workers | Windows Service | Windows Service (teste) | Service |
| APP | DoncMobile.App | Google Play | APK interno | N/A |

## 09 -- Principio Fundamental

A ordem de execucao nao e arbitraria. Cada etapa depende da anterior.

```
PIPELINE CI/CD -> TESTES -> IA OPERA -> IA REFATORA -> CONSOLIDA -> FRONTEND
```

- ERRADO: Refatorar primeiro -- gastar 3-4 meses refatorando manualmente sem testes, sem pipeline, sem IA.
- CORRETO: Pipeline + IA primeiro -- instrumentar pipeline e testes em 2-3 semanas. IA comeca a trabalhar no codigo atual. Depois a propria IA executa a refatoracao como tasks do Asana.

## 10 -- Etapa 1 -- Pipeline CI/CD (Semana 1-2)

Configurar GitHub Actions e contexto IA para todos os projetos ativos.

| Projeto | Framework | Build System | Workflow |
|---------|-----------|-------------|----------|
| Admin | .NET 4.8 | msbuild + nuget restore | admin-ci.yml |
| ApiV2 | .NET 4.8 | msbuild + nuget restore | apiv2-ci.yml |
| WebHubDonc | .NET 6.0 | dotnet build | webhub-ci.yml |
| DoncMobile.API | .NET 8.0 (migrar .NET 10) | dotnet build + test | mobile-api-ci.yml |
| DoncMobile.App | .NET 10.0 | dotnet build | mobile-app-ci.yml |

**Entregaveis:** CLAUDE.md na raiz, AI_CONTEXT.md por projeto (5 arquivos), DOMAIN_GLOSSARY.md, GitHub Actions para todos, ambientes de teste no IIS.

## 11 -- Etapa 2 -- Testes (Semana 3-4)

| Fluxo | Projeto | Tipo de Teste | Prioridade |
|-------|---------|---------------|------------|
| Criar / Editar OS | Api (core) | Unitario | Critico |
| Distribuir OS para profissional | Api + DoncRouter | Unitario | Critico |
| Fechar / Encerrar OS | Api (core) | Unitario | Critico |
| Integracoes ERP | Servico | Integracao | Alto |
| Sync do app mobile | DoncMobile.API | Unitario + Integracao | Alto |
| Autenticacao JWT | DoncMobile.API | Unitario | Alto |
| Agendamento (API externa) | ApiV2 | Unitario | Medio |
| Webhooks de integracao | ApiV2 / WebHubDonc | Integracao | Medio |

## 12 -- Etapa 3 -- IA Operacional (Semana 5-6)

A IA comeca a executar tasks reais do Asana nos projetos como estao hoje, sem refatoracao.

Exemplos de tasks iniciais: Melhorar layout da tela de OS (Admin), Ocultar campos na tela de Clientes (Admin), Corrigir sync de fotos (DoncMobile.API), Melhorar tela de OS no app (DoncMobile.App), Novo endpoint de relatorio (ApiV2).

## 13 -- Etapa 4 -- IA Refatora (Mes 2)

A refatoracao vira uma sequencia de tasks no Asana. Cada uma isolada, testavel e reversivel.

Tasks de refatoracao:
1. "Criar projeto Donc.Domain com entidades base"
2. "Criar projeto Donc.Application com MediatR"
3. "Criar projeto Donc.Infrastructure com EF Core 10"
4. "Migrar DoncMobile.API de .NET 8 para .NET 10"
5. Task por task: "Migrar endpoint X para Clean Architecture"

**Regra:** O codigo antigo continua funcionando em paralelo. So e removido quando o codigo novo esta validado em producao.

## 14 -- Etapa 5 -- Consolidacao (Mes 3-4)

**Consolidacoes:**
- ApiV2 + WebHubDonc + Avulsos -> Donc.Integracoes
- Servico -> Donc.Workers (Hangfire substitui Task Scheduler)
- CrowdsFull.sln -> Donc.sln

**Remocoes:** Gsr, eNotas, iugu.net, pagarMe, SigmaSegware, Movidesk.ApiClient, WebHubDoncNavagador, TesteRotas, ApiPrj (apos migracao).

## 15 -- Etapa 6 -- Frontend (Mes 5+)

Migracao gradual por modulo. Cada tela do Admin WebForms vira uma Razor Page em .NET 10.

1. Migrar Admin para Razor Pages (.NET 10) -- modulo por modulo
2. Aposentar EF6 completamente
3. Todos os projetos em .NET 10+

## 16 -- Pipeline IA-First

```
ASANA (Task criada) -> CLAUDE (Executa codigo) -> GITHUB (PR + Actions) -> TESTE (Deploy staging) -> PRODUCAO (Deploy final)
```

1. Task criada no Asana com criterios de aceitacao
2. Claude le CLAUDE.md + AI_CONTEXT.md, cria branch feature/asana-{id}-descricao, implementa + testes, cria PR
3. GitHub Actions: build automatico, testes unitarios, deploy no ambiente de teste
4. Validacao no teste pelo suporte
5. PR aprovado -> merge na main -> deploy automatico via Web Deploy -> IIS

## 17 -- Glossario de Dominio

| Termo | Definicao | Entidade |
|-------|-----------|----------|
| OS | Ordem de Servico -- unidade basica de trabalho | OrdemServico |
| Job | Sinonimo de OS nas APIs de integracao | OrdemServico |
| Profissional | Tecnico que executa a OS em campo | Profissional |
| Parceiro | Empresa terceirizada que fornece profissionais | Parceiro |
| Estabelecimento | Filial ou loja do cliente contratante | Estabelecimento |
| Rota | Sequencia otimizada de OS para um profissional/dia | Rota |
| Distribuicao | Processo de alocar OS para profissionais | Distribuicao |

## 18 -- CI/CD -- GitHub Actions

| Arquivo | Projeto | Build | Deploy Target |
|---------|---------|-------|---------------|
| admin-ci.yml | Admin | msbuild | teste-admin -> admin (IIS) |
| apiv2-ci.yml | ApiV2 | msbuild | teste-apiv2 -> apiv2 (IIS) |
| webhub-ci.yml | WebHubDonc | dotnet | teste-webhub -> webhub (IIS) |
| mobile-api-ci.yml | DoncMobile.API | dotnet | teste-app-api -> app-api (IIS) |
| mobile-app-ci.yml | DoncMobile.App | dotnet | Build APK (artifact) |

## 19 -- Projetos a Remover

| Projeto | Motivo | Destino | Etapa |
|---------|--------|---------|-------|
| Gsr | Nao publicado | Remover | 5 |
| eNotas | Nao usado | Remover | 5 |
| iugu.net | Nao usado | Remover | 5 |
| pagarMe | Nao usado | Remover | 5 |
| SigmaSegware | Nao usado | Remover | 5 |
| Movidesk.ApiClient | Nao usado | Remover | 5 |
| WebHubDoncNavagador | RPA nao usado | Remover | 5 |
| TesteRotas | Utilitario temp. | Remover | 5 |
| ApiPrj | Legado em migracao | Remover apos migracao | 5 |
| Avulsos | Migrar funcionalidade | -> Donc.Integracoes | 5 |
| ApiV2 | Consolidar | -> Donc.Integracoes | 5 |
| WebHubDonc | Consolidar | -> Donc.Integracoes | 5 |
| Servico | Modernizar | -> Donc.Workers | 5 |
| Api (core) | Aposentar EF6 | -> Donc.Domain/Infra | 6 |

> **ALERTA:** O projeto Api (core) e o ultimo a sair. So pode ser removido na Etapa 6.

## 20 -- Checklist por Etapa

### Etapa 1 -- Pipeline CI/CD (Semana 1-2)
- [ ] CLAUDE.md criado na raiz
- [ ] AI_CONTEXT.md criado para cada projeto ativo (5 arquivos)
- [ ] DOMAIN_GLOSSARY.md com termos do negocio
- [ ] GitHub Actions configurado para Admin e ApiV2 (msbuild)
- [ ] GitHub Actions configurado para WebHubDonc, DoncMobile.API, DoncMobile.App (dotnet)
- [ ] Ambientes de teste configurados no IIS
- [ ] Deploy automatizado funcionando

### Etapa 2 -- Testes (Semana 3-4)
- [ ] Projet Donc.UnitTests criado (xUnit + Moq)
- [ ] Testes para Criar / Editar / Fechar OS
- [ ] Testes para Distribuicao de OS
- [ ] Testes para Sync do app mobile
- [ ] Testes para Autenticacao JWT
- [ ] Testes integrados no GitHub Actions

### Etapa 3 -- IA Operacional (Semana 5-6)
- [ ] Claude criou pelo menos 3 PRs que passaram no build
- [ ] Deploy automatico no ambiente de teste funcionando
- [ ] Suporte validou pelo menos 1 PR
- [ ] Pipeline completo validado: Asana -> Claude -> PR -> Build -> Deploy Teste -> Aprovacao -> Producao

### Etapa 4 -- IA Refatora (Mes 2)
- [ ] Donc.Domain criado com entidades principais
- [ ] Donc.Application criado com MediatR + Commands/Queries
- [ ] Donc.Infrastructure criado com DoncDbContext (EF Core 10)
- [ ] Pelo menos 5 endpoints migrados para Clean Architecture
- [ ] Todos os testes existentes continuam passando

### Etapa 5 -- Consolidacao (Mes 3-4)
- [ ] Donc.Integracoes criado (ApiV2 + WebHubDonc + Avulsos)
- [ ] Donc.Workers criado com Hangfire
- [ ] Projetos mortos removidos
- [ ] RPA removido
- [ ] Solution renomeada: CrowdsFull.sln -> Donc.sln
- [ ] Solution reduzida de 18 para ~8 projetos

### Etapa 6 -- Frontend (Mes 5+)
- [ ] Admin migrado para Razor Pages (.NET 10)
- [ ] EF6 completamente substituido por EF Core 10
- [ ] Projeto Api (legado core) aposentado
- [ ] Todos os projetos em .NET 10+