shoc-backend/docs/work-orders/phase-0/audit-event-contract.md

Audit Event Contract — Work Orders

Fase: 0
Status: Aprovado para implementação baseline
Schema EF: WorkOrderAuditLog estendido

---

1. Princípios

• Toda mutação gera audit síncrono desde Fase 0.
• Edição inline (Fase 2) = 1 evento por campo.
• Audit serve investigação operacional, não só compliance.

---

2. Schema por evento

Campo	Tipo	Obrigatório
Id	int	Sim (PK)
WorkOrderId	int	Sim
EventType	enum string	Sim: Manual, System, Sync, Vendor
Action	string	Sim: FieldChanged, StatusChanged, WeekRolled, SyncRejected, AssignmentChanged
FieldName	string	Sim para inline / field change
OldValue	string	Sim
NewValue	string	Sim
UserId / ActorId	string	Sim para Manual
ActorType	enum string	Sim: Dispatcher, Vendor, System, Sync
CreatedAt	DateTime UTC	Sim
CorrelationId	string	Recomendado
DispatchId	int?	Quando evento é no dispatch

Compatibilidade: colunas Action legada mapeada para novo Action; UserId = ActorId para Manual.

---

3. Enums

AuditEventType: Manual | System | Sync | Vendor
AuditActorType: Dispatcher | Vendor | System | Sync
AuditActionType: FieldChanged | StatusChanged | AssignmentChanged | WeekRolled | SyncRejected | Create | Delete

---

4. Mutação → eventos

Mutação	Eventos
ChangeStatus	1× StatusChanged (EventType=Manual)
ChangeAssignment	1× AssignmentChanged (FieldName=AssignTo)
Inline cell (Fase 2)	1× FieldChanged por campo
Auto-schedule (Fase 2)	StatusChanged + FieldChanged se aplicável
Reschedule (Fase 2)	FieldChanged + analytics
WeekRolled (Fase 5)	System WeekRolled + CarriedOver
Sync skip	Sync SyncRejected
Vendor checklist	Vendor FieldChanged + DispatchId

---

5. Contrato FE (Audit tab)

interface AuditEntry {
  type: 'manual' | 'system' | 'sync' | 'vendor';
  dispatcherId?: string;
  action: string;
  fieldName?: string;
  oldValue: string;
  newValue: string;
  time: string; // ISO UTC
  dispatchId?: number;
}

Mapeamento API → FE:

API EventType	FE type
Manual	manual
System	system
Sync	sync
Vendor	vendor

---

6. Baseline Fase 0 (endpoints)

Endpoint	Garantia
POST ChangeStatus	1 audit StatusChanged; Old/New preenchidos
POST ChangeAssignment	1 audit AssignmentChanged; nomes usuário em Old/New

Implementação via IWorkOrderAuditService.

---

7. Critérios de aceite

• Migration estende WorkOrderAuditLog
• ChangeStatus/ChangeAssignment usam serviço central
• Testes assertam 1 evento por mutação

Assinatura Backend Lead: _________________ Data: _______