story: governança de mapeadores pelo admin (CRUD/promoção de TCL/XSL/XSLT)

[elson-vinicius-lopes]

Contexto

Correção ao vivo do dono durante a escrita de
docs/architecture/escopo-generico-txt-xml-e-acesso-por-papel-2026-08-14.md (§6.1, branch
fix/auditoria-gates-2026-08-14, commit 9494041, ainda não mergeada em develop): admin não
é "quem pode ver a transformação" (isso vira acesso de qualquer usuário — ver #93). admin é
especificamente gerenciamento dos artefatos de mapeamento já gerados (TCL, XSL/XSLT) —
CRUD/governança: editar, aprovar, revogar, promover um candidato gerado pela IA a "oficial".

Investigado em Controllers/MapperDatabaseController.cs: hoje só existem operações de leitura
sobre mapeadores (GET by-layout/{layoutGuid} linha 30, GET all linha 67, GET export/{id}
linha 112, GET by-input/{inputLayoutGuid} linha 158) e POST refresh-cache (linha 200,
manutenção de cache, já [Authorize(Roles = "operador")]). Não existe nenhuma operação de
escrita (criar/editar/excluir TCL/XSL) nem nenhum mecanismo de "promover candidato IA a
oficial" — o pathway IA (AiTransformationCandidateService) só gera e reporta status
(StatusConverged/StatusFailed), o candidato convergido não é gravado como mapeador
persistente no catálogo. O catálogo de mapeadores também não distingue hoje a origem
"criado pelo analista via Sysmiddle" vs. "promovido de um candidato IA".

O que falta

Esta issue é de rastreamento/design, não de implementação direta — o próprio doc de origem
recomenda tratar isso como novo trabalho de design (endpoints + modelo de dados), não como
"adicionar [Authorize(Roles=\"admin\")] em algo que já existe" (porque nada existe ainda).

Escopo a desenhar por @lp-architect antes de ir para @lp-backend-dev/@lp-parser-llm:

• Endpoint(s) de escrita sobre mapeador: editar TCL/XSL de um mapeador existente (admin)
• Endpoint de promoção: candidato IA (StatusConverged) → mapeador oficial do catálogo (admin)
• Endpoint de revogação/desativação de mapeador do catálogo (admin)
• Modelo de dados: representar a origem do mapeador (analista vs. IA promovida) — hoje não existe
  essa distinção no catálogo

Critério de aceite

• @lp-architect produz desenho (endpoints + modelo de dados) para as 3 operações de escrita
  acima, cobrindo pelo menos: contrato de request/response, onde a distinção de origem do
  mapeador é persistida, e como AiCandidateStore/candidato convergido vira insumo do
  endpoint de promoção
• Desenho aprovado pelo dono antes de abrir issue(s) de implementação subsequentes

Dono natural

@lp-architect (próximo passo é desenhar, não codar ainda) → @lp-backend-dev/@lp-parser-llm
na implementação subsequente.

Origem

docs/architecture/escopo-generico-txt-xml-e-acesso-por-papel-2026-08-14.md §6.1 e §9 (branch
fix/auditoria-gates-2026-08-14, commit 9494041).

[elson-vinicius-lopes]

Handoff do consumidor LayoutParserReact — Slice 7

O front já exibe prontidão técnica da release a partir de RequiredGatesPassed, mas mantém todas as mutações bloqueadas. Para integrar governança sem reproduzir regra no navegador, o contrato da API precisa informar:

1. estados e ambientes canônicos;
2. transições permitidas para a identidade atual (RBAC autoritativo);
3. rota/payload de transição com justificativa, idempotência e ETag/If-Match;
4. evento/auditoria por metadados, sem conteúdo fiscal;
5. rollback como promoção de versão anterior e imutabilidade de Published;
6. rejeição categórica de Sysmiddle nas rotas genéricas.

Consumidor: LayoutParserReact#198/#206. O front não registrará endpoints propostos nem habilitará ações até o handoff de implementação/OpenAPI existir.

[elson-vinicius-lopes]

Governança de mapeadores pelo admin (CRUD/promoção de TCL/XSL/XSLT) entregue no Slice 7, mergeada via PR #248 (feat(fiscal): Slice 7 - governanca/publicacao de MappingRelease (issue #94)), 2026-09-01.

[elson-vinicius-lopes]

Aceite do contrato pelo front (LayoutParserReact)\n\nCorreção do handoff anterior: o PR #248 foi identificado após a primeira leitura e o contrato já foi integrado no PR LayoutParserReact#211.\n\nO front consome �pprove, publish e

ollback, os novos status e o RBAC por papel do workspace. O E2E sintético percorre est_passed → approved → published → deprecated em desktop/mobile.\n\nFollow-ups contratuais preservados, sem bloquear o consumo atual: o GET completo de release omite os metadados de governança presentes nas respostas parciais; não há If-Match, leitura de MappingTransition nem �llowedTransitions. O piloto FIAT real continua separado da fixture sintética.\n\nRetorno explícito do consumidor: contrato dos três endpoints aceito e integrado, com essas limitações documentadas.