From ec6d69a9336f4282298c942ed5ae4e53c0372be8 Mon Sep 17 00:00:00 2001 From: Arthur Bassi Date: Mon, 13 Jul 2026 13:23:52 -0300 Subject: [PATCH] docs(work-orders): add Phase 7 rollout gates Lambda mapping and CloudWatch alerts --- TODO.md | 8 ++++ docs/work-orders/phase-7/cloudwatch-alerts.md | 32 +++++++++----- .../phase-7/lambda-ingest-discovery.md | 2 + .../phase-7/phase-7-gates-signoff.md | 43 +++++++++++++++---- 4 files changed, 66 insertions(+), 19 deletions(-) diff --git a/TODO.md b/TODO.md index 68fc21b..19fa447 100644 --- a/TODO.md +++ b/TODO.md @@ -50,3 +50,11 @@ - [ ] When SHOC deploys, switch workorder-ingest Lambda from DynamoDB to direct SHOC API calls - [ ] Retire DynamoDB sync bridge - [ ] GitHub branch protection — requires paid plan for private repos + +### Work Orders Board — Phase 7 ops (after engineering on `feat/work-orders-phase-7`) +- [ ] Staging: dry-run migrations Phase0–Phase6 + smoke multi-consumidor +- [ ] Staging: E2E SHOC (board + slide-over + completion-doc) +- [ ] Create CloudWatch alerts from `docs/work-orders/phase-7/cloudwatch-alerts.md` +- [ ] Name Lambda cutover owner; dual-run then `Sync:Enabled=false` +- [ ] Piloto 1–2 dispatchers → UAT → 100% rollout; Blazor sunset date +- [ ] Sign GO/DONE in `docs/work-orders/phase-7/phase-7-gates-signoff.md` diff --git a/docs/work-orders/phase-7/cloudwatch-alerts.md b/docs/work-orders/phase-7/cloudwatch-alerts.md index d83e929..07605d6 100644 --- a/docs/work-orders/phase-7/cloudwatch-alerts.md +++ b/docs/work-orders/phase-7/cloudwatch-alerts.md @@ -19,14 +19,28 @@ ## Alertas recomendados (Elastic Beanstalk / CloudWatch) -| Alerta | Condição | Severidade | -|--------|----------|------------| -| WeekRolled stale | `lastWeekRolledRunUtc` > 8 dias | P1 | -| WeekRolled job error | `lastWeekRolledError` não nulo | P1 | -| SyncRejected spike | `syncRejectedLast24h` > 50 | P2 | -| API 5xx board | ALB/Beanstalk 5xx rate > 1% em `/api/workorders/board` | P1 | -| Ingest auth failures | 401 em `/api/workorders/ingest` > 10/h | P2 | -| Sync disabled em prod sem cutover | `syncEnabled=false` e ingest não validado | P2 | +| Alerta | Condição | Severidade | Status ops | +|--------|----------|------------|------------| +| WeekRolled stale | `lastWeekRolledRunUtc` > 8 dias | P1 | [ ] criar | +| WeekRolled job error | `lastWeekRolledError` não nulo | P1 | [ ] criar | +| SyncRejected spike | `syncRejectedLast24h` > 50 | P2 | [ ] criar | +| API 5xx board | ALB/Beanstalk 5xx rate > 1% em `/api/workorders/board` | P1 | [ ] criar | +| Ingest auth failures | 401 em `/api/workorders/ingest` > 10/h | P2 | [ ] criar | +| Sync disabled em prod sem cutover | `syncEnabled=false` e ingest não validado | P2 | [ ] criar | + +--- + +## Runbook de criação (ops) + +1. Deploy API com `WorkOrderIngest` + `Sync` + jobs habilitados conforme ambiente. +2. Obter token Admin e validar: + ```powershell + curl -H "Authorization: Bearer " https:///api/workorders/ops/health + ``` +3. Criar EventBridge/cron (ex.: a cada 15 min) que chama o health endpoint **ou** publica métricas customizadas a partir do JSON. +4. Criar os alarmes da tabela acima no CloudWatch (ALB 5xx + métricas derivadas do health). +5. Agendar checagem diária manual durante piloto e rollout. +6. Marcar status ops na tabela quando cada alarme estiver ativo em staging e prod. --- @@ -36,5 +50,3 @@ # Com token Admin curl -H "Authorization: Bearer " https:///api/workorders/ops/health ``` - -Agendar checagem diária durante piloto e rollout. diff --git a/docs/work-orders/phase-7/lambda-ingest-discovery.md b/docs/work-orders/phase-7/lambda-ingest-discovery.md index b07d789..61765c8 100644 --- a/docs/work-orders/phase-7/lambda-ingest-discovery.md +++ b/docs/work-orders/phase-7/lambda-ingest-discovery.md @@ -91,3 +91,5 @@ Lambda deve enviar o header em cada `POST /api/workorders/ingest`. Não usar JWT - [ ] Auth ingest testada em staging - [ ] Zero drift em amostra de 100 WOs - [ ] Owner Lambda assinou runbook +- [ ] Dual-run validado (ops) +- [ ] `Sync:Enabled=false` em prod (ops) diff --git a/docs/work-orders/phase-7/phase-7-gates-signoff.md b/docs/work-orders/phase-7/phase-7-gates-signoff.md index 16021e0..4bb68bd 100644 --- a/docs/work-orders/phase-7/phase-7-gates-signoff.md +++ b/docs/work-orders/phase-7/phase-7-gates-signoff.md @@ -5,6 +5,31 @@ --- +## Engineering readiness (código — branch `feat/work-orders-phase-7`) + +Itens de engenharia entregues no repositório. Não substituem gates de staging/ops abaixo. + +| # | Item | Evidência | Status | +|---|------|-----------|--------| +| E1 | `GET /api/workorders/ops/health` | `WorkOrderOpsController` + `WorkOrderOpsHealthService` | [x] | +| E2 | `POST /api/workorders/ingest` + `X-Ingest-Key` | `WorkOrderIngestController` + `IngestApiKeyFilter` | [x] | +| E3 | `Sync:Enabled` → 503 no SyncController | `SyncOptions` + checks em WorkOrders/Comments/VendorReplies/All | [x] | +| E4 | Legacy deprecation middleware | `LegacyDeprecationMiddleware` + `LegacyEndpoints` config | [x] | +| E5 | Blazor sunset guard | `BlazorWorkOrderSunsetOptions` + guard em `WorkorderService` | [x] | +| E6 | Alertas documentados | [cloudwatch-alerts.md](cloudwatch-alerts.md) | [x] | +| E7 | Lambda mapping documentado | [lambda-ingest-discovery.md](lambda-ingest-discovery.md) | [x] | +| E8 | Testes coexistência | `dotnet test --filter FullyQualifiedName~WorkOrderPhase7` | [x] | +| E9 | Fase 6 slide-over API | `GET detail/audit/comments/media`, completion-doc, templates | [x] | + +**Config flags (default seguro em prod):** + +- `WorkOrderIngest:Enabled=true` (requer `ApiKey`) +- `Sync:Enabled=true` até cutover +- `LegacyEndpoints:DeprecationEnabled=false` até anúncio +- `BlazorWorkOrderSunset:Enabled=false` até data PO + +--- + ## Gate de entrada (GO Fase 7) Bloqueia piloto em produção até todos os itens estarem verdes. @@ -37,15 +62,15 @@ Bloqueia piloto em produção até todos os itens estarem verdes. ## Gates de saída (DONE Fase 7) -| Gate | Critério | -|------|----------| -| Piloto | 1–2 dispatchers SHOC em prod; UAT assinado | -| Rollout | 100% dispatchers no board SHOC | -| Estabilidade | Zero P1 por 2 semanas consecutivas | -| Blazor | Módulo WO sunset (`BlazorWorkOrderSunset:Enabled`) | -| Lambda | Ingest direto `POST /api/workorders/ingest`; Dynamo/Sync desligados | -| Monitoramento | `GET /api/workorders/ops/health` + alertas documentados | -| Legado | Headers `Sunset`/`Deprecation` nos endpoints legado | +| Gate | Critério | Status | +|------|----------|--------| +| Piloto | 1–2 dispatchers SHOC em prod; UAT assinado | [ ] | +| Rollout | 100% dispatchers no board SHOC | [ ] | +| Estabilidade | Zero P1 por 2 semanas consecutivas | [ ] | +| Blazor | Módulo WO sunset (`BlazorWorkOrderSunset:Enabled`) | [ ] | +| Lambda | Ingest direto `POST /api/workorders/ingest`; Dynamo/Sync desligados | [ ] | +| Monitoramento | `GET /api/workorders/ops/health` + alertas CloudWatch criados | [ ] | +| Legado | Headers `Sunset`/`Deprecation` nos endpoints legado | [ ] | **Assinatura DONE Fase 7**