ADR-501: Service Delivery — Service, ServiceRequest, Environment, Contract, CreditBalance
Status: Accepted
Contexto
MIDDAG Services (serviços profissionais) opera com modelo UST (Unidade de Serviço Técnico), projetos no Jira, billing mensal por consumo, e clientes sem visibilidade no status dos projetos. Rastreamento de UST em planilhas, faturamento mensal com cálculo manual, renovações de contrato dependem de memória. Plugin deve unificar billing, portal do cliente e rastreamento — sem substituir Jira para gestão de projeto.
Decisão
5 Domínios no Bounded Context Service Delivery
| Domínio | Tipo | Responsabilidade |
|---|---|---|
| Service | OPTIONAL | Projetos e contratos contínuos (contêiner de SRs) |
| ServiceRequest | OPTIONAL | Ordens de serviço granulares (SR-YYYYNNNN) |
| Environment | OPTIONAL | Instalações de plataforma gerenciada (rastreia, não provisiona) |
| Contract | OPTIONAL | SLA terms, renovação, fidelidade |
| CreditBalance | OPTIONAL | Saldo de créditos/USTs (auto-ativa com Service) |
Service (Projetos e Contratos)
| Aspecto | Detalhe |
|---|---|
| Vinculação | Service pertence a Entitlement (classe SVC) |
| Lifecycle | ongoing (contrato contínuo) ou project (início/fim) |
| Type | service, lab, development (opcional, categorização) |
| Jira | jira_project_key vincula ao projeto Jira |
| Contêiner | Agrupa ServiceRequests como itens de trabalho |
Detalhes de lifecycle, campos e auto-criação em REF-501-05.
ServiceRequest (Ordem de Serviço)
Código: SR-YYYYNNNN. Vinculado a Service OU Environment.
| Aspecto | Detalhe |
|---|---|
| Catálogo | 13 serviços catalogados com complexidade e créditos padrão |
| Billing | UST-based (créditos × complexidade × valor_base) ou horário |
| Aprovação | Workflow: draft → pending_approval → approved → in_progress → completed → billed |
| Análise | Serviços avançados requerem análise detalhada (SR separada, faturável independentemente) |
| Jira | jira_issue_key sincronizado via webhook |
Detalhes do workflow em REF-501-02.
Environment (Hosting Gerenciado)
| Aspecto | Detalhe |
|---|---|
| Vinculação | Environment pertence a Entitlement (classe ENV) |
| Responsabilidade | Rastreia instalações — NÃO provisiona infraestrutura |
| Dados | URL, plataforma (Moodle/WordPress/custom), SSL, backup |
| ServiceRequests | SRs standalone para manutenção vinculadas ao Environment |
Detalhes de tipos, lifecycle, campos e monitoramento em REF-501-06.
Contract (SLA e Renovação)
| Aspecto | Detalhe |
|---|---|
| Vinculação | Contract pertence a Entitlement (classe SVC) |
| Auto-ativação | POLICY configurável: Service, Environment ou ambos |
| Conteúdo | Termos de SLA, valor mensal/anual, data início/fim/renovação |
| Documento | PDF assinado vinculado (domínio Document) |
Detalhes em REF-501-04.
CreditBalance (UST / Créditos)
| Aspecto | Detalhe |
|---|---|
| Vinculação | CreditBalance pertence a Entitlement (classe SVC) |
| Auto-ativação | Ativa quando Service habilitado — mesmo zerado, mensurar custo |
| Terminologia | Interno: UST. Comercial: crédito/credit |
| Granularidade | Crédito = inteiro. 1 crédito = 10 unidades internas. |
| Consumo | FIFO (mais antigo primeiro). Reserva na abertura, débito na conclusão. |
| Policy | CreditPolicy governa expiração, carência, limites |
Detalhes em REF-501-03.
Modelo UST como Conceito
UST padroniza esforço: "Atualização de Plugin" sempre custa 4 créditos, independentemente das horas reais. Protege cliente contra ineficiência e MIDDAG contra subestimativa. Valor base configurável no admin. 3 níveis de complexidade (low 1x, medium 1.5x, high 2x). Catálogo com 13 serviços.
Detalhes em REF-501-01.
Document (Armazenamento de Arquivos)
O domínio Contract referencia documentos PDF assinados via signed_document (FK). O domínio Document é um domínio de suporte que gerencia armazenamento genérico de arquivos vinculados a Organizations — propostas, relatórios, certificados, contratos assinados. Não é parte do bounded context Service Delivery, mas é consumido por Contract.
| Aspecto | Detalhe |
|---|---|
| Armazenamento | Cloudflare R2 — upload via admin, URL persistida no registro |
| Signed URLs | Downloads gerados com tokens temporários para segurança |
| Metadata | Nome, tipo MIME, tamanho, hash armazenados no registro do documento |
| Limite | 50MB por arquivo |
| Tipos aceitos | PDF, DOCX, XLSX, PNG, JPG (configurável pelo admin) |
| Vinculação | Organization (genérico) — sem relação direta com Entitlement |
Detalhes do ciclo de vida de documentos e armazenamento R2 serão documentados em ADR próprio quando o domínio Document for implementado.
Jira como Complemento
Jira faz gestão de projeto (tarefas, sprints, worklogs, SLA rules). Plugin faz billing (UST, faturamento), portal do cliente (status, consumo) e catálogo de serviços. Comunicação via webhooks bidirecionais. Plugin é fonte de verdade financeira — Jira é fonte de verdade operacional.
Consequências
Positivas:
- 5 domínios cobrem ciclo completo de entrega de serviço B2B
- Modelo UST padroniza precificação — elimina "liga pro Michael pra perguntar"
- CreditBalance ativo mesmo zerado permite mensurar custo operacional real
- Jira complementa sem ser substituído — cada sistema faz o que faz melhor
Negativas:
- 5 domínios OPTIONAL adicionam complexidade significativa
- Integração Jira bidirecional é complexa (webhooks, conflict resolution)
- CreditBalance com FIFO e reserva requer lógica transacional cuidadosa
- Contract com auto-ativação via POLICY pode confundir admin
Referências
- REF-501-01 — UST Model & Service Catalog
- REF-501-02 — ServiceRequest Workflow
- REF-501-03 — CreditBalance & CreditPolicy
- REF-501-04 — Contract Lifecycle
- REF-501-05 — Service Spec
- REF-501-06 — Environment Spec
- ADR-202 — Entitlement (SVC provisiona Service/Contract/CreditBalance)
operations/04-service-catalog.md— Catálogo completo e modelo UST