shoc-backend/docs/work-orders/phase-0/dar-domain-architecture-review.md

# DAR — Domain Architecture Review (Work Orders)

**Fase:** 0  
**Status:** Draft para sign-off CTO  
**Referência:** [roadmap-work-orders-board.md](../../roadmap-work-orders-board.md) §4–5

---

## 1. Objetivo

Formalizar o modelo de domínio operacional do Schedule Board antes de qualquer migration de schema board ou contrato de listagem semanal.

---

## 2. Agregados e limites (anti God Entity)

```mermaid
flowchart TB
    subgraph root [AggregateRoot_WorkOrder]
        CORE[Core_Lifecycle_Assignment]
        SCH[Scheduling_slice]
        TRK[Tracking_slice]
        COMP[Completion_slice]
        ANA[Analytics_slice]
    end
    subgraph separate [Agregado_separado]
        DISP[Dispatch_fonte_vendor]
    end
    AUD[WorkOrderAuditLog_append_only]
    CORE --> SCH
    CORE --> TRK
    CORE --> ANA
    CORE --> COMP
    CORE --> DISP
    CORE --> AUD
```

| Agregado / Slice | Responsabilidade | Persistência Fase 0 |
|------------------|------------------|---------------------|
| **Core** | Id, WoNumber, Type, LifecycleStatus, SiteCode, LocationId, DueDate, AssignTo, Title, RowVersion, PrimaryDispatchId | Colunas em `workOrders` |
| **Scheduling** | ScheduledDate, ScheduledStart/End, TargetWeek, ScheduleWeekOnly | Colunas em `workOrders` |
| **Tracking** | OriginalWeek, OriginalDate (set-once) | Colunas em `workOrders` |
| **Analytics** | RescheduleCount, CarriedOver | Colunas em `workOrders` |
| **Completion** | DocStatus, refs attachments | Coluna DocStatus + attachments existentes |
| **Dispatch** | Vendor, tech, status portal | Tabela `Dispatches` + RowVersion |
| **Audit** | Rastreabilidade imutável | `WorkOrderAuditLogs` |

**Proibido:** `VendorId`, `TechName`, `TechPhone` canônicos na entidade WorkOrder. Vendor sempre via Dispatch primário.

---

## 3. Fonte da verdade por conceito

| Conceito | Fonte da verdade | Proibido |
|----------|------------------|----------|
| Status operacional | `LifecycleStatus` (10 valores FE) | String livre `Status` como canônico |
| Past Due | Derivado on-read (`ScheduledDate < hoje` AND NOT terminal) | Misturar no enum lifecycle |
| Vendor / Tech | Dispatch primário (`PrimaryDispatchId`) | Duplicar na WO |
| Schedule | Scheduling slice | Duplicar no core sem slice lógico |
| Completion | `DocStatus` | Inferir só de dispatch signoff |
| Reschedule / CarriedOver | Analytics + domain events | Job blind overwrite |
| WO# | `InternalWONumber` / `WorkerOrderNumber` com regra 11 dígitos (Fase 2+) | Dois números sem regra |
| POC | `WorkOrderContacts` + Notes | Só no detalhe sem contato |

---

## 4. Lifecycle Status vs Operational Flags

```text
LifecycleStatus  → enum único (10 valores alinhados ao frontend)
OperationalFlags → PastDue (derivado on-read; cache opcional Fase 5)
LegacyStatus     → string original read-only (migration Fase 0)
```

Filtro de status no board = `LifecycleStatus`. Overlay Past Due = flag derivada. Bloqueio de edição = validação sobre flag (Fase 2).

### Mapeamento legado → LifecycleStatus

| Legado (`Status`) | LifecycleStatus |
|-------------------|-----------------|
| Open | Incomplete |
| InProgress / In Progress | InProgress |
| Completed / Complete | Complete |
| Cancelled / Canceled | Canceled |
| OnHold / On Hold | OnHold |
| Desconhecido | Incomplete + NeedsReview |

---

## 5. CarriedOver — justificativa

| | isPastDue | carriedOver |
|--|-----------|-------------|
| Natureza | Estado pontual | Métrica histórica acumulada |
| Persistir | Não (derivado) | Sim (contador) |
| Incremento | N/A | Somente via domain event `WeekRolled` (Fase 5) |

---

## 6. Scheduling Aggregate Growth Watchlist

Campos que **não** entram em Scheduling sem ARB review:

- `MoveReason`, `MoveUser`, `MoveCategory`, `MoveSource`

Metadados de movimentação → Audit Event Contract.

**Gate:** slice Scheduling > 8 campos operacionais → ARB obrigatório.  
Contagem Fase 0: ScheduledDate, ScheduledStart, ScheduledEnd, TargetWeek, ScheduleWeekOnly, OriginalWeek, OriginalDate (tracking separado) — dentro do limite.

---

## 7. Jobs — domínio primeiro

| Job | Papel |
|-----|-------|
| Past Due diário | Cache refresh opcional; on-read sempre correto |
| Carried Over semanal | Dispara `WeekRolled` → incrementa contador + audit system |
| Promoção Overdue type | Derivado on-read |
| Audit | Síncrono em toda mutação desde Fase 0 |

**Regra de ouro:** Jobs nunca são a única fonte da verdade.

---

## 8. Critérios de aceite (sign-off CTO)

- [ ] Zero campos vendor canônicos na WO
- [ ] Agregados documentados e refletidos no schema Fase 0
- [ ] Persistido vs derivado validado com PO (ver `dar-persisted-vs-derived-matrix.md`)
- [ ] Watchlist Scheduling registrada
- [ ] Blazor congelado — sem novos campos board via EF direto

**Assinaturas**

| Papel | Nome | Data |
|-------|------|------|
| CTO / Arquiteto | | |
| Product Owner | | |