shoc-backend/docs/work-orders/phase-3/README.md

Fase 3 — Criação e Cancelamento

Programa: Work Orders Board
Objetivo: Criação wizard/inline via contrato do board SHOC, cancelamento soft dedicado, ManualEditFlag na criação, e delete físico restrito a Admin.

Depende de: Fase 0, Fase 1, Fase 2

---

Endpoints

POST /api/workorders/board

Cria uma WO com contrato alinhado ao board. Suporta wizard (payload completo) e inline row (subset mínimo).

Autenticação: Bearer JWT ([Authorize])

Request body:

{
  "woNumber": "12345",
  "workOrderType": "PM",
  "siteCode": "BK5",
  "assignTo": "dispatcher-guid",
  "dueDate": "2026-07-01",
  "scheduledDate": "2026-06-25",
  "targetWeek": "2026-06-22",
  "scheduleWeekOnly": false,
  "vendorId": 5,
  "apptDate": "2026-06-26",
  "apptTime": "09:00 – 11:00",
  "docStatus": "No",
  "description": "Leak in break room",
  "trade": "HVAC PM",
  "locationId": 12,
  "pocContactId": 3,
  "pocNotes": "Call before arrival"
}

Campo	Obrigatório	Descrição
workOrderType	Sim	Enum WorkOrderType
siteCode	Sim	Código do site
woNumber	Não	Se omitido, auto-gera sequencial normalizado 11 dígitos
scheduleWeekOnly	Não	Se true, targetWeek é obrigatório
vendorId	Condicional	Obrigatório quando apptDate ou apptTime informados

Responses:

HTTP	Body	Quando
200	WorkOrderBoardRowDto	Sucesso — row pronto para inserir no board
400	Response	Validação FluentValidation
409	WorkOrderBoardValidationErrorDto	WO# duplicado
422	WorkOrderBoardValidationErrorDto	Regra de domínio

Exemplo (inline mínimo):

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"workOrderType":"PM","siteCode":"BK5"}' \
  "https://localhost:5001/api/workorders/board"

---

POST /api/workorders/{id}/cancel

Soft cancel — transição para LifecycleStatus.Canceled com WO read-only.

Autenticação: Bearer JWT

Responses:

HTTP	Body	Quando
200	WorkOrderBoardRowDto	Cancelado (ou já estava cancelado — idempotente)
422	WorkOrderBoardValidationErrorDto	WO Complete ou Closed

Exemplo:

curl -X POST -H "Authorization: Bearer <token>" \
  "https://localhost:5001/api/workorders/42/cancel"

---

Regras de domínio na criação

Regra	Comportamento
Status inicial	Incomplete
Auto-schedule	scheduledDate + assignTo → Scheduled
Set-once tracking	Primeira scheduledDate → OriginalDate / OriginalWeek
Week-only	scheduleWeekOnly=true + targetWeek → aparece na semana no GET board
WO#	Manual normalizado 11 dígitos; auto-gerado se omitido
Vendor	Cria dispatch primário quando vendorId informado
ManualEditFlag	Field locks criados para cada campo SHOC preenchido

---

Soft cancel vs hard delete

Operação	Endpoint	Quem	Efeito
Soft cancel	POST /{id}/cancel	Dispatcher	Status Canceled, WO permanece, PATCH bloqueado (422)
Hard delete	DELETE DeleteWorkorder	Admin only	Remove registro, anexos e contatos

O legado POST AddWorkorder (form/Blazor) permanece inalterado.

---

ManualEditFlag na criação

Campos preenchidos na criação SHOC recebem lock em WorkOrderFieldLocks via audit FieldChanged. Sync subsequente em campo lockado gera SyncRejected (ver manual-edit-flag-design.md).

WO criada via Sync/Lambda continua sem locks até edição SHOC.

---

Audit

Evento	Action
Criação	1× Create + FieldChanged por campo preenchido
Auto-schedule na criação	StatusChanged adicional
Cancel	StatusChanged → Canceled
Hard delete Admin	Delete

---

Código entregue

Camada	Arquivo
DTOs	SeaHaven.Services/DTOs/WorkOrderBoardDTOs.cs
Validação	SeaHaven.Services/Validation/WorkOrderBoardCreateValidation.cs
Scheduling compartilhado	SeaHaven.Services/Helpers/WorkOrderBoardFieldMutations.cs
Create service	SeaHaven.Services/Implementation/WorkOrderBoardCreateService.cs
Cancel service	SeaHaven.Services/Implementation/WorkOrderBoardCancelService.cs
Audit	IWorkOrderAuditService.StageCreated, LogCreatedAsync
API	WorkOrderController — POST board, POST {id}/cancel, DELETE Admin
Testes	WorkOrderBoardCreateServiceTests, WorkOrderBoardCancelServiceTests, WorkOrderBoardCreateSyncLockTests

---

Gates de aceite

Desenvolvimento

• POST /api/workorders/board — Incomplete / auto-schedule / week-only
• WO# auto ou manual 11 dígitos + unicidade (409)
• Vendor/dispatch primário na criação
• Field locks + SyncRejected pós-create SHOC
• POST /{id}/cancel idempotente; PATCH bloqueado após cancel
• DELETE DeleteWorkorder restrito a Admin
• Legado AddWorkorder inalterado
• 68 testes unitários total (17 Fase 3 + 51 Fases 0–2)

Staging (pendente)

• UAT dispatcher: wizard + inline row
• Smoke Sync durante criação SHOC
• Confirmar navegação FE para semana do WO criado

---

Próximo passo

Fase 4 — Busca contextual na semana + advanced search cross-week conforme tier volume.