Compliance gerado do contrato (IA)

Objetivo: ao finalizar as assinaturas, o contrato nasce com um compliance próprio gerado por IA a partir das suas cláusulas de obrigatoriedade. Reusa integralmente o motor de Compliance existente (fluxos, etapas, validadores, agendamento, vínculo por prestador, instâncias mensais), ou seja, não cria sistema paralelo. Substitui a antiga ideia de "Obrigações", que foi descontinuada.

Premissas

• Não reinventa o Compliance: o compliance nativo é um ComplianceFlow comum, com origin = CONTRACT.
• A geração é 100% IA. Sem IA no plano, o contrato não ganha compliance automático.
• A pessoa pode editar e refinar os steps depois; o grosso vem da IA.

Gate por plano (AiExecutionSurface)

A automação em background só roda no nível WRITE_API do AiExecutionSurface. Isso é representado no produto por três features de plano (grupo ai):

Feature (PlanFeature.code)	Surface	Capacidade
ai_read	READ	Agente em consulta/leitura
ai_guided	GUIDED	Agente que conduz ações na interface
ai_write_api	WRITE_API	Automação em background e escrita via API; destrava a geração do compliance do contrato

O gate é subscriptionService.companyHasFeature(companyId, 'ai_write_api'). Sem essa feature, a geração é ignorada silenciosamente.

Modelo de dados (aditivo)

• ContractCompliance (contract_compliances): vínculo N:N entre Contract e ComplianceFlow. FKs onDelete: Cascade para os dois lados. Campo locked (true = nativo, não desvinculável). Unique (contractId, complianceFlowId). Soft-delete.
• ComplianceFlow.origin (ComplianceFlowOrigin: MANUAL | CONTRACT). O nativo é CONTRACT e não aparece na lista global (GET /compliance-flows filtra origin = MANUAL).

Um contrato pode ter N compliances: o nativo (locked) + globais adicionados.

Gatilho

Finalização das assinaturas (SIGNING → COMPLETED), nos dois caminhos:

• signing.service.maybeAutoComplete (auto, último signatário).
• contract.service.complete (conclusão manual).

Ambos chamam contractComplianceService.triggerGenerationInBackground(contractId, actorUserId?): fire-and-forget, não bloqueia a resposta de assinatura.

Fluxo de geração

1. Carrega o contrato (companyId, partes, cláusulas).
2. Gate ai_write_api; idempotência (já existe compliance locked?); exige texto de cláusulas (ContractReviewItem.htmlContent).
3. Chama a ai-api POST /ai/v1/compliance/generate-from-contract ({ contractText, contractKind? }) → { flow } no schema de CreateComplianceFlowDto.
4. Persiste o ComplianceFlow (origin = CONTRACT, status = active) reusando o repository de compliance-flows.
5. Cria o vínculo ContractCompliance (locked = true).
6. Anexa aos prestadores do contrato (ProviderComplianceFlow), entrando no motor de execução atual.

Contratos

Product API (nest-api)

GET    /contracts/{contractId}/compliances           # nativo (locked) + globais
POST   /contracts/{contractId}/compliances           # vincular fluxo global { complianceFlowId }
DELETE /contracts/{contractId}/compliances/{flowId}  # desvincular global (422/400 se locked)

IA (ai-api)

POST /ai/v1/compliance/generate-from-contract  # internal, server-to-server (JWT curto + x-company-id)
  body: { contractText, contractKind? }
  resp: { flow: <CreateComplianceFlowDto>, usage }

A IA gera steps idênticos ao schema atual (stepType documents|platformData|invoice, agendamento, documentos, dependência). Validadores ficam vazios para atribuição humana.

Regras de negócio

• O compliance nativo é locked: não pode ser desvinculado/excluído; só os steps são editáveis (mesmo esquema do compliance flow).
• Globais podem ser adicionados e removidos por contrato e por prestador, como hoje.
• Geração é idempotente: um contrato não regenera o nativo se já tiver um.

Erros conhecidos

ID	Erro	Mitigação
ERR-001	IA indisponível na finalização	Fire-and-forget com log; não quebra a conclusão. Reprocessável.
ERR-002	Empresa sem ai_write_api	Geração ignorada silenciosamente
ERR-003	Contrato sem texto de cláusulas	Geração ignorada (nada a extrair)
ERR-004	Tentativa de remover o nativo	400/422 (locked)

Compliance

LGPD: o compliance nativo herda a governança do Compliance. Auditoria via histórico do contrato na conclusão.