feat(api,web): fundação de Documentos + EDEN Parceiros/Assinante com login real

Continuação da leva "pelo menos mais 20 etapas" — 2 subagentes em paralelo.

## Documents (apps/api/src/documents/ + migration documents)

Metade "templates + geração" do eden.md módulo 4 (§1.1-1.3): document_templates,
document_template_versions (ciclo draft→publish, no máximo 1 rascunho por
template via índice único parcial, versão publicada imutável), document_generations
(idempotente por (template_version_id, origem), CHECK de origem única). Motor de
merge de variáveis ({{chave}}→valor, nunca lança exceção) como função pura
testável. A metade de Assinatura Eletrônica (envelopes, signatários, OTP,
cadeia de auditoria hash-chain — eden.md §1.4-1.9/§5-7, 9 tabelas satélite)
fica deliberadamente fora — grande e sensível demais para dividir espaço
com esta leva, fica para uma leva própria. PDF real via Chromium também
deferido; document_generations grava rendered_html, pdf_* ficam NULL.

## EDEN Parceiros / EDEN Assinante (apps/reseller-web, apps/subscriber-web)

Replicam o shell autenticado do core-web (leva anterior): login real com
suporte a MFA, sessão, AppShell do Design System — trocando só
applicationKey ("reseller"/"subscriber"), título e chave de localStorage
da sessão. As duas telas "Bootstrap da Fase 1" saem de circulação.

Testado ao vivo contra os containers reais: ciclo completo de template
(criar→draft→409 no segundo draft→editar→publicar→gerar documento com
merge de variáveis funcionando→regeneração idempotente reaproveita o
registro), e login via /v1/auth/login com applicationKey "reseller"/
"subscriber" retornando tokens válidos nos 2 portais reconstruídos.
pnpm turbo run typecheck build (28/28), pnpm --filter @eden/api test
(30/30, sem regressão), trilha de auditoria conferida no Postgres.

Claude-Session: https://claude.ai/code/session_01BcWWuKfykGtUweXmHD6cKx

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/api/src/app.module.ts

@@ -19,6 +19,7 @@ import { SupportModule } from "./support/support.module.js";
 import { HrTimeclockModule } from "./hr-timeclock/hr-timeclock.module.js";
 import { FiscalModule } from "./fiscal/fiscal.module.js";
 import { BillingModule } from "./billing/billing.module.js";
+import { DocumentsModule } from "./documents/documents.module.js";
 
 @Module({
   imports: [
@@ -41,6 +42,7 @@ import { BillingModule } from "./billing/billing.module.js";
     HrTimeclockModule,
     FiscalModule,
     BillingModule,
+    DocumentsModule,
   ],
   controllers: [HealthController],
 })

apps/api/src/documents/documents.controller.ts

@@ -0,0 +1,77 @@
+import { Body, Controller, Get, Param, Patch, Post, Query, UseGuards } from "@nestjs/common";
+import { ApiBearerAuth, ApiTags } from "@nestjs/swagger";
+import { DocumentsService } from "./documents.service";
+import { CreateDocumentTemplateDto } from "./dto/create-document-template.dto";
+import { UpdateDraftDto } from "./dto/update-draft.dto";
+import { CreateGenerationDto } from "./dto/create-generation.dto";
+import { JwtAuthGuard } from "../auth/jwt-auth.guard";
+import { PermissionGuard } from "../auth/permission.guard";
+import { RequirePermission } from "../auth/decorators/require-permission.decorator";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+import type { EdenAuthenticatedUser } from "../auth/jwt-auth.guard";
+
+/**
+ * Templates de documento + geração (eden.md §4, seções 1.1-1.3). Só a
+ * metade "templates + geração" do módulo 4 — Assinatura Eletrônica
+ * (seções 1.4-1.9) fica para uma leva dedicada futura (ver o comentário
+ * no topo da migration PENDING_documents.cjs).
+ */
+@ApiTags("documents")
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard, PermissionGuard)
+@Controller("v1/documents")
+export class DocumentsController {
+  constructor(private readonly documents: DocumentsService) {}
+
+  @Get("templates")
+  @RequirePermission("documents", "view")
+  listTemplates(@Query("docGroup") docGroup?: "cliente" | "revenda") {
+    return this.documents.listTemplates(docGroup);
+  }
+
+  @Post("templates")
+  @RequirePermission("documents", "edit")
+  createTemplate(@Body() dto: CreateDocumentTemplateDto, @CurrentUser() user: EdenAuthenticatedUser) {
+    return this.documents.createTemplate(dto, user);
+  }
+
+  @Get("templates/:id")
+  @RequirePermission("documents", "view")
+  getTemplate(@Param("id") id: string) {
+    return this.documents.getTemplate(id);
+  }
+
+  @Post("templates/:id/draft")
+  @RequirePermission("documents", "edit")
+  createDraft(@Param("id") id: string, @CurrentUser() user: EdenAuthenticatedUser) {
+    return this.documents.createDraft(id, user);
+  }
+
+  @Patch("templates/:id/draft")
+  @RequirePermission("documents", "edit")
+  updateDraft(@Param("id") id: string, @Body() dto: UpdateDraftDto, @CurrentUser() user: EdenAuthenticatedUser) {
+    return this.documents.updateDraft(id, dto, user);
+  }
+
+  @Post("templates/:id/publish")
+  @RequirePermission("documents", "edit")
+  publish(@Param("id") id: string, @CurrentUser() user: EdenAuthenticatedUser) {
+    return this.documents.publish(id, user);
+  }
+
+  @Post("generations")
+  @RequirePermission("documents", "edit")
+  createGeneration(@Body() dto: CreateGenerationDto, @CurrentUser() user: EdenAuthenticatedUser) {
+    return this.documents.createGeneration(dto, user);
+  }
+
+  @Get("generations")
+  @RequirePermission("documents", "view")
+  listGenerations(
+    @Query("templateId") templateId?: string,
+    @Query("clientRegistrationId") clientRegistrationId?: string,
+    @Query("resellerId") resellerId?: string,
+  ) {
+    return this.documents.listGenerations({ templateId, clientRegistrationId, resellerId });
+  }
+}

apps/api/src/documents/documents.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { DocumentsController } from "./documents.controller";
+import { DocumentsService } from "./documents.service";
+
+@Module({
+  imports: [AuthModule],
+  controllers: [DocumentsController],
+  providers: [DocumentsService],
+  exports: [DocumentsService],
+})
+export class DocumentsModule {}

apps/api/src/documents/documents.service.ts

@@ -0,0 +1,186 @@
+import { BadRequestException, ConflictException, Injectable, NotFoundException } from "@nestjs/common";
+import { auditRepo, documentsRepo } from "@eden/database";
+import type { EdenAuthenticatedUser } from "../auth/jwt-auth.guard";
+import { mergeVariables } from "./merge-engine";
+import { renderEditorContentToHtml, resolveSourceText } from "./editor-content-renderer";
+import type { CreateDocumentTemplateDto } from "./dto/create-document-template.dto";
+import type { UpdateDraftDto } from "./dto/update-draft.dto";
+import type { CreateGenerationDto } from "./dto/create-generation.dto";
+
+const { TemplateNotFoundError, TemplateKeyConflictError, DraftAlreadyExistsError, DraftNotFoundError } =
+  documentsRepo;
+
+/**
+ * Templates de documento + geração — eden.md §4, seções 1.1-1.3. Só a
+ * metade "templates + geração" do módulo 4; Assinatura Eletrônica
+ * (seções 1.4-1.9) fica para uma leva dedicada futura (ver o comentário
+ * no topo da migration PENDING_documents.cjs). Endpoint-level
+ * authorization (@RequirePermission) lives on DocumentsController — this
+ * service assumes the caller already holds the resource+action it needs.
+ */
+@Injectable()
+export class DocumentsService {
+  async listTemplates(docGroup?: "cliente" | "revenda") {
+    return documentsRepo.listTemplates(docGroup ? { docGroup } : {});
+  }
+
+  async getTemplate(id: string) {
+    const template = await documentsRepo.getTemplateWithVersions(id);
+    if (!template) throw new NotFoundException("Template de documento não encontrado");
+    return template;
+  }
+
+  async createTemplate(dto: CreateDocumentTemplateDto, user: EdenAuthenticatedUser) {
+    try {
+      const template = await documentsRepo.createTemplate({
+        key: dto.key,
+        name: dto.name,
+        docGroup: dto.docGroup,
+        createdBy: user.id,
+      });
+
+      await auditRepo.appendAuditEvent({
+        actorType: "user",
+        actorId: user.id,
+        action: "document_template.created",
+        resourceType: "document_template",
+        resourceId: template.id,
+        metadata: { key: template.key, docGroup: template.doc_group },
+      });
+
+      return template;
+    } catch (err) {
+      if (err instanceof TemplateKeyConflictError) {
+        throw new ConflictException(`A chave '${dto.key}' já está em uso por outro template`);
+      }
+      throw err;
+    }
+  }
+
+  async createDraft(templateId: string, user: EdenAuthenticatedUser) {
+    try {
+      const draft = await documentsRepo.createDraft(templateId, user.id, renderEditorContentToHtml);
+
+      await auditRepo.appendAuditEvent({
+        actorType: "user",
+        actorId: user.id,
+        action: "document_template.draft_created",
+        resourceType: "document_template_version",
+        resourceId: draft.id,
+        metadata: { templateId, version: draft.version },
+      });
+
+      return draft;
+    } catch (err) {
+      if (err instanceof TemplateNotFoundError) throw new NotFoundException("Template de documento não encontrado");
+      if (err instanceof DraftAlreadyExistsError) {
+        throw new ConflictException("Este template já possui um rascunho em andamento");
+      }
+      throw err;
+    }
+  }
+
+  async updateDraft(templateId: string, dto: UpdateDraftDto, user: EdenAuthenticatedUser) {
+    try {
+      const updated = await documentsRepo.updateDraft(
+        templateId,
+        { editorContent: dto.editorContent, cssContent: dto.cssContent, pageConfig: dto.pageConfig },
+        renderEditorContentToHtml,
+      );
+
+      await auditRepo.appendAuditEvent({
+        actorType: "user",
+        actorId: user.id,
+        action: "document_template.draft_updated",
+        resourceType: "document_template_version",
+        resourceId: updated.id,
+        metadata: { templateId },
+      });
+
+      return updated;
+    } catch (err) {
+      if (err instanceof TemplateNotFoundError) throw new NotFoundException("Template de documento não encontrado");
+      if (err instanceof DraftNotFoundError) {
+        throw new NotFoundException("Este template não possui um rascunho para editar");
+      }
+      throw err;
+    }
+  }
+
+  async publish(templateId: string, user: EdenAuthenticatedUser) {
+    try {
+      const published = await documentsRepo.publishDraft(templateId, user.id);
+
+      await auditRepo.appendAuditEvent({
+        actorType: "user",
+        actorId: user.id,
+        action: "document_template.published",
+        resourceType: "document_template_version",
+        resourceId: published.id,
+        metadata: { templateId, version: published.version },
+      });
+
+      return published;
+    } catch (err) {
+      if (err instanceof TemplateNotFoundError) throw new NotFoundException("Template de documento não encontrado");
+      if (err instanceof DraftNotFoundError) {
+        throw new ConflictException("Este template não possui um rascunho para publicar");
+      }
+      throw err;
+    }
+  }
+
+  async createGeneration(dto: CreateGenerationDto, user: EdenAuthenticatedUser) {
+    const hasClient = dto.clientRegistrationId != null;
+    const hasReseller = dto.resellerId != null;
+    if (hasClient === hasReseller) {
+      throw new BadRequestException("Informe exatamente uma origem: clientRegistrationId OU resellerId");
+    }
+
+    let published: Awaited<ReturnType<typeof documentsRepo.getPublishedVersionForTemplate>>;
+    try {
+      published = await documentsRepo.getPublishedVersionForTemplate(dto.templateId);
+    } catch (err) {
+      if (err instanceof TemplateNotFoundError) throw new NotFoundException("Template de documento não encontrado");
+      throw err;
+    }
+    if (!published) {
+      throw new NotFoundException("Este template ainda não tem uma versão publicada");
+    }
+
+    // Fluxo simplificado desta leva (eden.md §4 descreve o pipeline
+    // completo com renderToHtml/sanitizeDocumentHtml/Chromium/S3): roda o
+    // merge engine sobre o texto extraído de editor_content.plainText da
+    // versão publicada — sem renderização real de PDF (ver comentário na
+    // migration e no repositório documents.ts).
+    const sourceText = resolveSourceText(published.version.editor_content);
+    const { resolved, missingVariables } = mergeVariables(sourceText, dto.context ?? {});
+
+    const { generation, deduped } = await documentsRepo.createGenerationIdempotent({
+      templateId: dto.templateId,
+      templateVersionId: published.version.id,
+      clientRegistrationId: dto.clientRegistrationId ?? null,
+      resellerId: dto.resellerId ?? null,
+      renderContext: dto.context ?? {},
+      renderedHtml: resolved,
+      generatedBy: user.id,
+    });
+
+    if (!deduped) {
+      await auditRepo.appendAuditEvent({
+        actorType: "user",
+        actorId: user.id,
+        action: "document_generation.created",
+        resourceType: "document_generation",
+        resourceId: generation.id,
+        metadata: { templateId: dto.templateId, templateVersionId: published.version.id, missingVariables },
+      });
+    }
+
+    return { ...generation, missingVariables, deduped };
+  }
+
+  async listGenerations(filter: { templateId?: string; clientRegistrationId?: string; resellerId?: string }) {
+    return documentsRepo.listGenerations(filter);
+  }
+}

apps/api/src/documents/dto/create-document-template.dto.ts

@@ -0,0 +1,18 @@
+import { IsIn, IsString, Matches, MaxLength } from "class-validator";
+
+export class CreateDocumentTemplateDto {
+  /** Identificador estável fixado pelo sistema (eden.md §1.1) — só ASCII minúsculo/underscore, nunca editável depois de criado nesta leva. */
+  @IsString()
+  @Matches(/^[a-z][a-z0-9_]*$/, {
+    message: "key deve começar com letra minúscula e conter apenas letras minúsculas, números e underscore",
+  })
+  @MaxLength(100)
+  key!: string;
+
+  @IsString()
+  @MaxLength(200)
+  name!: string;
+
+  @IsIn(["cliente", "revenda"])
+  docGroup!: "cliente" | "revenda";
+}

apps/api/src/documents/dto/create-generation.dto.ts

@@ -0,0 +1,19 @@
+import { IsObject, IsOptional, IsUUID } from "class-validator";
+
+/**
+ * POST /v1/documents/generations body (eden.md §1.3, simplified for this
+ * leva). Exactly one of clientRegistrationId/resellerId is required —
+ * enforced in DocumentsService (mirrors the DB CHECK
+ * chk_document_generations_one_source), not here, since class-validator
+ * doesn't cleanly express an XOR across two optional fields.
+ */
+export class CreateGenerationDto {
+  @IsUUID() templateId!: string;
+
+  @IsOptional() @IsUUID() clientRegistrationId?: string;
+
+  @IsOptional() @IsUUID() resellerId?: string;
+
+  /** {chave: valor} usado pelo merge engine (merge-engine.ts) para resolver `{{variavel}}`. */
+  @IsObject() context!: Record<string, string>;
+}

apps/api/src/documents/dto/update-draft.dto.ts

@@ -0,0 +1,14 @@
+import { IsObject, IsOptional, IsString } from "class-validator";
+
+/**
+ * PATCH .../draft body (eden.md §1.2 step 2) — every field optional and
+ * independently omit-able; an omitted field keeps the draft's current
+ * value (see documents.ts's updateDraft `patch.field !== undefined`
+ * semantics). `editorContent` is accepted as generic JSONB — this leva
+ * does not validate the Tiptap tree shape.
+ */
+export class UpdateDraftDto {
+  @IsOptional() @IsObject() editorContent?: Record<string, unknown>;
+  @IsOptional() @IsString() cssContent?: string;
+  @IsOptional() @IsObject() pageConfig?: Record<string, unknown>;
+}

apps/api/src/documents/editor-content-renderer.ts

@@ -0,0 +1,62 @@
+/**
+ * Stand-in SIMPLIFICADO para o `renderToHtml()`/`renderEditorContent.js`
+ * do legado (eden.md §2.2) — aquele renderer conhece toda a árvore
+ * Tiptap (paragraph/heading/table/mergeField/conditional/...) e escapa
+ * HTML nó a nó. Esta leva de backend não tem o editor visual real ainda
+ * (`editor_content` é aceito como JSONB genérico, não validado), então
+ * em vez de reimplementar aquele renderer pela metade, este módulo faz
+ * só o mínimo necessário para `document_template_versions.html_content`
+ * nunca ficar dessincronizado do `editor_content` salvo:
+ *
+ *   - se `editor_content` tiver uma propriedade de nível raiz
+ *     `plainText` (string), ela é usada como o texto do documento;
+ *   - caso contrário, um placeholder determinístico é usado.
+ *
+ * NÃO deve ser confundido com o merge-engine (merge-engine.ts), que roda
+ * DEPOIS, sobre o texto aqui extraído, para resolver `{{variavel}}`.
+ */
+
+export const EDITOR_CONTENT_PLACEHOLDER_TEXT =
+  "[Conteúdo gerado pelo editor visual — renderização completa pendente de implementação]";
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Returns `editor_content.plainText` when present as a root-level string
+ * property, or `null` otherwise. Never throws on a malformed/unexpected
+ * shape — this leva doesn't validate the Tiptap tree at all (that's the
+ * visual editor's job once it exists).
+ */
+export function extractPlainText(editorContent: unknown): string | null {
+  if (
+    editorContent !== null &&
+    typeof editorContent === "object" &&
+    "plainText" in (editorContent as Record<string, unknown>) &&
+    typeof (editorContent as Record<string, unknown>).plainText === "string"
+  ) {
+    return (editorContent as { plainText: string }).plainText;
+  }
+  return null;
+}
+
+/**
+ * `extractPlainText` with the deterministic placeholder as fallback —
+ * this is the actual text fed to the merge engine at generation time
+ * (documents.service.ts), never `null`/empty on that path.
+ */
+export function resolveSourceText(editorContent: unknown): string {
+  const plainText = extractPlainText(editorContent);
+  return plainText && plainText.length > 0 ? plainText : EDITOR_CONTENT_PLACEHOLDER_TEXT;
+}
+
+/** Recomputes `document_template_versions.html_content` (eden.md §1.2 step 2). */
+export function renderEditorContentToHtml(editorContent: unknown): string {
+  return `<p>${escapeHtml(resolveSourceText(editorContent))}</p>`;
+}

apps/api/src/documents/merge-engine.ts

@@ -0,0 +1,49 @@
+/**
+ * Motor de merge de variáveis — versão SIMPLIFICADA para esta leva,
+ * inspirada no `resolveDocument()` do legado (eden.md §3.2), mas
+ * operando sobre TEXTO PURO com placeholders `{{variavel}}` em vez da
+ * árvore Tiptap completa. A árvore Tiptap real (nós `mergeField`,
+ * `conditional`, `tableRow.attrs.repeat`, catálogo de variáveis
+ * `VARIABLE_CATALOG` com formatação por tipo — eden.md §2.2, §3.1, §3.3,
+ * §3.4) fica para quando o editor visual real existir; não é
+ * reimplementada aqui.
+ *
+ * Pura e sem I/O — testável isoladamente (ver
+ * apps/api/test/merge-engine.spec.ts). Diferença deliberada em relação
+ * ao motor completo do legado: aquele lança `MISSING_REQUIRED_FIELDS`/
+ * `UNRESOLVED_VARIABLES` (HTTP 422) e bloqueia a geração; este NUNCA
+ * lança exceção — variáveis ausentes do contexto são substituídas por
+ * string vazia e apenas reportadas em `missingVariables` (deduplicadas,
+ * na ordem da primeira ocorrência). O chamador decide o que fazer com
+ * elas (bloquear, avisar, etc.); o motor não decide isso sozinho.
+ */
+
+export interface MergeResult {
+  /** Texto com todo `{{variavel}}` substituído — nunca sobra placeholder pendente, mesmo quando ausente do contexto (vira string vazia). */
+  resolved: string;
+  /** Chaves referenciadas no texto mas ausentes de `context`, deduplicadas, na ordem da primeira ocorrência. */
+  missingVariables: string[];
+}
+
+// Mesma sintaxe de chave do catálogo legado (eden.md §3.1): namespace.campo,
+// ex. "cliente.razao_social". Espaços em volta da chave são tolerados
+// ("{{ cliente.razao_social }}") e ignorados.
+const MERGE_FIELD_PATTERN = /\{\{\s*([A-Za-z0-9_.]+)\s*\}\}/g;
+
+export function mergeVariables(text: string, context: Record<string, string>): MergeResult {
+  const missingVariables: string[] = [];
+  const seenMissing = new Set<string>();
+
+  const resolved = text.replace(MERGE_FIELD_PATTERN, (_match: string, key: string) => {
+    if (Object.prototype.hasOwnProperty.call(context, key)) {
+      return context[key] ?? "";
+    }
+    if (!seenMissing.has(key)) {
+      seenMissing.add(key);
+      missingVariables.push(key);
+    }
+    return "";
+  });
+
+  return { resolved, missingVariables };
+}