shoc-backend/docs/roadmap-work-orders-board.md

# Roadmap de Implementação — Work Orders API vs Frontend Board

**Documento:** Relatório consolidado de arquitetura e entrega  
**Fonte da verdade (frontend):** `seahaven.desing/src/pages/WorkOrders.tsx`  
**Backend:** `seaheven.api`  
**Auditoria base:** [auditoria-work-orders-api-vs-frontend.md](auditoria-work-orders-api-vs-frontend.md)  
**Estado atual:** Compatibility Score **24/100** — backend **Not Ready**  
**Nota técnica do programa:** **9.0/10** (meta kickoff enterprise **9.5+**)  
**Escopo:** capacidades de negócio, domínio, governança, fases, riscos e validação — sem design de API, schema ou código

---

## 1. Executive Summary

### 1.1 Readiness geral

O backend é **maduro para CRUD legado, dispatch, vendor portal, checklist/sign-off e audit**, mas foi construído para **listagem paginada administrativa**, não para o **Schedule Board operacional** que o frontend define. A tela principal do board **não pode funcionar** com os contratos atuais.

| Dimensão | Avaliação |
|----------|-----------|
| Tela principal (visão semanal) | ~5% |
| 14 colunas do board | ~15% |
| Edição inline | ~0% |
| Completion doc WO-level | ~0% |
| Background jobs | ~0% |
| Detalhe / slide-over | ~40% |
| **Média ponderada** | **~24%** |

### 1.2 Problemas arquiteturais principais

1. **Paradigma de contrato incompatível** — paginação global vs. janela semanal com seção Unscheduled fixa.
2. **Projeção de listagem insuficiente** — 9 das 14 colunas do board não são alimentadas pela listagem atual.
3. **Ausência de camada de domínio operacional** — campos derivados, tipo de WO e status operacionais ausentes ou não expostos.
4. **Database drift** — `WorkOrderType` existe no SQL legado mas não no EF; possíveis outras colunas desalinhadas.
5. **Modelo de mutação inadequado** — form multipart vs. edição granular por célula.
6. **Sem automação de sistema** — zero infraestrutura de jobs; regras do FE nunca executam no servidor.
7. **Cinco consumidores paralelos** — SHOC, Blazor EF, Vendor Portal, Sync/Lambda, e-mails — sem governança de ownership.
8. **Duas trilhas paralelas** — Blazor acessa EF direto; API REST é integração do SHOC.

### 1.3 Maior risco do programa

**Governança de ownership de dados** — quem pode alterar cada campo entre SHOC, Vendor Portal, Sync, Blazor e Jobs. A arquitetura de domínio resolve fontes da verdade; a governança operacional é o gate final.

### 1.4 Decisões de produto registradas

- **Novas funcionalidades do board** → somente via API REST para o frontend React (SHOC).
- **Blazor (`SeaHavenIndustries`)** → não recebe board, inline edit, jobs, advanced search nem completion doc WO-level; manutenção mínima até sunset do módulo WO.
- **Vendor Portal** → permanece ativo; não-regressão obrigatória.
- **DynamoDB/Sync** → ponte temporária; aposentar após SHOC ingerir direto ([TODO.md](../TODO.md)).

### 1.5 Complexidade e esforço

| Métrica | Valor |
|---------|-------|
| Complexidade geral | **Alta** |
| Esforço total | **XL** (6–9 meses, 2 squads; ou 4–6 meses, 3 squads) |
| Fase 0 — Fundação domínio + governança | L |
| Fase 1 — Board semanal | L |
| Fase 2 — Edição inline + concorrência | L |
| Fase 3 — Criação e cancelamento | M |
| Fase 4 — Busca avançada | M |
| Fase 5 — Domain events (jobs) | M |
| Fase 6 — Completion doc e slide-over | M |
| Fase 7 — Rollout e produção | M |

### 1.6 Gates bloqueantes da Fase 0

Nenhuma implementação de board inicia sem:

1. Domain Architecture Review (DAR) aprovado
2. **Data Ownership Model** assinado
3. **Field Ownership Matrix** assinada
4. **Audit Event Contract** aprovado
5. Volume Discovery Report (sem premissa de volume)
6. Database drift report (SQL vs EF)
7. Spike vendor/dispatch
8. Data migration dry-run
9. RowVersion multi-agregado definido

---

## 2. Capability Gap Assessment

### 2.1 Weekly Scheduling Board — **Critical**
- **Atual:** paginação sem janela temporal, sem Unscheduled.
- **Desejado:** 1 call/semana, Mon–Fri + Unscheduled, contador `X of Y`.

### 2.2 Work Order Lifecycle — **High**
- **Atual:** form parcial, status `Open`, delete físico.
- **Desejado:** wizard/inline completo, `Incomplete`, soft cancel read-only.

### 2.3 Inline Editing — **Critical**
- **Atual:** `EditWorkorder` multipart; endpoints separados.
- **Desejado:** update granular por célula com regras embutidas.

### 2.4 Search & Filtering — **High**
- **Atual:** 5 campos, escopo global, assignee single-select.
- **Desejado:** busca contextual na semana + advanced search cross-week.

### 2.5 Status Management — **Critical**
- **Atual:** enum 5 valores + string livre; sem Past Due.
- **Desejado:** 10 labels + flag Past Due separada; auto-schedule; bloqueios.

### 2.6 Completion Documentation — **High**
- **Atual:** sign-off básico; verify só no dispatch.
- **Desejado:** `docStatus` WO-level (Yes/No/NN); templates por serviço.

### 2.7 Vendor Management (board) — **High**
- **Atual:** vendor só no detalhe via dispatch.
- **Desejado:** colunas VENDOR/APPT na lista; edição via dispatch primário.

### 2.8 Scheduling Intelligence — **Critical**
- **Atual:** `ScheduledDate` no detalhe; sem `targetWeek`, `ScheduledEnd`.
- **Desejado:** agendamento semântico completo; badges ↻ e ↷N.

### 2.9 Audit & Tracking — **Medium**
- **Atual:** audit field-based legado.
- **Desejado:** `{type: manual|system, dispatcherId?, action, time}` + eventos de sistema.

### 2.10 Background Automation — **Critical** (como otimização, não fonte da verdade)
- **Atual:** zero jobs.
- **Desejado:** WeekRolled, cache opcional PastDue; domínio recalcula on-read.

### 2.11 Lookup Data — **High**
- **Atual:** lookups paginados incompatíveis; sem PM types, technicians.
- **Desejado:** dispatchers (initials/color), sites por code, PM types, technicians.

### 2.12 Reporting / Contadores — **Medium**
- **Atual:** `totalCount` global.
- **Desejado:** `X of Y` semanal.

### 2.13 Security — **High**
- **Atual:** `[Authorize]` comentado no `WorkOrderController`.
- **Desejado:** auth ativa; default "My WOs".

---

## 3. Dependency Map

```mermaid
flowchart TD
    subgraph phase0 [Fase0_Fundacao]
        DAR[DAR e 3 artefatos]
        DOM[Agregados dominio]
        VOL[Volume Discovery]
        OWN[Data Ownership]
    end
    subgraph phase1 [Fase1_Board]
        B1[Listagem semanal]
        B2[14 colunas]
    end
    subgraph phase2 [Fase2_Mutacao]
        M1[Inline edit]
        M2[Concorrencia]
    end
    subgraph phase3 [Fase3_Lifecycle]
        L1[Criacao wizard]
        L2[Cancelamento]
    end
    subgraph phase45 [Fase4_5]
        S1[Search]
        E1[Domain events]
    end
    subgraph phase6 [Fase6_Completion]
        C1[DocStatus slideover]
    end
    DAR --> DOM
    DOM --> B1
    OWN --> M1
    VOL --> B1
    B1 --> B2 --> M1
    M1 --> L1
    B2 --> S1
    DOM --> E1
    B2 --> C1
```

**Ordem obrigatória:** Fase 0 → Board → Inline → Lifecycle → Search/Events → Completion → Rollout.

---

## 4. Domain Model

### 4.1 Agregados e limites (anti God Entity)

```mermaid
flowchart TB
    subgraph root [Aggregate Root 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 | Responsabilidade |
|----------|------------------|
| **WorkOrder (core)** | Id, WoNumber, Type, LifecycleStatus, SiteCode, LocationId, DueDate, AssignTo, Title, RowVersion |
| **Scheduling slice** | ScheduledDate, ScheduledStart/End, TargetWeek, ScheduleWeekOnly |
| **Tracking slice** | OriginalWeek, OriginalDate (set-once) |
| **Analytics slice** | RescheduleCount, CarriedOver (contadores históricos) |
| **Completion slice** | DocStatus, refs attachments |
| **Dispatch** | Vendor, tech, status portal — **fonte da verdade vendor** |
| **Audit** | Rastreabilidade imutável |

**Proibido:** `VendorId`, `TechName`, `TechPhone` canônicos na WO.

### 4.2 Scheduling Aggregate Growth Watchlist

Campos que **não** entram em Scheduling sem ARB review: `MoveReason`, `MoveUser`, `MoveCategory`, `MoveSource`. Metadados de movimentação → Audit. Gate: slice Scheduling > 8 campos operacionais → ARB obrigatório.

### 4.3 Campos reaproveitados (sem nova coluna)

`SiteCode`, `ScheduledDate`, `DueDate`, `AssignTo`, `Trade`/`Problem`, `LocationId`, POC via `WorkOrderContacts`.

### 4.4 Database drift conhecido

| Coluna SQL | Ação |
|------------|------|
| `WorkOrderType` | Mapear no Core |
| `AvettaTask` | Inventariar; mapear ou deprecar |
| `AssignDate` | Inventariar; mapear ou deprecar |

Gate Fase 0: diff completo SQL vs `ApplicationDbContextModelSnapshot`.

### 4.5 Entidades relacionadas

| Entidade | Mudança | Fase |
|----------|---------|------|
| `WorkOrderContacts` | `Notes` (pocNotes) | 0 |
| `WorkOrderAuditLog` | EventType Manual/System/Vendor/Sync | 0 |
| `ApplicationUser` | Initials, Color | 0–1 |
| `Locations` | SiteCode | 0–1 |
| `WorkOrderAttachments` | Category | 2–6 |
| `WorkOrderEnums` | LifecycleStatus, WorkOrderType, DocStatus, OperationalFlags | 0 |
| `Dispatch` | Proteção regression | contínuo |

Fora de escopo imediato: `FollowUps`, `Quotes`, `PMSchedules`, `Employee`, `WorkOrderCategories` no board.

---

## 5. Domain Architecture Review (DAR)

### 5.1 Fonte da verdade por conceito

| Conceito | Fonte da verdade | Proibido |
|----------|------------------|----------|
| Status | `LifecycleStatus` (10 valores) | String livre; status composto |
| Past Due | `OperationalFlags.PastDue` | Misturar no enum lifecycle |
| Vendor/Tech | Dispatch primário | Duplicar na WO |
| Schedule | Scheduling slice | Duplicar no core |
| Completion | Completion.DocStatus | Só inferir de dispatch |
| Reschedule/Carried | Analytics + audit | Job blind overwrite |
| WO# | Campo canônico único | Dois números sem regra |
| POC | WorkOrderContacts | Só no detalhe |

### 5.2 Matriz Persistido vs Derivado

| Campo FE | Persistido | Derivado | Fonte / Regra |
|----------|------------|----------|---------------|
| `lifecycleStatus` | Sim | Não | Core |
| `isPastDue` | Não | **Sim** | `ScheduledDate < hoje` AND NOT terminal; job = cache opcional |
| `type` Overdue | Não | **Sim** | Regra type + schedule + status |
| `carriedOver` | Sim | Não | Métrica histórica; incremento via `WeekRolled` |
| `rescheduleCount` | Sim | Parcial | Domain event em mudança de `ScheduledDate` |
| `docStatus` | Sim | Não | Completion slice |
| `dayGroup`, `apptTime` | Não | Sim | Calculados na leitura |
| vendor/tech | Via Dispatch | Projeção | Join dispatch primário |

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

### 5.3 Lifecycle Status vs Operational Flags

```text
LifecycleStatus  → enum único (10 valores FE)
OperationalFlags → PastDue, (futuro: Escalated)
```

Filtro status = LifecycleStatus. Overlay Past Due = flag. Bloqueio de edição = validação sobre flag.

### 5.4 CarriedOver — justificativa

| | `isPastDue` | `carriedOver` |
|--|-------------|---------------|
| Natureza | Estado pontual | **Métrica histórica acumulada** |
| Persistir | Não (derivado) | **Sim** (contador) |
| Por quê | Calculável da data atual | Não recuperável só do schedule atual |

Invariante: incremento **somente** via domain event `WeekRolled`.

### 5.5 Vendor / Dispatch — spike obrigatório (Fase 0)

1. WO mantém `PrimaryDispatchId`
2. Colunas VENDOR = projeção do dispatch primário
3. Edição inline vendor = mutação no Dispatch
4. WO sem dispatch → edição cria dispatch primário

Entregável: ADR "Vendor Source of Truth". Critério: zero `Tech*` canônicos na WO.

### 5.6 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 | Derivado on-read |
| Audit | Síncrono em toda mutação desde Fase 0 |

### 5.7 Database drift investigation

Diff SQL vs EF; classificar: mapear, deprecar, mover para agregado satélite. Tabelas: `workOrders`, `Comments`, `Locations`, `Dispatch`.

---

## 6. Data Ownership Model

### 6.1 Ownership por ator

| Ator | Pode alterar | Não pode alterar |
|------|--------------|------------------|
| **SHOC** | Lifecycle, Schedule, Assignment, Completion, vendor via Dispatch, POC, WO# | Checklist/signoff vendor |
| **Vendor Portal** | Dispatch status, checklist, signoff, comments | Schedule, lifecycle, assignment, DueDate |
| **Sync/Lambda** | Campos ingest (Description, ExternalId, etc.) — só owner Sync | Campos SHOC-owned após 1ª edição manual |
| **Blazor** | Campos legados até sunset | Campos novos board |
| **Jobs** | Incremento CarriedOver; audit system | Lifecycle, Schedule, Dispatch |

### 6.2 Field Ownership Matrix

| Campo | Agregado | Owner escritor | Sync sobrescreve? | Conflito SHOC vs Sync |
|-------|----------|----------------|-------------------|----------------------|
| LifecycleStatus | Core | SHOC | Não após 1ª edição SHOC | SHOC vence |
| AssignTo | Core | SHOC | Não após 1ª edição SHOC | SHOC vence |
| ScheduledDate / janela | Scheduling | SHOC | Não | SHOC vence |
| TargetWeek | Scheduling | SHOC | Não | SHOC vence |
| DueDate | Core | SHOC + Sync | Sim se nunca editado SHOC | SHOC se ManualEditFlag |
| Description | Core | SHOC + Sync | Merge / SHOC priority | SHOC se editado |
| SiteCode / Location | Core | SHOC + Sync | Sim na criação; não após SHOC | SHOC após flag |
| WorkOrderType | Core | SHOC | Sim na criação ingest | SHOC após flag |
| WoNumber | Core | SHOC | Não | SHOC only |
| Vendor / tech | Dispatch | SHOC + Vendor | Não | Domínios separados |
| Checklist/signoff | Dispatch | Vendor | Não | Vendor vence |
| DocStatus | Completion | SHOC | Não | SHOC only |
| RescheduleCount / CarriedOver | Analytics | Domain events | Não | N/A |
| ExternalWorkOrderId | Core | Sync | Sim (idempotente) | Sync only |

**ManualEditFlag:** primeira edição SHOC marca campo; Sync subsequente skip + audit `SyncRejected`.

### 6.3 Sync merge — cenários

| Cenário | Comportamento |
|---------|---------------|
| Sync DueDate + SHOC ScheduledDate | Merge — campos distintos |
| Sync Status + SHOC Status | SHOC vence; sync skip |
| Sync AssignTo + SHOC AssignTo | SHOC vence |
| Sync Description + SHOC Description | SHOC vence se ManualEditFlag |
| Sync cria WO novo | Full ingest |
| Sync atualiza por ExternalWorkOrderId | Field-level merge por matriz |

---

## 7. Concurrency Strategy

### 7.1 Atores

Dispatcher (SHOC), Vendor (Portal), Sync/Lambda, Blazor (congelado), Jobs.

### 7.2 RowVersion multi-agregado

| Agregado | RowVersion | Quando muda |
|----------|------------|-------------|
| **WorkOrder (root)** | No Core | Mutação Core, Scheduling, Completion, Analytics na mesma transação |
| **Dispatch** | Próprio | Mutação vendor/tech/checklist/status dispatch |
| **Projeção board** | N/A | FE envia `workOrderVersion` + `dispatchVersion` |

**Propagação:**
- SHOC edita ScheduledDate → bump WO.RowVersion
- SHOC edita vendor → bump Dispatch.RowVersion
- Vendor edita checklist → bump Dispatch.RowVersion only
- Sync altera Description → bump WO se merge aplicado
- DocStatus → bump WO (Completion na mesma transação)

Conflito → 409 com `currentState` para refresh.

### 7.3 Concurrency Ownership Rules

| Cenário | Resultado |
|---------|-----------|
| SHOC vs SHOC (mesmo campo) | 409; último RowVersion válido |
| SHOC vs Sync (mesmo campo) | Vence owner do campo |
| SHOC vs Sync (campos diferentes) | Merge |
| Vendor vs Sync | Domínios separados |
| SHOC vs Vendor | Merge se campos distintos; impossível mesmo conceito por design |
| Job WeekRolled vs SHOC reschedule | Idempotência WO+semana |
| Blazor vs SHOC | SHOC vence; Blazor congelado |

### 7.4 Testes

Fase 2: conflito paralelo (2 dispatchers, sync durante edição); dual RowVersion; audit count = fields changed.

---

## 8. Audit Event Contract

### 8.1 Princípios

- Toda mutação gera audit **síncrono** desde Fase 0
- Edição inline = **1 evento por campo**
- Audit para investigação operacional, não só compliance

### 8.2 Schema por evento

| Campo | Obrigatório |
|-------|-------------|
| WorkOrderId | Sim |
| EventType | Sim: Manual / System / Sync / Vendor |
| Action | Sim: FieldChanged, StatusChanged, WeekRolled, SyncRejected |
| FieldName | Sim para inline |
| OldValue, NewValue | Sim |
| ActorId, ActorType | Sim para Manual |
| Timestamp | Sim UTC |
| CorrelationId | Recomendado |
| DispatchId | Quando evento é no dispatch |

### 8.3 Mutação → eventos

| Mutação | Eventos |
|---------|---------|
| ChangeStatus | 1× StatusChanged |
| Inline cell | 1× FieldChanged por campo |
| Auto-schedule | StatusChanged + FieldChanged se aplicável |
| Reschedule | FieldChanged + RescheduleCount + audit analytics |
| WeekRolled | System WeekRolled + CarriedOver old/new |
| Sync skip | Sync SyncRejected |
| Vendor checklist | Vendor FieldChanged no Dispatch |

### 8.4 Contrato FE (Audit tab)

`{ type, dispatcherId?, action, fieldName?, oldValue, newValue, time }`

---

## 9. Data Migration Plan

### 9.1 Status

| Legado | LifecycleStatus alvo |
|--------|------------------------|
| Open | Incomplete |
| InProgress | In Progress |
| Completed | Complete |
| Cancelled | Canceled |
| OnHold | On Hold |
| Desconhecido | Incomplete + NeedsReview |

Processo: dry-run staging; 100% classificados; `LegacyStatus` read-only 1 release; rollback documentado.

### 9.2 WO#

| Formato legado | Estratégia |
|----------------|------------|
| Sequencial sync `10000001` | Normalizar 11 dígitos |
| `WO-{date}-{random}` | Coexistência; novos só 11 dígitos |
| Duplicatas | Resolução manual pré-go-live |

### 9.3 WorkOrderType

Mapear SQL existente → enum; NULL → default PO; Overdue = derivado.

### 9.4 Rollback

Migrations reversíveis; feature flag SHOC; snapshot pré-migration.

---

## 10. Volume Discovery e Search Scalability

### 10.1 Volume Discovery (Fase 0 — gate Fase 1)

**Sem premissa de volume.** Métricas obrigatórias:

| Métrica | Gate |
|---------|------|
| Total WOs produção/staging | Obrigatório |
| WOs/semana (p95) | Obrigatório |
| WOs Unscheduled | Obrigatório |
| Crescimento mensal | Desejável |

### 10.2 Tiers e impacto

| Tier | Total WOs | Listagem semanal | Advanced search |
|------|-----------|------------------|-----------------|
| **S** | < 25k | Índices simples | SQL filtros compostos |
| **M** | 25k–250k | Índices covering | Paginação obrigatória |
| **L** | 250k–1M | Read model candidato | Full-text |
| **XL** | > 1M | Materialized view | Search dedicado (ARB) |

Fases 1–3: índices conservadores compatíveis com qualquer tier. Fase 4: implementação conforme tier + load test.

---

## 11. Coexistência Multi-Consumidor

### 11.1 Inventário

| Consumidor | Conexão | Status |
|------------|---------|--------|
| **SHOC React** (`seahaven.desing`) | REST JWT | Em desenvolvimento — **único alvo novas features** |
| **Blazor** (`SeaHavenIndustries`) | EF direto, não REST | Ativo — manutenção mínima; sunset WO |
| **Vendor Portal UI** | REST `X-Vendor-Token` | API ativa; UI externa |
| **SyncController + Lambda** | DynamoDB → SQL | Ponte temporária |
| **E-mails SendGrid** | Deep links SHOC/Portal | Ativo |
| **Mobile** | — | Sem evidência — confirmar com PO |

```mermaid
flowchart TB
    SHOC[SHOC React] -->|REST JWT| API[Api REST]
    VPortal[Vendor Portal] -->|X-Vendor-Token| API
    Lambda[Lambda ingest] --> DynamoDB[(DynamoDB)]
    DynamoDB --> Sync[SyncController]
    Sync --> DB[(SQL Server)]
    API --> DB
    Blazor[Blazor EF] -->|legado| DB
```

**Nota:** DynamoDB é **ingestão externa**, não banco operacional. SQL Server é fonte para board, Blazor e Portal.

### 11.2 Matriz de coexistência

| Consumidor | Novas features board | Schema | Sunset |
|------------|---------------------|--------|--------|
| SHOC | Recebe tudo | Consome novos campos | Destino final |
| Blazor | Não recebe | Colunas nullable; backward compatible | Módulo WO congela |
| Vendor Portal | Não usa board | Dispatch intacto | Mantém |
| Sync/Lambda | Indireto | Defaults para novos campos | Após cutover API |
| E-mails | Links SHOC | FrontendBaseUrl prod | Atualizar templates |

### 11.3 Trilhas de entrega

- **Trilha A SHOC:** fases 0–7; feature flags; piloto dispatchers
- **Trilha B Blazor:** smoke EF pós-migration; sem board; bugfix crítico only
- **Trilha C Vendor Portal:** regression suite cada release que toca WO/Dispatch
- **Trilha D Lambda:** manter até SHOC produção; cutover Fase 7; critério: criação WO + auth serviço estáveis

### 11.4 Endpoints legado vs board

- Legado (`GetWorkOrderList`, etc.): manter durante coexistência; congelar contrato
- Board: novos contratos; não estender legado com hacks
- Deprecação: após 100% dispatchers SHOC + sunset Blazor WO

### 11.5 Ordem de rollout

1. Fase 0 staging — gates + migrations
2. Gate Blazor smoke EF
3. Fase 1 staging — SHOC board feature flag
4. Gate Vendor Portal regression
5. Fases 2–6 incrementais
6. Piloto 1–2 dispatchers
7. Rollout gradual
8. Sunset Blazor WO
9. Cutover Lambda → API
10. Deprecação legado + SyncController

### 11.6 Monitoramento coexistência

Métricas por consumidor; drift DynamoDB vs SQL; adoção SHOC vs Blazor; alertas job failure.

### 11.7 Checklist pré-go-live PO

- App mobile externo?
- Data sunset Blazor WO
- FrontendBaseUrl produção → SHOC
- Owner Lambda cutover

---

## 12. Implementation Phases

### Fase 0 — Domain Foundation + Governança

**Objetivo:** Kickoff enterprise — domínio, ownership, volume, audit antes de board.

**Escopo:** DAR; 3 artefatos (Ownership, Field Matrix, Audit Contract); Volume Discovery; drift SQL/EF; spike vendor; agregados Core+Scheduling+Tracking+Analytics+Completion; enums; RowVersion root+Dispatch; migration dry-run; ManualEditFlag design; audit baseline ChangeStatus/ChangeAssignment; smoke Blazor/Sync/Portal.

**Não inicia:** Board API, inline edit, jobs.

**Validação:** 9 gates assinados; audit granularidade testada; tier volume definido.

---

### Fase 1 — Weekly Board (leitura)

**Objetivo:** Tela principal carrega semana operacional.

**Escopo:** Listagem window-based; Unscheduled; 14 colunas como projeção; `X of Y`; filtros (dispatcher multi, `__unassigned__`, My WOs, tipo, semana); `isPastDue` derivado on-read; vendor via dispatch primário; índices conforme tier volume.

**Validação:** 1 call = semana + Unscheduled; 12/14 colunas mínimo; gate Vendor Portal regression.

---

### Fase 2 — Inline Edit + Concorrência

**Objetivo:** Edição spreadsheet com regras e conflitos tratados.

**Escopo:** Update granular; dual RowVersion; audit 1 evento/campo; auto-schedule; rescheduleCount++; bloqueio PastDue flag; cancel read-only; WO# 11 dígitos; testes concorrência.

---

### Fase 3 — Criação e Cancelamento

**Escopo:** Wizard/inline completo; Incomplete inicial; targetWeek; soft cancel; ManualEditFlag na criação; delete admin documentado.

---

### Fase 4 — Search

**Escopo:** Busca contextual semana; advanced search cross-week conforme tier; load test; sem implementar advanced sem tier definido.

---

### Fase 5 — Scheduled Domain Events

**Escopo:** WeekRolled → CarriedOver++; cache opcional PastDue; idempotência; monitoramento falha; on-read sempre correto.

---

### Fase 6 — Completion Doc e Slide-over

**Escopo:** docStatus WO-level; templates por serviço; Comments/Audit/Media alinhados ao FE.

---

### Fase 7 — Rollout e Produção

**Escopo:** Piloto; rollout gradual; sunset Blazor WO; cutover Lambda; deprecação legado; UAT; zero P1 duas semanas; dashboards saúde.

---

## 13. Critical Path Analysis

### Must Have
1. Listagem window-based + Unscheduled
2. Projeção 14 colunas
3. Agregados domínio + enums
4. Update granular por campo
5. Status 10 labels + flag PastDue
6. Lookups
7. Criação wizard
8. WO# 11 dígitos
9. DAR + 3 artefatos Fase 0

### Should Have
10. Domain events CarriedOver
11. Advanced search
12. Regras mutação completas
13. Soft cancel enforcement
14. docStatus WO-level
15. Auth ativa

### Nice to Have
16. Reorder intra-dia persistido (FE local)
17. Flags pessoais session-only
18. Paginação 12/24/48/96
19. Bulk select

---

## 14. Frontend Impact Assessment

| Gap | UX | Severidade | Workaround |
|-----|-----|------------|------------|
| Sem listagem semanal | Tela inutilizável | Critical | Mock FE |
| 14 colunas incompletas | Board ilegível | Critical | Nenhum em prod |
| Sem inline edit | Core inoperante | Critical | Modal legado |
| Sem advanced search | WOs históricos invisíveis | High | Busca por ID |
| Status incompatíveis | Decisões erradas | Critical | Hardcode FE |
| Sem jobs (derivados) | Badges stale se só client | High | On-read BE resolve PastDue |
| Sem docStatus | COMP DOC vazia | High | Ocultar coluna |
| WO# formato errado | Criação bloqueada | Critical | — |
| Ownership Sync vs SHOC | Overwrite silencioso | Critical | Field Matrix Fase 0 |
| Auth desabilitada | Risco segurança | High | API gateway |

---

## 15. Business Rules Assessment

| Regra | Status | Impacto |
|-------|--------|---------|
| Auto-schedule Incomplete→Scheduled | Unsupported | Status incorreto |
| Reschedule → rescheduleCount++ | Unsupported | Badge ↻ ausente |
| Reschedule limpa PastDue (derivado) | Unsupported | Flag stale até re-read |
| Status bloqueado se PastDue | Unsupported | Bypass via API |
| WO# único 11 dígitos | Unsupported | Duplicatas |
| Cancel read-only | Partial | Edição pós-cancel |
| WeekRolled → carriedOver | Unsupported | Badge ↷N ausente |
| Completion doc por serviço | Unsupported | Workflow manual |
| Week-only scheduling | Unsupported | Wizard incompleto |

---

## 16. Data Contract Readiness

| Área | Readiness % | Gap principal |
|------|-------------|---------------|
| List Views board | 5% | 14 colunas, schedule, vendor, flags |
| Detail slide-over | 40% | Derivados, docStatus, schema |
| Search | 10% | Cross-week, date ranges |
| Lookups | 20% | initials, site code, PM, tech |
| Scheduling | 25% | targetWeek, ScheduledEnd |
| Status | 30% | 10 labels + flag |
| Completion | 0% | docStatus, templates |
| Comments | 60% | Schema |
| Audit | 50% | type system, granularidade |
| Media | 45% | category |

**Média ponderada: ~28%**

---

## 17. Testing Strategy

### Functional
Board semanal, 14 colunas, filtros, inline por campo, regras negócio, criação/cancelamento, docStatus, status+flag, ownership rejection sync.

### Integration
SHOC E2E por fase; Vendor Portal regression; Sync; auth; dual RowVersion.

### Regression
Endpoints legados; Blazor smoke EF; Portal checklist/signoff.

### UAT
Roteiros dispatchers reais; sign-off PO por fase.

### Data validation
WO# migration; status mapping; derivados on-read vs contadores; referencial.

### Migration validation
Dump produção espelho; antes/depois contagens; rollback por fase.

### Fase-specific
- **0:** volume queries; audit granularidade; sync skip
- **2:** concurrency suite; 409 handling
- **4:** load test tier
- **5:** job failure injection; on-read correctness

---

## 18. Risk Matrix

| Risco | Prob. | Impacto | Mitigação |
|-------|-------|---------|-----------|
| Board inoperante em prod | Alta | Crítico | Fase 1 gate; E2E |
| Ownership ambíguo Sync vs SHOC | Alta | Crítico | Field Ownership Matrix |
| God Entity creep | Média | Alto | Growth Watchlist; ARB |
| Conflito cross-agregado | Média | Alto | RowVersion root + Dispatch |
| Job falha estado errado | Alta | Alto | Derivados on-read |
| Vendor drift Dispatch vs WO | Alta | Crítico | Spike; projeção only |
| Status migration incorreta | Média | Crítico | LegacyStatus; dry-run |
| Volume desconhecido → índices errados | Alta | Alto | Volume Discovery Fase 0 |
| Audit inútil investigação | Média | Médio | Event Contract |
| Regressão Vendor Portal | Média | Crítico | Suite dedicada |
| Blazor vs SHOC divergência | Alta | Alto | Congelar Blazor WO |
| Auth bloqueia integrações | Média | Alto | Inventário consumidores |
| CarriedOver recalculado errado | Baixa | Médio | Só via WeekRolled |
| Scheduling aggregate creep | Média | Alto | Watchlist §4.2 |

---

## 19. Prioritized Backlog

Ordenado por sequência de implementação.

| # | Item | P | Fase | Dep | Complex. | Risco |
|---|------|---|------|-----|----------|-------|
| 1 | DAR completo + sign-off CTO | P0 | 0 | — | M | Alto |
| 2 | Data Ownership Model | P0 | 0 | — | S | Alto |
| 3 | Field Ownership Matrix + ManualEditFlag | P0 | 0 | 2 | M | Alto |
| 4 | Audit Event Contract + baseline | P0 | 0 | — | M | Médio |
| 5 | Volume Discovery Report | P0 | 0 | — | S | Alto |
| 6 | Database drift SQL vs EF | P0 | 0 | — | M | Médio |
| 7 | Spike vendor/dispatch source of truth | P0 | 0 | — | M | Alto |
| 8 | Agregados domínio (anti God Entity) | P0 | 0 | 1 | L | Alto |
| 9 | Matriz Persistido vs Derivado | P0 | 0 | 1 | S | Médio |
| 10 | RowVersion root + Dispatch | P0 | 0 | 8 | M | Alto |
| 11 | Enums Lifecycle + Flags + WorkOrderType | P0 | 0 | 8 | M | Médio |
| 12 | Data migration dry-run | P0 | 0 | 8 | M | Alto |
| 13 | Inventário consumidores + coexistência | P0 | 0 | — | S | Médio |
| 14 | Smoke Blazor EF + Sync + Portal | P0 | 0 | 8 | M | Alto |
| 15 | Normalização WO# 11 dígitos | P0 | 0 | 12 | M | Alto |
| 16 | Reativar auth endpoints WO | P0 | 0 | — | S | Médio |
| 17 | Lookups (dispatchers, sites, PM, tech) | P0 | 0–1 | — | M | Baixo |
| 18 | Listagem window-based + Unscheduled | P0 | 1 | 8,11,17 | L | Alto |
| 19 | Projeção 14 colunas | P0 | 1 | 18 | L | Alto |
| 20 | isPastDue derivado on-read | P0 | 1 | 19 | S | Baixo |
| 21 | Vendor via dispatch primário | P0 | 1 | 7,19 | M | Alto |
| 22 | Filtros principais + My WOs | P0 | 1 | 18 | M | Médio |
| 23 | Contador X of Y | P1 | 1 | 18 | S | Baixo |
| 24 | Sync merge por field ownership | P0 | 0–1 | 3 | M | Alto |
| 25 | Update granular inline | P0 | 2 | 19 | L | Alto |
| 26 | Audit 1 evento por campo | P0 | 2 | 4,25 | M | Médio |
| 27 | Concurrency integration tests | P0 | 2 | 10,25 | M | Alto |
| 28 | Auto-schedule Incomplete→Scheduled | P0 | 2 | 25 | M | Médio |
| 29 | RescheduleCount++ domain event | P0 | 2 | 25 | S | Baixo |
| 30 | Bloqueio status se PastDue flag | P0 | 2 | 25 | S | Baixo |
| 31 | Cancel read-only enforcement | P1 | 2 | 25 | S | Baixo |
| 32 | Criação wizard/inline completa | P0 | 3 | 25 | M | Médio |
| 33 | Week-only scheduling targetWeek | P1 | 3 | 32 | M | Médio |
| 34 | Soft cancel dedicado | P1 | 3 | 31 | S | Baixo |
| 35 | Busca contextual semana | P1 | 4 | 19 | M | Baixo |
| 36 | Advanced search cross-week | P1 | 4 | 5,19 | L | Médio |
| 37 | Load test search por tier | P0 | 4 | 5 | M | Alto |
| 38 | WeekRolled domain event + CarriedOver | P1 | 5 | 8 | M | Médio |
| 39 | Cache opcional PastDue | P2 | 5 | 20 | S | Baixo |
| 40 | docStatus WO-level | P1 | 6 | 8 | M | Médio |
| 41 | Completion templates por serviço | P2 | 6 | 40 | L | Médio |
| 42 | Slide-over Comments/Audit/Media | P2 | 6 | 4,40 | M | Baixo |
| 43 | Regression suite legado + Portal | P0 | cont. | — | M | Alto |
| 44 | UAT dispatchers por fase | P0 | cont. | — | S | Médio |
| 45 | Piloto + rollout gradual SHOC | P0 | 7 | 1–42 | M | Alto |
| 46 | Sunset Blazor WO | P1 | 7 | 45 | S | Médio |
| 47 | Cutover Lambda → API | P1 | 7 | 32 | M | Alto |
| 48 | Deprecação endpoints legado + Sync | P2 | 7 | 45 | M | Médio |
| 49 | Monitoramento coexistência | P1 | 7 | 45 | S | Baixo |

---

## 20. Cronograma indicativo

```mermaid
gantt
    title Work Orders Board
    dateFormat YYYY-MM-DD
    section Fundacao
    DAR_arteFatos_dominio     :2026-07-01, 8w
    section Board
    Listagem_14colunas        :2026-09-01, 8w
    section Mutacao
    Inline_concorrencia       :2026-11-01, 8w
    Criacao_cancelamento      :2026-11-15, 6w
    section Inteligencia
    Search                    :2027-01-01, 6w
    Domain_events             :2027-01-15, 4w
    section Completion
    DocStatus_slideover       :2027-02-15, 6w
    section Producao
    Piloto_rollout            :2027-04-01, 8w
```

---

## 21. Stakeholders

| Papel | Responsabilidade |
|-------|------------------|
| CEO / Sponsor | Investimento XL; prioridade SHOC sobre Blazor |
| Product Owner | Aceite por fase; semana operacional; regras ambíguas |
| CTO / Arquiteto | DAR; 3 artefatos; ownership; cutover Lambda |
| Backend | Fases 0–6 domínio e contratos |
| Frontend SHOC | Integração; feature flags; remover mocks |
| QA | Testes §17; UAT; concurrency |
| Documentação | Contratos; guia consumidores legados |
| Operações | Jobs; alertas; monitoramento coexistência |

---

## 22. Critérios de prontidão para kickoff (9.5+)

| Área | Critério |
|------|----------|
| Domain Design | DAR aprovado; agregados; Watchlist |
| Source of Truth | Field Ownership Matrix assinada |
| Data Governance | Data Ownership Model completo |
| Concurrency | RowVersion root + Dispatch; testes Fase 2 |
| Sync | Cenários explícitos; ManualEditFlag |
| Audit | Event Contract; 1 evento/campo inline |
| Migration | Dry-run; LegacyStatus rollback |
| Volume | Discovery Fase 0; tier definido |
| Jobs | Domain events; on-read correto se job falha |
| Coexistência | Inventário; trilhas; smoke Blazor/Portal/Sync |

---

## 23. Conclusão

Programa **viável e de grande porte (XL)**. O caminho crítico é:

```text
Resolver domínio e governança (Fase 0)
  → Board semanal (Fase 1)
    → Inline edit + concorrência (Fase 2)
      → Paridade funcional progressiva (Fases 3–6)
        → Rollout seguro (Fase 7)
```

O documento integra: gap assessment da auditoria, modelo de domínio com agregados, governança de ownership, concorrência multi-agregado, migração de dados, coexistência SHOC/Blazor/Portal/Lambda, e backlog executável — pronto para Architecture Review Board e kickoff de implementação enterprise.

**Próximo passo imediato:** executar Fase 0 — produzir e assinar os três artefatos (Data Ownership Model, Field Ownership Matrix, Audit Event Contract) antes de qualquer migration de schema.