[PBI] 203a — Editor de TCL/XSL/XSLT com RBAC

[elson-vinicius-lopes]

Contexto

Sub-task de #203 (quebra de escopo pós-FAIL de QA). Ver comentário de quebra em #203.

Escopo

Componente de edição real de TCL/XSL/XSLT (não textarea solto) como caminho principal de autoria, com:

• gating de ações por roles da sessão (hoje o RBAC é decorativo no front — precisa virar enforcement real, ainda que a validação final continue sendo da API);
• persistência via endpoint de mutação de artefato (ainda não existe na API).

Critério de aceite

• Given um usuário sem role de Mapper autorizado, When abre o Mapping Studio, Then nenhuma ação de edição é exposta nem executável.
• Given um usuário autorizado, When edita e salva, Then a alteração persiste via novo endpoint e o resultado aparece refletido no diff/histórico.
• Editor aceita apenas TCL/XSL/XSLT (validação de tipo de conteúdo/extensão).

Dependência (bloqueio)

BLOQUEADO até a API (LayoutParserApi) expor endpoint de mutação de artefato + contrato de RBAC de autoria. Referenciar LayoutParserApi#94/#103 conforme já apontado no PBI pai #203.

Relação

Filha de #203 (Epic). Pré-requisito de #203d. Prioridade sugerida: segunda prioridade ("big rock" depois de #203e), mas só pode iniciar após desbloqueio de API.

[elson-vinicius-lopes]

Cross-check do contrato #226/#198 contra o estado da API

Documento completo: docs/architecture/cross-check-contratos-226-198-react-2026-09-10.md
(LayoutParserApi PR #375). Resumo pergunta a pergunta abaixo.

Achado que domina o #226

Hoje ninguém edita TCL/XSLT como texto do lado da API. O humano opera sobre regras
estruturadas (MappingDraftRule: SourceRefs/TargetRefs/Operation/ConditionsJson/
TransformationsJson). O TCL/XSLT só nasce na compilação determinística
(MappingDraftRuleTranspiler, via POST .../compile) e, a partir do publish, fica
imutável. Não existe nenhum caminho de mutação de conteúdo de artefato. O
PATCH .../mapping-drafts/{draftId}/artifacts/{engine} proposto por vocês é capacidade
inteiramente nova.

#226 — Editor de TCL/XSL/XSLT com RBAC

Item	Veredito	Detalhe
226.1 endpoint PATCH .../artifacts/{engine}	NÃO EXISTE	Capacidade nova: endpoint + store + validação de sintaxe + decidir o vínculo artefato↔regras. O modelo de vocês casa: engine tcl|xslt, baseArtifactHash ≈ MappingReleaseArtifact.Hash, justification tem precedente.
226.2 edição gera revisão de draft ou nova release?	nenhum dos dois existe	O modelo favorece nova MappingRelease derivada: draft não tem versionamento (só as regras têm ROWVERSION + MappingDraftRuleDecision append-only); release já é unidade de versão idempotente por (DraftId, RulesSnapshotHash). Casa com a #229 (edição manual = revisão candidata, não sobrescreve release). Precisa de um mini-ADR nosso pra fechar.
226.3 RBAC de autoria	PARCIAL	Os 6 papéis existem idênticos (WorkspaceRole: owner/fiscal_admin/mapper/reviewer/operator/viewer). [RequireWorkspaceRole] funciona (404 sem membership, 403 papel insuficiente). Matriz codificada só em governança: approve=reviewer|fiscal_admin, publish/rollback=fiscal_admin|owner, List=todos. Draft/compile/edição-de-regra NÃO checam papel — só membership. A suposição de vocês (mapper autor + fiscal_admin/owner override) é compatível mas ainda não está codificada.
226.4 contrato de erro	PARCIAL	200+eTag, 412 com {current}, 428, 400, 422, 403, 404 já são emitidos com shape idêntico no PATCH .../rules/{ruleId}. Só falta o endpoint onde plugar. Exceção: 401 não existe por design — usem 404 fail-closed para "não autenticado" (a API não distingue não-autenticado de não-encontrado na fronteira).

#198 — Catálogo e ciclo de vida

Item	Veredito	Detalhe
198.1 transição archived	NÃO EXISTE endpoint	Status declarado no enum mas sem archive/deprecate manual.
198.2 diff estruturado por schema/destino	PARCIAL	CanonicalDiffer já produz estruturado (NodeDiff: Kind/XPath/Expected/Actual) e já é exposto em testRunSummary.divergences (MappingTestRunDivergence, enriquecido com RuleId + SourceRefs + Evidence). Faltam: diff release A × B e agregação por schema/destino (hoje é lista plana por XPath).
198.3 perfil fiscal (documentType/schemaVersion/operation/jurisdiction)	NÃO EXISTE	FiscalProject só tem Name; nada em draft/release; jurisdiction não existe em nenhum lugar do repo. Precisa FiscalProfile + migração no IdentityDatabase.
198.4 filtros status/draftId/environment no GET /mapping-releases	NÃO EXISTE	List aceita só page/pageSize; ListByWorkspaceAsync sem filtros. Implementação pequena e localizada.
198.5 "cobertura de destinos obrigatórios"	conceito NOVO	Não é o coveragePercent (esse é cobertura de teste dinâmica de um test-run). É estático: elementos obrigatórios do XSD alvo × TargetRefs das regras aceitas. Depende de 198.3.

Fecha só com documentação (sem código novo)

• 226.3 — a matriz de papéis atual (o que cada endpoint exige hoje).
• 226.4 — o vocabulário de erro + a regra "sem 401, usar 404 fail-closed".
• 198.2 — o shape do NodeDiff/divergences que já existe e vocês podem consumir já.

Sub-issues criadas na API (ordem de ataque)

1. Doc-only (@lp-doc) — RBAC atual + vocabulário de erro + shape do diff existente.
2. [PBI] Catálogo e ciclo de vida de mappings fiscais #198.4 filtros de listagem — P, sem dependência, primeiro.
3. [PBI] Catálogo e ciclo de vida de mappings fiscais #198.1 endpoint de arquivamento — P, independente.
4. [PBI] Catálogo e ciclo de vida de mappings fiscais #198.3 perfil fiscal — M, mini-ADR antes; pré-requisito do 198.5.
5. Épico [PBI] 203a — Editor de TCL/XSL/XSLT com RBAC #226 — 5a ADR de versionamento da edição manual → 5b endpoint PATCH + store → 5c validação de sintaxe TCL/XSLT.
6. [PBI] Catálogo e ciclo de vida de mappings fiscais #198.2b + [PBI] Catálogo e ciclo de vida de mappings fiscais #198.5 juntos — M, depois do 198.3 (mesmo parser de XSD alvo).

Ordem: 1 → 2,3 → 4 → 6 → 5 (em paralelo a partir de 5a). Números das issues no comentário a seguir.

Issues criadas na API

Ordem	Issue API	Cobre
1	LayoutParserApi#376	doc-only: RBAC atual + vocabulário de erro + shape do diff
2	LayoutParserApi#377	#198.4 — filtros status/draftId/environment no GET /mapping-releases
3	LayoutParserApi#378	#198.1 — endpoint de arquivamento/deprecação manual
4	LayoutParserApi#379	#198.3 — perfil fiscal (mini-ADR + FiscalProfile + migração)
6	LayoutParserApi#380	#198.2b (diff release A×B + agregação por schema) + #198.5 (cobertura de obrigatórios)
5	LayoutParserApi#381	épico #226 — 5a ADR versionamento → 5b endpoint PATCH+store → 5c validação de sintaxe

Priorização final é do dono da API; a ordem acima é recomendação do cross-check.

[elson-vinicius-lopes]

Cross-check #226/#198 — pacote completo em produção (2026-09-15)

As quatro frentes do cross-check que ainda dependiam de implementação estão prontas,
mergeadas e em produção.

1. Perfil fiscal (#379 / #198.3)

FiscalProfile (documentType/schemaVersion/operation/jurisdiction) em 2 camadas:

• MappingDraft.FiscalProfile — cópia de trabalho, mutável.
• MappingRelease.FiscalProfile — snapshot congelado na compilação, imutável.

PUT /api/workspaces/{workspaceId}/mapping-drafts/{draftId}/fiscal-profile
Body: { documentType, schemaVersion, operation, jurisdiction }

200 grava (idempotente, não retroage releases existentes) · 422 por regra de validação
específica (documentType sem XSD configurado, schemaVersion não instalada, etc.) · 404
sem identidade/membership.

fiscalProfile + resolvedXsd (derivado, eco de XsdValidation:DocumentTypes) agora saem
em todo GET de draft e de release. RBAC: mapper/fiscal_admin/owner.

2. Editor de artefato TCL/XSL/XSLT com edição manual (#381 / #226)

PATCH /api/workspaces/{workspaceId}/mapping-drafts/{draftId}/artifacts/{engine}
Headers: If-Match: "<baseArtifactHash>"
Body: { content, justification }

• Edição manual = nova MappingRelease derivada (ArtifactSource=manual_edit,
  DerivedFromReleaseId, ManualEditReason, ManuallyEditedArtifactKinds) — nunca muta a
  release-base, nunca sobrescreve a publicada.
• Concorrência otimista igual ao PATCH .../rules/{ruleId}: 200+eTag / 412 com
  {current} / 428 sem If-Match / 400 header malformado / 422 sintaxe inválida
  (XSLT validado de verdade via XslCompiledTransform; TCL por heurística — não é parser
  real, documentado como tal).
• Percorre a mesma governança: test-runs → approve → publish, com re-aprovação
  obrigatória. Recompilar depois nunca sobrescreve a edição manual — as duas coexistem.
• RBAC: mapper/fiscal_admin/owner. Sem identidade → 404 (não 401 — fronteira não
  distingue os dois, por design).

3. Diff granular por ruleId (#367 / #228)

Achado: a maior parte já existia (CanonicalDiffer/MappingTestRunDivergence já
resolviam RuleId/SourceRefs/Evidence por divergência). Faltava só a agregação —
adicionado divergencesByRuleId no mesmo GET .../releases/{releaseId}, ao lado do
divergences plano que já existia (nada quebrado).

4. Diff release A×B + cobertura de obrigatórios (#380 / #198.2b + #198.5)

GET .../mapping-drafts/{draftId}/releases/diff?fromReleaseId=&toReleaseId=

Diff entre duas releases do mesmo draft, agregado por elemento do schema (não lista
plana). 404 se releases de workspace/draft diferentes; 422 se alguma não tem test-run
rodado ainda.

requiredCoverage: { percent, uncovered } novo no GET .../releases/{releaseId} —
cobertura estática (não confundir com coveragePercent, que é de test-run):
elementos/atributos obrigatórios do XSD alvo × TargetRefs das regras aceitas.
null quando a release não tem FiscalProfile.

Gap real fechado no caminho: o test-run agora persiste o XML real gerado
(ActualXml/ExpectedXml), não só as divergências — necessário pro diff A×B funcionar.

O que falta (não é código, é decisão/dado)

• Perfil fiscal com release já existente: grava sem retroagir (comportamento atual,
  default) — se quiserem travar com 409, é mudança de política, não de capacidade.
• RBAC de PATCH .../rules/{ruleId} e POST .../compile continua só por membership (sem
  gate de papel) — recomendação registrada no ADR do #381 pra estender o mesmo
  [RequireWorkspaceRole], mas não foi feita (fora do escopo, decisão de produto).
• Swagger/README ainda não atualizados pro conjunto novo — pedido a @lp-doc.

Tudo em master, deploy confirmado verde em 2026-09-15.

[elson-vinicius-lopes]

Atualização (2026-09-15) — dependência de API resolvida, item movido para Ready.

A LayoutParserApi reportou entrega em produção (deploy verde em master, 2026-09-15) do editor de artefato TCL/XSL/XSLT com edição manual (API#381), que corresponde exatamente ao bloqueio original desta PBI (LayoutParserApi#94/#103):

• Novo PATCH /api/workspaces/{workspaceId}/mapping-drafts/{draftId}/artifacts/{engine}, com If-Match/concorrência otimista no mesmo padrão do PATCH de rules já usado no front.
• Edição manual gera uma nova MappingRelease derivada (nunca muta a release-base) e passa pela mesma governança test-runs → approve → publish já existente.

Ressalva registrada pela própria API (não resolvida, é decisão de produto deles): RBAC de PATCH .../rules/{ruleId} e POST .../compile (e, por extensão, este novo PATCH de artifact) segue por membership apenas — sem gate de papel (mapper/fiscal_admin/owner). Está anotado no ADR deles como recomendação, não implementado. Ou seja, a parte "RBAC" do título desta PBI (203a) ainda não tem enforcement de papel garantido no backend.

Status: None → Ready. Endpoint existe e está consumível; falta o trabalho de front (editor de artefato, integração com o novo PATCH, fluxo de release derivada) — não fechar até UI/consumo implementado e validado.

[elson-vinicius-lopes]

Atualização — 2026-09-15

PR #255 (feat/fiscal-profile-manual-edit-diff-contract → develop) mergeado em 2026-09-15T16:26:45Z. Quality Gates, CodeQL e Dependency Review: SUCCESS. Workflow CI e Deploy Dev rodou com sucesso após o merge (deploy no ambiente development confirmado).

Escopo entregue no front: tipos + camada services para os 4 endpoints novos entregues pela API (perfil fiscal, editor de artefato manual com concorrência otimista, diff granular por ruleId, diff A×B + cobertura de obrigatórios). Implementado em duas rodadas — primeira rodada teve contract:check com FAIL, corrigido, segunda rodada passou com veredito PASS do @lp-qa.

Sem UI ainda — a UI para consumir esses contratos é entrega futura, não incluída neste PR.

Pendência de revalidação de contrato: 2 shapes (ResolvedXsdReference, MappingReleaseDiff*) não foram confirmados contra o MCP da API — o MCP ficou indisponível (CONNECTION_CLOSED) em várias tentativas durante a sessão. @lp-contract-qa precisa revalidar esses 2 shapes assim que o MCP estiver acessível.

Item não fecha ainda — falta UI e a revalidação de contrato pendente, além de promoção develop → main para produção.

[elson-vinicius-lopes]

Evidência de conclusão — Done

• UI entregue via cc46382 (feat(mapping-studio): UI para perfil fiscal, edição manual de artefato e diff A×B (#198/#226/#228)) e endurecida em c575448.
• PR feat(mapping-studio): UI para perfil fiscal, edição manual e diffs (#198/#226/#228) #256 (feat/fiscal-mapping-studio-ui → develop), merge commit d3919455e7876e70957abdf53f8da9b505255f37, 2026-09-15T18:34:30Z.
• Promovido a produção via PR Develop #257 (develop → main), merge commit e953af42268181b31c15a8e3fb907f81bd48e20f, 2026-09-15T18:55:06Z.
• Deployment de produção e953af4 (id 6466178132) com status success em 2026-09-15T18:55:10Z.

Escopo desta issue (editor de TCL/XSL/XSLT com RBAC) entregue como parte da UI do Mapping Studio. Status movido para Done no Project #3.