@genne/genne-cli 0.1.33 → 0.1.35

package/GR.md

@@ -1,83 +0,0 @@
-# GR pelo terminal
-
-A CLI usa os endpoints GR existentes do Core. Readiness, vínculo, mercado, configuração, estado, permissões e execução externa continuam sendo decisões do Core. `genne help admin gr`, `genne help carrier gr` e `genne help driver profile` mostram sintaxe, filtros, JSON e confirmação.
-
-## Papéis e ACL
-
-| Sessão ativa | Responsabilidade | Autorização no Core |
-| --- | --- | --- |
-| Driver | Enviar o próprio cadastro/documentos, informar treinamento e consultar prontidão/pendências | Papel driver e identidade da sessão; sem gestão de providers, requests ou outros motoristas |
-| Shipper | Não possui gestão de GR neste contrato | GR está fora do catálogo customer shipper; usar uma base shipper como operação não concede gestão |
-| Carrier | Configurar providers/mappings e operar motoristas vinculados e requests próprias | Membership ativa, módulo GR ativo e permissões efetivas; conta derivada da sessão |
-| Admin | Diretório global, gestão das carriers e definições globais | Super admin ou grants explícitos do staff; papel admin sozinho não concede acesso total |
-
-Leituras Admin/carrier aceitam `gr.view` ou `gr.manage`. Mutações exigem `gr.manage`; declarações pessoais no Admin exigem também `privacy.manage`. Senhas continuam write-only, conforme o DTO do Core. Nenhuma chave de permissão ou entitlement foi acrescentada, portanto não há seed/backfill de ACL neste incremento.
-
-O `role` de `/auth/me` é o papel ativo. Uma identidade driver + admin precisa de sessões separadas; a CLI não soma `roles` nem interpreta grants para autorizar chamadas. Um 403 do Core encerra a operação, sem trocar papel ou conta.
-
-## Cobertura operacional
-
-IDs nos comandos são UUIDs públicos. `admin gr` usa `/api/v1/admin/gr`; `carrier gr` usa `/api/v1/carrier/gr`.
-
-| Trabalho | Comando relativo a `admin gr` ou `carrier gr` |
-| --- | --- |
-| Diretório global, incluindo perfis sem vínculo | Admin `drivers [carrier_account_id=UUID] [filtros]` → `GET /admin/gr/drivers` |
-| Diretório da carrier | Carrier `drivers [filtros]`; Admin `carriers CARRIER_ID drivers [filtros]` |
-| Detalhe global | Admin `driver-profiles PROFILE_ID show` |
-| Dashboard e bloqueados | Carrier `dashboard`, `blacklist list`; Admin `carriers CARRIER_ID dashboard`, `… blacklist list` |
-| Bloquear/desbloquear vínculo | Carrier `links LINK_ID blacklist\|unblock`; Admin `carriers CARRIER_ID links LINK_ID blacklist\|unblock` |
-| Aprovar/revogar GR externo | Carrier `links LINK_ID manual-approval`; Admin `carriers CARRIER_ID links LINK_ID manual-approval`; JSON stdin `{"approved":true\|false}` |
-| Exportar e reprocessar documento | Carrier `drivers PROFILE_ID export`, `… documents TYPE reprocess`; Admin sob `carriers CARRIER_ID drivers …` |
-| Registrar treinamento | `driver-profiles PROFILE_ID training` |
-| Definições globais | `provider-definitions list`; somente Admin `provider-definitions PROVIDER_ID update` |
-| Contas de providers | `providers list\|create\|PROVIDER_ID update\|test\|operations` |
-| Mapping da operação | `providers PROVIDER_ID mappings list\|upsert` |
-| Fila e criação | `requests list\|create` |
-| Estado e histórico | `requests REQUEST_ID show\|attempts\|evidence\|orchestration-events` |
-| Transições | `requests REQUEST_ID retry\|verify\|cancel\|confirm-recovery\|operation\|personal-declarations` |
-
-O driver usa `driver profile draft|complete` com JSON por stdin e documentos locais opcionais. `training_watched` aceita booleano. `driver profile show` retorna treinamento, `ready_for_gr`, blocos e status documental próprios. Isso não cria uma request nem declara aprovação pelo provider.
-
-## Sequência operacional
-
-1. Confira `genne env show` e `genne whoami`; selecione a sessão e a conta corretas.
-2. Consulte diretório e detalhe/export. Corrija pendências pelo cadastro/documentos existentes; prontidão é calculada no Core.
-3. Consulte definitions, providers, operations e mappings. Escolha provider e operação explicitamente; a CLI não infere operação por cidade, documento ou nome. O fallback legado permanece no Core.
-4. Envie `driver_profile_id`, `provider_account_id` e `operation_key` por stdin a `gr requests create`. Confirme no terminal.
-5. Consulte `requests REQUEST_ID show` e históricos. Use `allowed_actions` e requirements do Core; `202`/`queued` são aceitação, não conclusão.
-6. `verify` reconcilia/verifica; `retry` solicita nova execução permitida. Para recovery, envie a revisão e operações exatas da prévia vigente. A confirmação mostra esses valores; o Core rejeita revisão obsoleta.
-
-Use `meta.next_cursor` mantendo os demais filtros. `limit` é tamanho do lote, não página. Requests e attempts usam `pagination=cursor` automaticamente. Proteja o histórico do shell e as saídas operacionais que contêm dados pessoais.
-
-A cobertura funcional corresponde às ações de gestão das telas GR: reprocessamento, transições, configuração e acompanhamento reutilizam o backend já existente. A release 0.1.2 distribui esta integração; a revalidação do backend é evidência adicional.
-
-## Aprovação manual de GR externo
-
-Use o UUID público do vínculo (`link_id`), não o perfil ou usuário do motorista.
-Confira `genne env show` e `genne whoami` antes de operar. A sessão precisa ter
-`gr.manage`; o Core valida o vínculo ativo, não bloqueado e da transportadora correta.
-
-```sh
-printf '%s' '{"approved":true}' | genne carrier gr links LINK_ID manual-approval
-printf '%s' '{"approved":false}' | genne admin gr carriers CARRIER_ID links LINK_ID manual-approval
-```
-
-Confirme o `LINK_ID` no terminal após revisar a ação e a transportadora. `true`
-registra a aprovação externa; `false` remove somente essa aprovação manual e
-volta a considerar o resultado do provider. Não altera treinamento, documentos,
-evidências do provider ou aprovação em outra transportadora. A resposta síncrona
-traz `link_id`, `driver_user_id` e `manual_approval` com `approved`, `updated_at`
-e `updated_by_user_id`, definidos pelo Core. A CLI não repete escritas automaticamente.
-
-Requer os endpoints de aprovação manual do [Core #132](https://github.com/genneco/genne-core/pull/132).
-Testes locais com API simulada comprovam o contrato do cliente, não deploy nem
-aprovação real em produção. Não há tool MCP de aprovação manual: o stdio segue
-somente leitura e o MCP remoto exige uma intenção específica no Core.
-
-## MCP e evidência
-
-Leituras são compartilhadas pelo MCP local e remoto. `genne_admin_gr_driver_directory` expõe o diretório global; `genne_admin_gr_drivers` continua carrier-scoped. Treinamento tem escrita remota com intenção/aprovação existente; as demais mutações GR da matriz são operações CLI com confirmação interativa. Mutações não são expostas pelo MCP stdio.
-
-Testes CLI exercitam endpoints, envelopes, cursor, papéis ativos, escopo forjado, propagação de 403 e ausência de escrita após confirmação recusada. Os testes HTTP usam servidor simulado: comprovam o cliente, não o enforcement de uma implantação real.
-
-Neste incremento, ACL/ownership foram conferidos no catálogo, guards, controllers e testes existentes do monorepo `442cc64c54cd7b08d38ab2b1f9da36bcd6236ed3`. A execução do controller carrier pelo runner Dev falhou antes dos testes: source snapshot indisponível em origin e `tools/dev-cli` ausente no checkout do runner. Em 2026-10-01, smoke read-only Admin em Prod passou para diretório global (`limit=1`), definitions, provider accounts e requests (`limit=1`). Não havia sessão Dev salva; smokes positivos driver/carrier/shipper, negações reais de ACL e testes Core permanecem pendentes. Não houve escrita externa GR, deploy ou release.