REF-501-02: ServiceRequest Workflow
ADR: ADR-501 — Service DeliveryEscopo: Fluxo completo de OS, estados, análise detalhada como SR separada, campos, Jira vs Plugin
1. Diagrama de Estados
┌──── rejected ────► CLOSED
│
DRAFT ──► PENDING_APPROVAL ──► APPROVED ──► IN_PROGRESS ──► COMPLETED ──► BILLED
│
└──── blocked ────► ON_HOLD| Estado | Significado | Transições |
|---|---|---|
draft | Criada, aguardando envio para aprovação | → pending_approval |
pending_approval | Aguardando aprovação do cliente | → approved, closed (rejected) |
approved | Cliente aprovou, pronta para execução | → in_progress |
in_progress | Trabalho em andamento | → completed, on_hold |
on_hold | Bloqueada (dependência externa, espera do cliente) | → in_progress |
completed | Trabalho concluído, UST real registrada | → billed |
closed | Encerrada sem execução (rejeitada ou cancelada) | Estado terminal |
billed | Faturada ao cliente | Estado terminal |
2. Fluxo Completo
1. Criação
├── Jira: issue criada (primário para equipe)
├── Plugin: SR criada via webhook (espelho)
└── Campos preenchidos: catalog_service, complexity, ust_estimated
2. Triagem
├── Validar escopo e determinar complexidade
├── USTs pré-aprovadas E adequadas? → Pular para Execução
└── Caso contrário → Etapa de Aprovação
3. Aprovação
├── Requer análise detalhada? → SR de análise separada (ver seção 3)
├── Cliente notificado: "OS #X requer aprovação — Y créditos estimados"
├── Aprovado → approved
└── Rejeitado → closed (zero billing)
4. Execução
├── Equipe trabalha no Jira
├── Status sincronizado Jira → Plugin via webhook
└── Bloqueio → on_hold (com motivo)
5. Conclusão
├── ust_actual preenchido (pode diferir do estimado)
├── billed_value calculado: ust_actual × complexity_factor × base_value_at_creation
└── Status: completed
6. Faturamento
├── SR incluída na fatura mensal
├── Créditos debitados do CreditBalance (se aplicável)
└── Status: billed3. Análise Detalhada como SR Separada
Serviços marcados "Requer Análise" (itens 4-8, 10-13) exigem fase de análise antes da execução.
SR-20260002 (Integração de API — execução)
│
└── SR-20260003 (Análise de Requisitos — análise)
├── parent_sr: SR-20260002
├── Faturável independentemente
└── Se cliente rejeita execução após análise:
→ SR-20260003 faturada (análise realizada)
→ SR-20260002 closed (zero billing)Regra crítica: Análise e execução são SRs separadas com faturamento independente.
4. Campos do ServiceRequest
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Formato SR-YYYYNNNN |
entitlement_id | FK | Entitlement pai (SVC ou ENV) |
service_id | FK | Service contêiner (se aplicável) |
catalog_service | enum | Serviço do catálogo (1-13) ou custom |
complexity | enum | low / medium / high |
ust_estimated | decimal | Pré-preenchido do catálogo, editável pelo admin |
ust_actual | decimal | USTs reais (preenchido na conclusão) |
base_value_at_creation | decimal | Snapshot do valor base quando SR criada |
billed_value | decimal | Calculado: ust_actual × complexity_factor × base_value |
status | enum | draft / pending_approval / approved / in_progress / on_hold / completed / closed / billed |
requires_analysis | boolean | Do catálogo — direciona fluxo de aprovação |
parent_sr | FK (nullable) | Se SR de análise, aponta para SR de execução |
jira_issue_key | string | Issue Jira vinculada (ex: PROJ-123) |
billing_mode | enum | ust (padrão) ou hourly (taxa por função) |
5. Jira vs Plugin — Responsabilidade por Dado
| Dado | Fonte de Verdade | Sync | Notas |
|---|---|---|---|
| Status da OS | Jira | Jira → Plugin | Jira vence para workflow |
| UST estimada | Plugin | Plugin → Jira | Plugin define, Jira lê |
| UST real | Plugin | Calculado | Derivado de worklogs Jira + complexidade |
| Valor faturado | Plugin | N/A | Plugin é autoridade única de billing |
| Tipo de serviço | Plugin | Plugin → Jira | Catálogo do plugin |
| Tarefas | Jira | N/A | Plugin não replica gestão de projeto |
| SLA rules | Jira | Jira → Plugin | Jira aplica, plugin exibe no portal |
6. Criação de SR pelo Cliente (modo standalone)
O cliente pode solicitar ServiceRequests diretamente pelo portal para Entitlements de classe ENV (manutenção de ambientes gerenciados):
| Etapa | Descrição |
|---|---|
| 1. Acesso | Na página de detalhe do Environment, cliente clica "Solicitar Serviço" |
| 2. Dados | Preenche: título, descrição, prioridade (low/normal/high/urgent) |
| 3. Criação | Sistema cria SR com status draft, vinculada ao Entitlement ENV do Environment |
| 4. Número | service_request_number gerado atomicamente no formato SR-YYYYNNNN |
| 5. Admin | Admin recebe notificação, revisa a SR e transiciona para pending_approval ou approved |
O cliente também pode solicitar via Jira (redirecionamento externo) — nesse caso o admin cria a SR internamente no plugin.
Para SRs vinculadas a Service (modo vinculado), apenas o admin pode criar — o cliente não tem acesso a essa funcionalidade.
7. Notificações
ServiceRequests disparam notificações em pontos-chave do ciclo de vida:
| Evento | Destinatário | Canal |
|---|---|---|
| SR criada (pelo cliente) | Admin | Email + painel admin |
| SR atribuída | Responsável interno | Email + Jira (se vinculado) |
| SR em review/completed | Cliente | Email + portal |
| SR aprovada pelo cliente | Equipe interna | Email + Jira |
| SR atrasada (due_date excedida) | Admin + responsável | Email + alerta admin |
NotificationPolicy (configurável no admin) determina quais canais são ativados para cada evento.
8. Portal Visibility (ServiceRequest)
Regras de visibilidade para o cliente no portal:
| Dado | Visível ao cliente? | Nota |
|---|---|---|
| Status | Sim | Todos os estados do workflow |
| Prioridade | Sim | |
| Due date | Sim | |
| Título e descrição | Sim | |
| Client notes | Sim | Campo específico para comunicação com cliente |
| Notas internas | Não | Visível apenas para admin e equipe |
| Horas reais | Não | ust_actual não exposto ao cliente |
| Assigned_to | Não | Detalhe interno de atribuição |
| Billed value | Sim (após billed) | Visível apenas quando SR está no estado billed |
| Créditos consumidos | Sim | Exibido no extrato de CreditBalance |
SRs são exibidas em dois contextos:
- Modo vinculado: dentro do detalhe do Service pai
- Modo standalone: na página de detalhe do Environment