adam/shoc-backend
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-backend.git synced 2026-09-30 08:23:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
shoc-backend/docs/roadmap-work-orders-board.md

34 KiB
Raw Blame History

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
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).

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

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)

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

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 
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

  1. Domain events CarriedOver
  2. Advanced search
  3. Regras mutação completas
  4. Soft cancel enforcement
  5. docStatus WO-level
  6. Auth ativa

Nice to Have

  1. Reorder intra-dia persistido (FE local)
  2. Flags pessoais session-only
  3. Paginação 12/24/48/96
  4. 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

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 é:

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.