mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-10-02 16:43:20 +00:00
139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
# 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 | | |
|