Guia de Uso - APIs `/executive`

Base URL: https://csuite.internut.com.br/executive

Documentação Swagger: https://csuite.internut.com.br/executive/docs

📋 Índice

Visão Geral
Policy Engine API
Policy Guardian API
Policies API (CRUD)
Memory API
Governance API
Agents API
Alerts & Action Items API
Dashboard & Monitoring API
Admin API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Executive é o órgão regulador do sistema CSuite, responsável por:

Policy Engine Central: Avaliação de decisões (ALLOW/RECOMMEND/ESCALATE/DENY)
Policy Guardian: Sistema adaptativo de governança com IA
Precedents Engine: Transformação de exceções em precedentes auditáveis
Auto-tuning: Ajuste automático de políticas baseado em histórico
Instrumentação: Auditoria completa de decisões e violações

Fluxo de Governança:

Evento → Violação → Case
Case → Guardian → Precedente
Precedente → Regra
Regra → Score
Score → Auto-tuning
Auto-tuning → Regra

Características:
- ✅ Policy Engine centralizado
- ✅ Integração com Policy Guardian (IA)
- ✅ Versionamento de políticas (SHA256)
- ✅ Instrumentação automática
- ✅ Rate limiting (100 req/min IP, 1000 req/min usuário)

2. Policy Engine API

Base Path: /v1/policy

2.1 Avaliar Decisão

Endpoint: POST /v1/policy/evaluate

Descrição: Avalia uma decisão usando o Policy Engine e retorna ALLOW/RECOMMEND/ESCALATE/DENY.

Request:

{
  "decision_id": "customer_decisions.recommend_next_best_action",
  "actor": "app:csuite-sales-manager",
  "inputs": {
    "org_id": 1,
    "customer_id": 12345,
    "risk_level": "medium",
    "capabilities": ["db:mysql.core", "api:4c.decide"],
    "payload": {
      "sku": "BK4-2516",
      "price": 1500.00
    }
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/policy/evaluate" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "customer_decisions.recommend_next_best_action",
    "actor": "app:csuite-sales-manager",
    "inputs": {
      "org_id": 1,
      "customer_id": 12345,
      "risk_level": "medium",
      "capabilities": ["db:mysql.core"],
      "payload": {
        "sku": "BK4-2516",
        "price": 1500.00
      }
    }
  }'

Resposta (ALLOW):

{
  "decision_id": "customer_decisions.recommend_next_best_action",
  "outcome": "ALLOW",
  "automation": "AUTOMATED",
  "category": "SALES",
  "app": "csuite-sales-manager",
  "reasons": ["policy:min_margin_ok", "policy:customer_tier_allowed"],
  "notify": [],
  "required_fields": [],
  "required_flags": [],
  "missing_capabilities": [],
  "policy_version": "v1.2.3",
  "namespace": "csuite"
}

Resposta (ESCALATE):

{
  "decision_id": "customer_decisions.recommend_next_best_action",
  "outcome": "ESCALATE",
  "automation": "MANUAL",
  "category": "SALES",
  "app": "csuite-sales-manager",
  "reasons": ["policy:margin_below_threshold", "policy:requires_approval"],
  "notify": ["manager:sales", "director:finance"],
  "required_fields": ["approval_code"],
  "required_flags": [],
  "missing_capabilities": [],
  "policy_version": "v1.2.3",
  "namespace": "csuite"
}

Outcomes possíveis:
- ALLOW: Decisão aprovada, pode executar automaticamente
- RECOMMEND: Decisão recomendada, mas requer confirmação
- ESCALATE: Decisão requer aprovação humana
- DENY: Decisão negada, não pode executar

Casos de uso:
- Validação de decisões comerciais
- Controle de acesso a recursos
- Aprovação de ações sensíveis
- Auditoria de decisões

2.2 Listar Decisões Disponíveis

Endpoint: GET /v1/policy/decisions

Descrição: Lista todas as decisões disponíveis no Policy Engine.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/decisions"

Resposta:

{
  "decisions": [
    "customer_decisions.recommend_next_best_action",
    "sales.create_quote",
    "pricing.adjust_price",
    "operations.execute_workflow"
  ],
  "source": "/app/policies/csuite-policies.flattened.yaml",
  "version": "v1.2.3"
}

2.3 Obter Decisão Específica

Endpoint: GET /v1/policy/decision/{decision_id}

Descrição: Obtém detalhes de uma decisão específica.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/decision/customer_decisions.recommend_next_best_action"

Resposta:

{
  "decision_id": "customer_decisions.recommend_next_best_action",
  "automation": "AUTOMATED",
  "category": "SALES",
  "app": "csuite-sales-manager",
  "rules": [
    {
      "rule_code": "min_margin",
      "threshold": 0.10,
      "severity": "high"
    }
  ]
}

2.4 Recarregar Políticas

Endpoint: POST /v1/policy/reload

Descrição: Recarrega políticas do arquivo YAML (requer secret se configurado).

Query Parameters:
- secret (string, obrigatório se CSUITE_POLICY_RELOAD_SECRET configurado)

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/policy/reload?secret=my_secret"

Resposta:

{
  "ok": true,
  "version": "v1.2.4",
  "namespace": "csuite",
  "checksum": "abc123...",
  "decision_count": 45,
  "loaded_at": "2024-12-01T10:00:00Z"
}

2.5 Listar Versões

Endpoint: GET /v1/policy/versions

Descrição: Lista histórico de versões de políticas.

Parâmetros de Query:
- namespace (string, padrão: csuite) - Namespace das políticas
- limit (int, padrão: 50) - Número máximo de versões

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/versions?namespace=csuite&limit=20"

Resposta:

{
  "namespace": "csuite",
  "total": 20,
  "versions": [
    {
      "version": "v1.2.4",
      "checksum": "abc123...",
      "loaded_at": "2024-12-01T10:00:00Z",
      "decision_count": 45
    },
    {
      "version": "v1.2.3",
      "checksum": "def456...",
      "loaded_at": "2024-11-30T15:00:00Z",
      "decision_count": 44
    }
  ]
}

2.6 Versão Mais Recente

Endpoint: GET /v1/policy/versions/latest

Descrição: Obtém a versão mais recente das políticas.

Parâmetros de Query:
- namespace (string, padrão: csuite) - Namespace das políticas

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/versions/latest?namespace=csuite"

2.7 Versão por Checksum

Endpoint: GET /v1/policy/versions/{checksum}

Descrição: Obtém detalhes de uma versão específica por checksum.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/versions/abc123..."

2.8 Health do Policy Engine

Endpoint: GET /v1/policies/health

Descrição: Verifica saúde do Policy Engine.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policies/health"

Resposta:

{
  "status": "ok",
  "version": "v1.2.3",
  "decision_count": 45,
  "last_reload": "2024-12-01T10:00:00Z"
}

3. Policy Guardian API

Base Path: /v1/policy/guardian

3.1 Analisar Casos

Endpoint: POST /v1/policy/guardian/analyze

Descrição: Analisa casos pendentes usando Agente IA e gera outputs (NO_ACTION, POLICY_QUESTION, POLICY_DRAFT, POLICY_DRIFT).

Request:

{
  "decision_id": null,
  "case_id": null,
  "generate_outputs": true
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/policy/guardian/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "generate_outputs": true
  }'

Resposta:

{
  "cases_touched": 5,
  "outputs_created": 3,
  "message": "ok"
}

Fluxo:
1. Rollup de violações para casos (sp_pg_rollup_violations_to_cases)
2. Gera outputs pendentes usando Agente IA (sp_pg_generate_guardian_outputs)

Outputs possíveis:
- NO_ACTION: Nenhuma ação necessária
- POLICY_QUESTION: Questão sobre política existente
- POLICY_DRAFT: Rascunho de nova política
- POLICY_DRIFT: Detecção de drift em política

3.2 Listar Casos Pendentes

Endpoint: GET /v1/policy/guardian/pending

Descrição: Lista casos na fila do Diretor-Guardião.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/pending"

Resposta:

{
  "cases": [
    {
      "case_id": 1,
      "case_code": "CASE-2024-001",
      "policy_ref": "INV_LOW_TURN",
      "severity": "high",
      "opened_at": "2024-12-01T10:00:00Z",
      "violations_count": 5,
      "status": "OPEN"
    }
  ],
  "total": 10
}

3.3 Registrar Decisão do Diretor

Endpoint: POST /v1/policy/guardian/decide

Descrição: Registra decisão do Diretor sobre um caso.

Request:

{
  "case_id": 1,
  "decision": "APPROVE",
  "decision_notes": "Aprovado para implementação",
  "decided_by": "director:finance"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/policy/guardian/decide" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": 1,
    "decision": "APPROVE",
    "decision_notes": "Aprovado para implementação",
    "decided_by": "director:finance"
  }'

3.4 Efetividade de Política

Endpoint: GET /v1/policy/guardian/effectiveness/{policy_key}

Descrição: Obtém métricas de efetividade de uma política.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/effectiveness/INV_LOW_TURN"

3.5 Impacto Financeiro

Endpoint: GET /v1/policy/guardian/financial-impact/{case_id}

Descrição: Obtém impacto financeiro de um caso.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/financial-impact/1"

3.6 Métricas de Aprendizado

Endpoint: GET /v1/policy/guardian/learning-metrics

Descrição: Obtém métricas de aprendizado do Policy Guardian.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/learning-metrics"

3.7 Sugerir Limites

Endpoint: GET /v1/policy/guardian/suggest-limits/{policy_key}

Descrição: Sugere limites para uma política baseado em histórico.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/suggest-limits/INV_LOW_TURN"

3.8 Candidatos a Sunset

Endpoint: GET /v1/policy/guardian/sunset-candidates

Descrição: Lista políticas candidatas a desativação (sunset).

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/sunset-candidates"

3.9 Enterprise Guardian

Endpoints:
- GET /v1/policy/guardian/enterprise/guardian/{customer_ref} - Status do guardian para cliente
- GET /v1/policy/guardian/enterprise/policy/{customer_ref}/{policy_key} - Política específica para cliente
- GET /v1/policy/guardian/enterprise/coverage - Cobertura de políticas enterprise
- GET /v1/policy/guardian/enterprise/concentration - Concentração de políticas

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policy/guardian/enterprise/guardian/40306"

4. Policies API (CRUD)

Base Path: /policies ou /v1/policies

4.1 Listar Políticas

Endpoint: GET /policies/{org_id} ou GET /v1/policies/{org_id}

Descrição: Lista políticas de uma organização.

Parâmetros de Query:
- enabled_only (bool, padrão: false) - Apenas políticas habilitadas

Exemplo:

# Todas as políticas
curl "https://csuite.internut.com.br/executive/policies/1"

# Apenas habilitadas
curl "https://csuite.internut.com.br/executive/policies/1?enabled_only=true"

# Versão v1
curl "https://csuite.internut.com.br/executive/v1/policies/1"

Resposta:

[
  {
    "id": 1,
    "organization_id": 1,
    "rule_type": "constraint",
    "rule_key": "min_margin",
    "rule_value": 0.10,
    "description": "Margem mínima de 10%",
    "enabled": true,
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z",
    "created_by": "admin",
    "updated_by": "admin"
  }
]

4.2 Obter Política

Endpoint: GET /policies/{org_id}/{rule_key} ou GET /v1/policies/{org_id}/{rule_key}

Descrição: Obtém uma política específica.

Exemplo:

curl "https://csuite.internut.com.br/executive/policies/1/min_margin"

4.3 Criar Política

Endpoint: POST /policies/{org_id} ou POST /v1/policies/{org_id}

Descrição: Cria uma nova política.

Request:

{
  "rule_type": "constraint",
  "rule_key": "min_margin",
  "rule_value": 0.10,
  "description": "Margem mínima de 10%",
  "enabled": true
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/policies/1" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "constraint",
    "rule_key": "min_margin",
    "rule_value": 0.10,
    "description": "Margem mínima de 10%",
    "enabled": true
  }'

Tipos de políticas:
- constraint: Restrições (ex: min_margin, max_contacts_per_day)
- guardrail: Proteções (ex: silence_hours, blocked_skus)
- preference: Preferências (ex: priority_skus, allow_channels)

4.4 Atualizar Política

Endpoint: PATCH /policies/{org_id}/{rule_key} ou PATCH /v1/policies/{org_id}/{rule_key}

Descrição: Atualiza uma política existente.

Request:

{
  "rule_value": 0.15,
  "enabled": true,
  "description": "Margem mínima atualizada para 15%"
}

Exemplo:

curl -X PATCH "https://csuite.internut.com.br/executive/policies/1/min_margin" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_value": 0.15,
    "enabled": true
  }'

4.5 Deletar Política

Endpoint: DELETE /policies/{org_id}/{rule_key} ou DELETE /v1/policies/{org_id}/{rule_key}

Descrição: Remove uma política.

Exemplo:

curl -X DELETE "https://csuite.internut.com.br/executive/policies/1/min_margin"

Resposta: 204 No Content

5. Memory API

Base Path: /v1

5.1 Policy Radar

Endpoint: GET /v1/policies

Descrição: Policy Radar - Lista principal de políticas com score e risco.

Parâmetros de Query:
- org_id (int, obrigatório) - ID da organização
- tier (string, opcional) - TRUSTED|GUARDED|EXPERIMENTAL|ALL
- risk (string, opcional) - HIGH|MEDIUM|LOW|ALL
- decay (bool, opcional) - Filtrar por decay
- backlog (bool, opcional) - Filtrar por backlog
- limit (int, padrão: 50) - Limite de resultados

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policies?org_id=1&tier=TRUSTED&limit=20"

Resposta:

{
  "updated_at": "2024-12-01T10:00:00Z",
  "summary": {
    "high_risk": 5,
    "attention": 10,
    "trusted": 30
  },
  "items": [
    {
      "rule_code": "INV_LOW_TURN",
      "score": 85,
      "trend": "UP",
      "tier": "TRUSTED",
      "open_cases": 0,
      "flags": []
    }
  ]
}

5.2 Detalhe de Política

Endpoint: GET /v1/policies/{rule_code}

Descrição: Detalhe cognitivo de uma policy (Policy Memory View).

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policies/INV_LOW_TURN"

Resposta:

{
  "rule_code": "INV_LOW_TURN",
  "current": {
    "severity": "high",
    "cooldown_hours": 24,
    "is_active": true
  },
  "confidence": {
    "score": 85,
    "tier": "TRUSTED",
    "trend": "UP"
  },
  "origin": {
    "precedent_item_id": 123,
    "created_from_case": 45
  }
}

5.3 Timeline de Política

Endpoint: GET /v1/policies/{rule_code}/timeline

Descrição: Linha do tempo de decisões da policy.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policies/INV_LOW_TURN/timeline"

5.4 Casos de Política

Endpoint: GET /v1/policies/{rule_code}/cases

Descrição: Lista casos relacionados a uma política.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/policies/INV_LOW_TURN/cases"

5.5 Precedentes

Endpoints:
- GET /v1/precedents - Lista precedentes
- GET /v1/precedents/draft - Lista rascunhos
- GET /v1/precedents/{item_id} - Obtém precedente
- POST /v1/precedents/{item_id}/approve - Aprova precedente

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/precedents?org_id=1"

5.6 Query de Memória

Endpoint: POST /v1/memory/query

Descrição: Consulta a memória institucional usando IA.

Request:

{
  "question": "Quais políticas foram criadas a partir de casos de baixo giro?",
  "context": {
    "org_id": 1,
    "domain": "inventory"
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/memory/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quais políticas foram criadas a partir de casos de baixo giro?",
    "context": {"org_id": 1}
  }'

6. Governance API

Base Path: /v1/governance

6.1 Policy Radar (Governança)

Endpoint: GET /v1/governance/policies/radar

Descrição: Policy Radar executivo - Visão consolidada das políticas com métricas de performance.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/governance/policies/radar"

Resposta:

{
  "items": [
    {
      "policy_ref": "INV_LOW_TURN",
      "exception_rate_last_day": 0.05,
      "escalations_last_day": 2,
      "score": 85,
      "tier": "TRUSTED"
    }
  ]
}

6.2 Detalhe de Política (Governança)

Endpoint: GET /v1/governance/policies/{policy_ref}/detail

Descrição: Detalhes completos de uma política na visão de governança.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/governance/policies/INV_LOW_TURN/detail"

6.3 Proposed Changes

Endpoints:
- GET /v1/governance/proposed-changes - Lista mudanças propostas
- GET /v1/governance/proposed-changes/ready-to-execute - Mudanças prontas para execução
- GET /v1/governance/proposed-changes/stalled - Mudanças bloqueadas
- GET /v1/governance/proposed-changes/{change_id}/evidence - Evidências de mudança
- GET /v1/governance/proposed-changes/{change_id}/execution-plan - Plano de execução
- POST /v1/governance/proposed-changes/{change_id}/execution-plan/auto-seed - Gerar plano automaticamente
- POST /v1/governance/proposed-changes/{change_id}/review - Revisar mudança
- POST /v1/governance/proposed-changes/{change_id}/mark-executed - Marcar como executado

Exemplo:

# Listar mudanças propostas
curl "https://csuite.internut.com.br/executive/v1/governance/proposed-changes"

# Mudanças prontas para execução
curl "https://csuite.internut.com.br/executive/v1/governance/proposed-changes/ready-to-execute"

6.4 Execution Steps

Endpoints:
- GET /v1/governance/execution-steps/{exec_id} - Obtém passo de execução
- GET /v1/governance/execution-steps/blocked - Lista passos bloqueados

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/governance/execution-steps/1"

6.5 Health de Governança

Endpoint: GET /v1/governance/health

Descrição: Verifica saúde do sistema de governança.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/governance/health"

6.6 Attention Exceeded

Endpoint: GET /v1/governance/attention-exceeded/recent

Descrição: Lista casos recentes onde o attention budget foi excedido.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/governance/attention-exceeded/recent"

6.7 Attention Status

Endpoint: GET /v1/attention/status

Descrição: Retorna status de atenção necessária para budgets e uso.

Parâmetros de Query:
- scope_type (string, opcional) - Tipo de escopo (policy, budget, etc)
- scope_ref (string, opcional) - Referência do escopo

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/attention/status?scope_type=policy&scope_ref=INV_LOW_TURN"

6.8 Charge and Bridge

Endpoint: POST /v1/attention/charge-and-bridge

Descrição: Carrega attention budget e faz bridge para execution.

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/v1/attention/charge-and-bridge" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "policy",
    "scope_ref": "INV_LOW_TURN",
    "action": "execute"
  }'

6.9 Audit Timeline

Endpoint: GET /v1/audit/timeline

Descrição: Timeline de auditoria de decisões e mudanças.

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/audit/timeline?org_id=1&days=30"

6.10 Cases

Endpoints:
- GET /v1/cases/{case_id} - Obtém caso específico
- GET /v1/cases/{case_id}/similar - Lista casos similares

Exemplo:

curl "https://csuite.internut.com.br/executive/v1/cases/1"

7. Agents API

Base Path: /agents

7.1 Executar Agente CFO

Endpoint: POST /agents/{org_id}/cfo/run

Descrição: Executa o agente CFO para uma organização.

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/agents/1/cfo/run"

Resposta:

{
  "run_id": 123,
  "org_id": 1,
  "agent_code": "CFO",
  "status": "completed",
  "alerts_generated": 5,
  "action_items_created": 3,
  "executed_at": "2024-12-01T10:00:00Z"
}

7.2 Executar Agente Genérico

Endpoint: POST /agents/{org_id}/{code}/run

Descrição: Executa um agente específico (CFO, CEO, COO, CMO, CAIO).

Exemplo:

# Executar CEO
curl -X POST "https://csuite.internut.com.br/executive/agents/1/CEO/run"

# Executar COO
curl -X POST "https://csuite.internut.com.br/executive/agents/1/COO/run"

7.3 Listar Execuções

Endpoint: GET /agents/{org_id}/runs

Descrição: Lista histórico de execuções de agentes.

Parâmetros de Query:
- agent_code (string, opcional) - Filtrar por agente
- limit (int, padrão: 50) - Limite de resultados
- offset (int, padrão: 0) - Offset para paginação

Exemplo:

# Todas as execuções
curl "https://csuite.internut.com.br/executive/agents/1/runs"

# Execuções do CFO
curl "https://csuite.internut.com.br/executive/agents/1/runs?agent_code=CFO"

# Com paginação
curl "https://csuite.internut.com.br/executive/agents/1/runs?limit=20&offset=0"

Resposta:

[
  {
    "id": 123,
    "org_id": 1,
    "agent_code": "CFO",
    "status": "completed",
    "alerts_generated": 5,
    "action_items_created": 3,
    "executed_at": "2024-12-01T10:00:00Z",
    "completed_at": "2024-12-01T10:05:00Z"
  }
]

7.4 Listar Agentes

Endpoint: GET /agents/{org_id}

Descrição: Lista agentes disponíveis para uma organização.

Exemplo:

curl "https://csuite.internut.com.br/executive/agents/1"

Resposta:

[
  {
    "code": "CFO",
    "name": "Chief Financial Officer",
    "status": "active",
    "last_run": "2024-12-01T10:00:00Z"
  },
  {
    "code": "CEO",
    "name": "Chief Executive Officer",
    "status": "active",
    "last_run": "2024-12-01T09:00:00Z"
  }
]

7.5 Alertas de Agentes

Endpoint: GET /agents/{org_id}/alerts

Descrição: Lista alertas gerados por agentes.

Parâmetros de Query:
- severity (string, opcional) - Filtrar por severidade
- status (string, opcional) - Filtrar por status
- limit (int, padrão: 50) - Limite de resultados

Exemplo:

curl "https://csuite.internut.com.br/executive/agents/1/alerts?severity=high"

8. Alerts & Action Items API

Base Path: /alerts, /action-items

8.1 Listar Alertas

Endpoint: GET /agents/{org_id}/alerts

Descrição: Lista alertas de uma organização.

Parâmetros de Query:
- severity (string, opcional) - Filtrar por severidade
- status (string, opcional) - Filtrar por status (open, acknowledged, resolved)
- limit (int, padrão: 50) - Limite de resultados

Exemplo:

# Todos os alertas
curl "https://csuite.internut.com.br/executive/agents/1/alerts"

# Alertas críticos abertos
curl "https://csuite.internut.com.br/executive/agents/1/alerts?severity=critical&status=open"

8.2 Reconhecer Alerta

Endpoint: POST /alerts/{alert_id}/ack

Descrição: Reconhece um alerta (acknowledge).

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/alerts/123/ack"

Resposta:

{
  "alert_id": 123,
  "status": "acknowledged",
  "acknowledged_at": "2024-12-01T10:00:00Z"
}

8.3 Listar Action Items

Endpoint: GET /action-items/{org_id}

Descrição: Lista action items de uma organização.

Parâmetros de Query:
- status (string, opcional) - Filtrar por status (pending, in_progress, completed)
- priority (string, opcional) - Filtrar por prioridade
- limit (int, padrão: 50) - Limite de resultados

Exemplo:

# Action items pendentes
curl "https://csuite.internut.com.br/executive/action-items/1?status=pending"

# Action items de alta prioridade
curl "https://csuite.internut.com.br/executive/action-items/1?priority=high"

8.4 Obter Action Item

Endpoint: GET /action-items/{item_id}

Descrição: Obtém detalhes de um action item.

Exemplo:

curl "https://csuite.internut.com.br/executive/action-items/123"

8.5 Alert Rules

Endpoints:
- GET /alert-rules/{org_id} - Lista regras de alerta
- POST /alert-rules - Cria regra de alerta
- PATCH /alert-rules/{rule_id} - Atualiza regra de alerta
- DELETE /alert-rules/{rule_id} - Remove regra de alerta
- GET /alert-rules/{org_id}/export - Exporta regras
- POST /alert-rules/{org_id}/import - Importa regras

Exemplo:

# Listar regras
curl "https://csuite.internut.com.br/executive/alert-rules/1"

# Exportar regras
curl "https://csuite.internut.com.br/executive/alert-rules/1/export"

9. Dashboard & Monitoring API

Base Path: /dashboard, /monitoring

9.1 Resumo do Dashboard

Endpoint: GET /dashboard/summary/{org_id}

Descrição: Retorna resumo executivo do dashboard.

Exemplo:

curl "https://csuite.internut.com.br/executive/dashboard/summary/1"

Resposta:

{
  "org_id": 1,
  "alerts_open": 5,
  "items_pending": 8,
  "last_run": "2024-12-01T10:00:00Z",
  "agents_status": {
    "CFO": "active",
    "CEO": "active",
    "COO": "active"
  }
}

9.2 Métricas de Monitoramento

Endpoint: GET /monitoring/metrics/{org_id}

Descrição: Obtém métricas de monitoramento de uma organização.

Exemplo:

curl "https://csuite.internut.com.br/executive/monitoring/metrics/1"

9.3 Resumo de Monitoramento

Endpoint: GET /monitoring/summary/{org_id}

Descrição: Retorna resumo de monitoramento.

Exemplo:

curl "https://csuite.internut.com.br/executive/monitoring/summary/1"

9.4 System Health

Endpoint: GET /monitoring/system-health

Descrição: Obtém status geral de saúde do sistema.

Exemplo:

curl "https://csuite.internut.com.br/executive/monitoring/system-health"

10. Admin API

Base Path: /admin

10.1 Listar Tabelas

Endpoint: GET /admin/tables

Descrição: Lista todas as tabelas do banco de dados.

Exemplo:

curl "https://csuite.internut.com.br/executive/admin/tables"

10.2 Descrever Tabela

Endpoint: GET /admin/describe

Descrição: Descreve estrutura de uma tabela.

Parâmetros de Query:
- table (string, obrigatório) - Nome da tabela

Exemplo:

curl "https://csuite.internut.com.br/executive/admin/describe?table=pg_decision_log"

10.3 Executar Query

Endpoint: GET /admin/query

Descrição: Executa query SQL (read-only, use com cuidado).

Parâmetros de Query:
- sql (string, obrigatório) - Query SQL

Exemplo:

curl "https://csuite.internut.com.br/executive/admin/query?sql=SELECT COUNT(*) FROM pg_decision_log"

⚠️ Aviso: Use apenas para queries SELECT. Queries de modificação são bloqueadas.

11. Scheduler API

Base Path: /scheduler

11.1 Listar Jobs

Endpoint: GET /scheduler/jobs

Descrição: Lista jobs agendados.

Exemplo:

curl "https://csuite.internut.com.br/executive/scheduler/jobs"

11.2 Agendar Job

Endpoint: POST /scheduler/schedule/{org_id}/{agent_code}

Descrição: Agenda execução periódica de um agente.

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/scheduler/schedule/1/CFO"

11.3 Cancelar Agendamento

Endpoint: POST /scheduler/unschedule/{org_id}/{agent_code}

Descrição: Cancela agendamento de um agente.

Exemplo:

curl -X POST "https://csuite.internut.com.br/executive/scheduler/unschedule/1/CFO"

12. Exemplos Práticos

12.1 Avaliar Decisão Completa

# 1. Avaliar decisão de venda
curl -X POST "https://csuite.internut.com.br/executive/v1/policy/evaluate" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "customer_decisions.recommend_next_best_action",
    "actor": "app:csuite-sales-manager",
    "inputs": {
      "org_id": 1,
      "customer_id": 12345,
      "risk_level": "medium",
      "capabilities": ["db:mysql.core"],
      "payload": {
        "sku": "BK4-2516",
        "price": 1500.00
      }
    }
  }'

# 2. Verificar versão das políticas
curl "https://csuite.internut.com.br/executive/v1/policy/versions/latest"

12.2 Policy Guardian Workflow

# 1. Analisar casos pendentes
curl -X POST "https://csuite.internut.com.br/executive/v1/policy/guardian/analyze" \
  -H "Content-Type: application/json" \
  -d '{"generate_outputs": true}'

# 2. Listar casos pendentes
curl "https://csuite.internut.com.br/executive/v1/policy/guardian/pending"

# 3. Registrar decisão do diretor
curl -X POST "https://csuite.internut.com.br/executive/v1/policy/guardian/decide" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": 1,
    "decision": "APPROVE",
    "decision_notes": "Aprovado",
    "decided_by": "director:finance"
  }'

12.3 Gerenciar Políticas

# 1. Listar políticas
curl "https://csuite.internut.com.br/executive/policies/1?enabled_only=true"

# 2. Criar política
curl -X POST "https://csuite.internut.com.br/executive/policies/1" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "constraint",
    "rule_key": "min_margin",
    "rule_value": 0.10,
    "description": "Margem mínima de 10%",
    "enabled": true
  }'

# 3. Atualizar política
curl -X PATCH "https://csuite.internut.com.br/executive/policies/1/min_margin" \
  -H "Content-Type: application/json" \
  -d '{"rule_value": 0.15}'

12.4 Executar Agentes

# 1. Executar CFO
curl -X POST "https://csuite.internut.com.br/executive/agents/1/cfo/run"

# 2. Ver histórico de execuções
curl "https://csuite.internut.com.br/executive/agents/1/runs?agent_code=CFO&limit=10"

# 3. Ver alertas gerados
curl "https://csuite.internut.com.br/executive/agents/1/alerts?severity=high"

13. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-executive está rodando
Verifique se o path está correto (/executive/v1/policy ou /executive/agents)
Verifique se o endpoint existe na documentação OpenAPI

Erro: "Unauthorized" (401)

Verifique autenticação via csuite-auth
Faça login em /login primeiro

Erro: "Forbidden" (403) em `/policy/reload`

Verifique se o secret está correto
Verifique se CSUITE_POLICY_RELOAD_SECRET está configurado

Erro: "decision_id not found" (404)

Verifique se o decision_id existe no arquivo de políticas
Verifique se as políticas foram carregadas (/v1/policy/decisions)
Verifique aliases (ex: 4c.recommend_next_best_action → customer_decisions.recommend_next_best_action)

Outcome sempre ESCALATE/DENY

Verifique se os inputs estão corretos
Verifique se as capabilities são suficientes
Verifique se as políticas estão habilitadas
Verifique logs do Policy Engine

Policy Guardian não gera outputs

Verifique se existem casos pendentes (/v1/policy/guardian/pending)
Verifique se o Agente IA está configurado
Verifique logs do Guardian
Verifique se a procedure sp_pg_generate_guardian_outputs existe

Dados não aparecem no Memory API

Verifique se os jobs foram executados
Verifique se as views existem no banco (vw_pg_policy_score, etc.)
Verifique se há dados no schema csuite_memory

14. Documentação Relacionada

14.1 Documentação Interna

README: csuite-executive/README.md
Policy Engine: csuite-executive/POLICY_ENGINE.md
Policy Guardian: csuite-executive/docs/POLICY_GUARDIAN.md
Policy Guardian Agent: csuite-executive/docs/POLICY_GUARDIAN_AGENT.md
Policy Versioning: csuite-executive/docs/POLICY_VERSIONING.md
Instrumentation: csuite-executive/docs/POLICY_ENGINE_INSTRUMENTATION.md

14.2 Postman Collection

Arquivo: csuite-executive/CSuite_API.postman_collection.json

Coleção completa de endpoints para importar no Postman.

15. Próximos Passos

Adicionar webhooks para notificações de decisões
Adicionar exportação CSV/Excel de decisões
Adicionar métricas de performance (tempo de resposta)
Adicionar cache para queries frequentes
Adicionar rate limiting por usuário/org

16. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/executive/docs

OpenAPI JSON: https://csuite.internut.com.br/executive/openapi.json

ReDoc: https://csuite.internut.com.br/executive/redoc

Última atualização: 2024-12-20
Versão: 0.1.0

Guia de Uso - APIs /executive

📋 Índice

1. Visão Geral

2. Policy Engine API

2.1 Avaliar Decisão

2.2 Listar Decisões Disponíveis

2.3 Obter Decisão Específica

2.4 Recarregar Políticas

2.5 Listar Versões

2.6 Versão Mais Recente

2.7 Versão por Checksum

2.8 Health do Policy Engine

3. Policy Guardian API

3.1 Analisar Casos

3.2 Listar Casos Pendentes

3.3 Registrar Decisão do Diretor

3.4 Efetividade de Política

3.5 Impacto Financeiro

3.6 Métricas de Aprendizado

3.7 Sugerir Limites

3.8 Candidatos a Sunset

3.9 Enterprise Guardian

4. Policies API (CRUD)

4.1 Listar Políticas

4.2 Obter Política

4.3 Criar Política

4.4 Atualizar Política

4.5 Deletar Política

5. Memory API

5.1 Policy Radar

5.2 Detalhe de Política

5.3 Timeline de Política

5.4 Casos de Política

5.5 Precedentes

5.6 Query de Memória

6. Governance API

6.1 Policy Radar (Governança)

6.2 Detalhe de Política (Governança)

6.3 Proposed Changes

6.4 Execution Steps

6.5 Health de Governança

6.6 Attention Exceeded

6.7 Attention Status

6.8 Charge and Bridge

6.9 Audit Timeline

6.10 Cases

7. Agents API

7.1 Executar Agente CFO

7.2 Executar Agente Genérico

7.3 Listar Execuções

7.4 Listar Agentes

7.5 Alertas de Agentes

8. Alerts & Action Items API

8.1 Listar Alertas

8.2 Reconhecer Alerta

8.3 Listar Action Items

8.4 Obter Action Item

8.5 Alert Rules

9. Dashboard & Monitoring API

9.1 Resumo do Dashboard

9.2 Métricas de Monitoramento

9.3 Resumo de Monitoramento

9.4 System Health

10. Admin API

10.1 Listar Tabelas

10.2 Descrever Tabela

10.3 Executar Query

11. Scheduler API

11.1 Listar Jobs

11.2 Agendar Job

11.3 Cancelar Agendamento

12. Exemplos Práticos

12.1 Avaliar Decisão Completa

12.2 Policy Guardian Workflow

12.3 Gerenciar Políticas

12.4 Executar Agentes

13. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Forbidden" (403) em /policy/reload

Guia de Uso - APIs `/executive`

Erro: "Forbidden" (403) em `/policy/reload`