@hed-hog/core 0.0.399 → 0.0.401

package/src/message-template/message-template-admin.service.ts

@@ -0,0 +1,239 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  NotFoundException,
+  forwardRef,
+} from '@nestjs/common';
+import * as Handlebars from 'handlebars';
+
+import { UpdateMessageTemplateDTO } from './dto/update-message-template.dto';
+import {
+  DEFAULT_MESSAGE_LOCALE,
+  MessageTemplateService,
+} from './message-template.service';
+import {
+  MessageTemplateDefinition,
+  getMessageTemplateDefinition,
+  listMessageTemplateDefinitions,
+  listMessageTemplateModules,
+} from './message-template.registry';
+
+/** Uma linha da tela: o que o código declara, com o que o banco sobrescreveu. */
+export type MessageTemplateListItem = {
+  slug: string;
+  module: string;
+  name: Record<string, string>;
+  description: Record<string, string>;
+  /** O texto em vigor por locale — o editado quando existe, senão o padrão. */
+  body: Record<string, string>;
+  /** O texto padrão, para a tela poder mostrar o diff e restaurar. */
+  fallback: Record<string, string>;
+  variables: MessageTemplateDefinition['variables'];
+  is_active: boolean;
+  /** Há linha no banco? É o que acende o selo e habilita "restaurar padrão". */
+  customized: boolean;
+};
+
+/**
+ * O que a tela de Modelos de Mensagem faz.
+ *
+ * A listagem é o **registry**, não um `SELECT`: modelo declarado por uma library
+ * recém-instalada já aparece, sem migration nenhuma. O banco entra por cima,
+ * como override — é daí que vêm `is_active`, o corpo editado e o selo
+ * "personalizado".
+ *
+ * Não expõe create nem delete de modelo: cada um existe porque há código que o
+ * procura pelo slug. Criar pela tela geraria registro que nada lê; apagar
+ * derrubaria o texto sem ninguém entender por quê. O que a tela faz é editar o
+ * texto, ligar/desligar e restaurar o padrão.
+ */
+@Injectable()
+export class MessageTemplateAdminService {
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /** Os módulos que têm modelo registrado, para o agrupamento da tela. */
+  modules() {
+    return { data: listMessageTemplateModules() };
+  }
+
+  async list(moduleSlug?: string) {
+    const definitions = listMessageTemplateDefinitions(moduleSlug);
+
+    // Uma consulta para a lista inteira, e não uma por modelo: são poucas linhas
+    // e a tela pede todas de uma vez.
+    const rows = await (this.prisma as any).message_template.findMany({
+      where: { slug: { in: definitions.map((d) => d.slug) } },
+      include: {
+        message_template_locale: {
+          select: { body: true, locale: { select: { code: true } } },
+        },
+      },
+    });
+
+    const bySlug = new Map(rows.map((row: any) => [row.slug, row]));
+    const data = definitions.map((definition) =>
+      MessageTemplateAdminService.merge(definition, bySlug.get(definition.slug)),
+    );
+
+    return { data, total: data.length };
+  }
+
+  async get(slug: string): Promise<MessageTemplateListItem> {
+    const definition = getMessageTemplateDefinition(slug);
+
+    if (!definition) {
+      throw new NotFoundException(`Modelo de mensagem "${slug}" não encontrado.`);
+    }
+
+    const row = await (this.prisma as any).message_template.findUnique({
+      where: { slug },
+      include: {
+        message_template_locale: {
+          select: { body: true, locale: { select: { code: true } } },
+        },
+      },
+    });
+
+    return MessageTemplateAdminService.merge(definition, row);
+  }
+
+  /**
+   * Grava o texto editado. **Upsert**, porque a linha pode não existir ainda:
+   * ela nasce na primeira edição, e não no seed.
+   */
+  async update(slug: string, dto: UpdateMessageTemplateDTO) {
+    const definition = getMessageTemplateDefinition(slug);
+
+    if (!definition) {
+      throw new NotFoundException(`Modelo de mensagem "${slug}" não encontrado.`);
+    }
+
+    // Valida ANTES de gravar: aceitar um corpo que não compila deixaria a tela
+    // dizendo "salvo" enquanto o aviso sai com o texto padrão, sem explicação.
+    for (const [locale, body] of Object.entries(dto.locale ?? {})) {
+      if (body?.body != null) {
+        MessageTemplateAdminService.assertCompiles(locale, body.body);
+      }
+    }
+
+    const template = await (this.prisma as any).message_template.upsert({
+      where: { slug },
+      create: { slug, is_active: dto.is_active ?? true },
+      update: dto.is_active == null ? {} : { is_active: dto.is_active },
+    });
+
+    for (const [code, value] of Object.entries(dto.locale ?? {})) {
+      if (value?.body == null) continue;
+
+      const locale = await (this.prisma as any).locale.findFirst({
+        where: { code },
+        select: { id: true },
+      });
+
+      if (!locale) continue;
+
+      await (this.prisma as any).message_template_locale.upsert({
+        where: {
+          message_template_id_locale_id: {
+            message_template_id: template.id,
+            locale_id: locale.id,
+          },
+        },
+        create: {
+          message_template_id: template.id,
+          locale_id: locale.id,
+          body: value.body,
+        },
+        update: { body: value.body },
+      });
+    }
+
+    return this.get(slug);
+  }
+
+  /**
+   * Volta ao texto do código, apagando a linha.
+   *
+   * Apagar, e não copiar o padrão para dentro do banco: uma cópia congelaria o
+   * texto na versão de hoje, e a próxima melhoria que viesse por deploy não
+   * chegaria a quem restaurou.
+   */
+  async restore(slug: string) {
+    if (!getMessageTemplateDefinition(slug)) {
+      throw new NotFoundException(`Modelo de mensagem "${slug}" não encontrado.`);
+    }
+
+    await (this.prisma as any).message_template
+      .delete({ where: { slug } })
+      .catch(() => null);
+
+    return this.get(slug);
+  }
+
+  /**
+   * Renderiza um corpo qualquer com as amostras do modelo, sem tocar no banco.
+   *
+   * É a única forma de ver onde o texto quebra no balão antes de ele chegar ao
+   * grupo.
+   */
+  preview(slug: string, body: string) {
+    const definition = getMessageTemplateDefinition(slug);
+
+    if (!definition) {
+      throw new NotFoundException(`Modelo de mensagem "${slug}" não encontrado.`);
+    }
+
+    MessageTemplateAdminService.assertCompiles(DEFAULT_MESSAGE_LOCALE, body);
+
+    const samples = Object.fromEntries(
+      Object.entries(definition.variables).map(([key, spec]) => [key, spec.sample]),
+    );
+
+    return {
+      text: Handlebars.compile(body, { noEscape: true })(samples).trim(),
+    };
+  }
+
+  private static assertCompiles(locale: string, body: string) {
+    try {
+      Handlebars.compile(body, { noEscape: true })({});
+    } catch (error) {
+      throw new BadRequestException(
+        `O corpo em "${locale}" tem sintaxe inválida: ${
+          (error as Error)?.message ?? 'erro desconhecido'
+        }`,
+      );
+    }
+  }
+
+  /** Junta a declaração do código com o que o banco sobrescreveu. */
+  private static merge(
+    definition: MessageTemplateDefinition,
+    row: any,
+  ): MessageTemplateListItem {
+    const edited: Record<string, string> = {};
+
+    for (const locale of row?.message_template_locale ?? []) {
+      const code = locale.locale?.code;
+      const body = String(locale.body ?? '').trim();
+      if (code && body) edited[code] = locale.body;
+    }
+
+    return {
+      slug: definition.slug,
+      module: definition.moduleSlug,
+      name: definition.name,
+      description: definition.description ?? {},
+      body: { ...definition.fallback, ...edited },
+      fallback: definition.fallback,
+      variables: definition.variables,
+      is_active: row?.is_active ?? true,
+      customized: Boolean(row),
+    };
+  }
+}

package/src/message-template/message-template.controller.ts

@@ -0,0 +1,52 @@
+import { Role } from '@hed-hog/api';
+import { Body, Controller, Get, Param, Patch, Post, Query } from '@nestjs/common';
+
+import { MessageTemplateAdminService } from './message-template-admin.service';
+import { UpdateMessageTemplateDTO } from './dto/update-message-template.dto';
+
+/**
+ * Modelos de mensagem, endereçados por SLUG e não por id.
+ *
+ * O id seria o identificador errado aqui: a linha do banco só existe depois da
+ * primeira edição, então um modelo ainda no padrão não teria id nenhum para a
+ * tela usar. O slug existe desde que a library o registra.
+ */
+@Role()
+@Controller('message-templates')
+export class MessageTemplateController {
+  constructor(private readonly templates: MessageTemplateAdminService) {}
+
+  @Get()
+  async list(@Query('module') module?: string) {
+    return this.templates.list(module?.trim() || undefined);
+  }
+
+  // Antes de :slug — o Nest resolve rotas na ordem em que estão declaradas.
+  @Get('modules')
+  async modules() {
+    return this.templates.modules();
+  }
+
+  @Post(':slug/preview')
+  async preview(@Param('slug') slug: string, @Body() body: { body: string }) {
+    return this.templates.preview(slug, body?.body ?? '');
+  }
+
+  @Post(':slug/restore')
+  async restore(@Param('slug') slug: string) {
+    return this.templates.restore(slug);
+  }
+
+  @Get(':slug')
+  async get(@Param('slug') slug: string) {
+    return this.templates.get(slug);
+  }
+
+  @Patch(':slug')
+  async update(
+    @Param('slug') slug: string,
+    @Body() data: UpdateMessageTemplateDTO,
+  ) {
+    return this.templates.update(slug, data);
+  }
+}

package/src/message-template/message-template.module.ts

@@ -0,0 +1,21 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+
+import { MessageTemplateAdminService } from './message-template-admin.service';
+import { MessageTemplateController } from './message-template.controller';
+import { MessageTemplateService } from './message-template.service';
+
+/**
+ * Modelos de mensagem para canal que não é e-mail.
+ *
+ * Exporta o `MessageTemplateService` porque quem renderiza são as libraries: o
+ * SAC para o aviso de chamado, o commerce para o de venda. O serviço da tela
+ * fica dentro, que ninguém fora daqui edita template por código.
+ */
+@Module({
+  imports: [forwardRef(() => PrismaModule)],
+  controllers: [MessageTemplateController],
+  providers: [MessageTemplateService, MessageTemplateAdminService],
+  exports: [MessageTemplateService],
+})
+export class MessageTemplateModule {}

package/src/message-template/message-template.registry.spec.ts

@@ -0,0 +1,62 @@
+import {
+  clearMessageTemplateRegistry,
+  listMessageTemplateDefinitions,
+  registerMessageTemplates,
+} from './message-template.registry';
+
+/** Uma definição válida; cada teste sobrescreve só o que lhe interessa. */
+const definicao = (overrides: Record<string, unknown> = {}) => ({
+  slug: 'demo.aviso',
+  moduleSlug: 'demo',
+  name: { pt: 'Aviso' },
+  fallback: { pt: 'Olá {{nome}}' },
+  variables: { nome: { sample: 'Fulano' } },
+  ...overrides,
+});
+
+describe('registerMessageTemplates', () => {
+  beforeEach(() => clearMessageTemplateRegistry());
+
+  it('aceita uma definição bem formada', () => {
+    registerMessageTemplates([definicao() as any]);
+    expect(listMessageTemplateDefinitions('demo')).toHaveLength(1);
+  });
+
+  it('recusa slug fora da gramática <module>.<nome>', () => {
+    // Sem a gramática, duas libraries brigariam por um slug curto como "paid" e
+    // a tela não teria como dizer de quem é o modelo.
+    expect(() =>
+      registerMessageTemplates([definicao({ slug: 'aviso' }) as any]),
+    ).toThrow(/inválido/);
+  });
+
+  it('recusa moduleSlug que não bate com o slug', () => {
+    expect(() =>
+      registerMessageTemplates([
+        definicao({ slug: 'sac.aviso', moduleSlug: 'commerce' }) as any,
+      ]),
+    ).toThrow(/moduleSlug/);
+  });
+
+  it('recusa modelo sem texto padrão em português', () => {
+    // Sem o padrão, uma linha quebrada no banco deixaria o aviso mudo.
+    expect(() =>
+      registerMessageTemplates([definicao({ fallback: { en: 'Hi' } }) as any]),
+    ).toThrow(/texto padrão/);
+  });
+
+  it('recusa slug duplicado em vez de deixar uma library sobrescrever a outra', () => {
+    registerMessageTemplates([definicao() as any]);
+    expect(() =>
+      registerMessageTemplates([definicao({ name: { pt: 'Outro' } }) as any]),
+    ).toThrow(/já está registrado/);
+  });
+
+  it('registrar a mesma definição duas vezes é inofensivo', () => {
+    // Acontece de verdade: o arquivo de templates é importado por mais de um
+    // módulo, e o Jest reavalia o módulo entre suites.
+    const mesma = definicao() as any;
+    registerMessageTemplates([mesma]);
+    expect(() => registerMessageTemplates([mesma])).not.toThrow();
+  });
+});

package/src/message-template/message-template.registry.ts

@@ -0,0 +1,125 @@
+/**
+ * Declaração de um modelo de mensagem cujo texto canônico vive em código.
+ *
+ * O registry é o que faz da tabela `message_template` um **override** em vez da
+ * única cópia: o render cai no `fallback` sempre que a linha do banco falta,
+ * está desligada, vazia ou com sintaxe quebrada; a tela oferece "restaurar
+ * padrão"; e uma library recém-instalada já aparece na tela sem migration
+ * nenhuma — a listagem é o registry, não um `SELECT`.
+ *
+ * Esse último ponto é a diferença deliberada em relação aos prompts de IA, que
+ * seguem o mesmo desenho mas listam do banco: lá, prompt registrado sem seed
+ * funciona e não aparece na tela, e é preciso uma migration por conjunto.
+ */
+export type MessageTemplateVariable = {
+  /** Explica o que a variável carrega. Aparece no editor, ao lado do botão. */
+  description?: string;
+  /**
+   * Valor de exemplo, usado no preview.
+   *
+   * É obrigatório porque o preview é a única forma de ver onde o texto quebra no
+   * balão do WhatsApp antes de ele chegar ao grupo.
+   */
+  sample: string | number | boolean;
+};
+
+export type MessageTemplateDefinition = {
+  /** `<module>.<nome>` — ver assertSlugGrammar. */
+  slug: string;
+  /** Precisa ser igual ao primeiro segmento do slug. */
+  moduleSlug: string;
+  /** Rótulo na tela, por código de locale. `pt` é obrigatório. */
+  name: Record<string, string>;
+  /** Uma linha dizendo quando a mensagem sai. Opcional, por locale. */
+  description?: Record<string, string>;
+  /**
+   * Texto canônico por locale, em Handlebars com o markdown do WhatsApp.
+   *
+   * É ele que renderiza enquanto ninguém editou — e continua sendo a rede
+   * quando o texto editado falha. `pt` é obrigatório.
+   */
+  fallback: Record<string, string>;
+  variables: Record<string, MessageTemplateVariable>;
+};
+
+const registry = new Map<string, MessageTemplateDefinition>();
+
+const SLUG_RE = /^([a-z0-9-]+)\.([a-z0-9-]+)$/;
+
+/** O locale que todo template precisa ter: é o idioma em que a equipe lê o aviso. */
+const REQUIRED_LOCALE = 'pt';
+
+function assertDefinition(definition: MessageTemplateDefinition) {
+  const match = SLUG_RE.exec(definition.slug);
+
+  if (!match) {
+    throw new Error(
+      `Slug de modelo de mensagem inválido: "${definition.slug}". ` +
+        'Esperado <module>.<nome>, em minúsculas.',
+    );
+  }
+
+  // Sem isto, duas libraries poderiam brigar por um slug curto como "paid" e a
+  // tela não teria como dizer de quem é o modelo.
+  if (match[1] !== definition.moduleSlug) {
+    throw new Error(
+      `O modelo "${definition.slug}" declara moduleSlug "${definition.moduleSlug}", ` +
+        `mas o slug diz "${match[1]}".`,
+    );
+  }
+
+  if (!definition.name?.[REQUIRED_LOCALE]?.trim()) {
+    throw new Error(`O modelo "${definition.slug}" não tem nome em "${REQUIRED_LOCALE}".`);
+  }
+
+  if (!definition.fallback?.[REQUIRED_LOCALE]?.trim()) {
+    throw new Error(
+      `O modelo "${definition.slug}" não tem texto padrão em "${REQUIRED_LOCALE}". ` +
+        'Sem ele, uma linha quebrada no banco deixaria o aviso mudo.',
+    );
+  }
+}
+
+/**
+ * Chamado no carregamento do módulo de cada library, a partir do
+ * `*.message-templates.ts` dela. Slug duplicado lança, então duas libraries não
+ * reivindicam o mesmo modelo em silêncio.
+ */
+export function registerMessageTemplates(
+  definitions: MessageTemplateDefinition[],
+): void {
+  for (const definition of definitions) {
+    assertDefinition(definition);
+
+    const existing = registry.get(definition.slug);
+    if (existing && existing !== definition) {
+      throw new Error(`O modelo de mensagem "${definition.slug}" já está registrado.`);
+    }
+
+    registry.set(definition.slug, definition);
+  }
+}
+
+export function getMessageTemplateDefinition(
+  slug: string,
+): MessageTemplateDefinition | undefined {
+  return registry.get(slug);
+}
+
+export function listMessageTemplateDefinitions(
+  moduleSlug?: string,
+): MessageTemplateDefinition[] {
+  const all = [...registry.values()];
+  const filtered = moduleSlug ? all.filter((d) => d.moduleSlug === moduleSlug) : all;
+  return filtered.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Os módulos que registraram algum modelo, para o agrupamento da tela. */
+export function listMessageTemplateModules(): string[] {
+  return [...new Set([...registry.values()].map((d) => d.moduleSlug))].sort();
+}
+
+/** Auxiliar de teste — o registry é estado de módulo. */
+export function clearMessageTemplateRegistry(): void {
+  registry.clear();
+}

package/src/message-template/message-template.service.spec.ts

@@ -0,0 +1,149 @@
+import {
+  clearMessageTemplateRegistry,
+  registerMessageTemplates,
+} from './message-template.registry';
+import { MessageTemplateService } from './message-template.service';
+
+/**
+ * O que estes testes protegem: o aviso nunca depender do texto editado dar certo.
+ *
+ * Portados do SAC, onde a regra era "todo caminho ruim devolve null e o chamador
+ * usa o texto embutido". Aqui a regra ficou mais forte: todo caminho ruim cai no
+ * `fallback` do registry, e o chamador não precisa mais manter texto nenhum.
+ */
+describe('MessageTemplateService', () => {
+  let prisma: any;
+  let service: MessageTemplateService;
+
+  const SLUG = 'demo.aviso';
+  const PADRAO = 'Padrão: {{protocol}}';
+
+  const linha = (body: string, overrides: Record<string, unknown> = {}) => ({
+    is_active: true,
+    message_template_locale: [{ body, locale: { code: 'pt' } }],
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    clearMessageTemplateRegistry();
+    registerMessageTemplates([
+      {
+        slug: SLUG,
+        moduleSlug: 'demo',
+        name: { pt: 'Aviso' },
+        fallback: { pt: PADRAO, en: 'Default: {{protocol}}' },
+        variables: { protocol: { sample: '202609-000045' } },
+      },
+    ]);
+
+    prisma = { message_template: { findUnique: jest.fn().mockResolvedValue(null) } };
+    service = new MessageTemplateService(prisma);
+  });
+
+  it('renderiza o texto editado quando existe', async () => {
+    prisma.message_template.findUnique.mockResolvedValue(
+      linha('Chamado {{protocol}} de {{requester_name}}'),
+    );
+
+    await expect(
+      service.render(SLUG, {
+        protocol: '202609-000045',
+        requester_name: 'João Rangel',
+      }),
+    ).resolves.toBe('Chamado 202609-000045 de João Rangel');
+  });
+
+  it('não escapa o texto, que vai puro para o WhatsApp', async () => {
+    // Com escape de HTML um apóstrofo viraria `&#x27;` na tela do celular.
+    prisma.message_template.findUnique.mockResolvedValue(linha('{{nome}}'));
+
+    await expect(service.render(SLUG, { nome: "Joao D'Avila" })).resolves.toBe(
+      "Joao D'Avila",
+    );
+  });
+
+  it('esconde a seção quando o campo vem vazio', async () => {
+    prisma.message_template.findUnique.mockResolvedValue(
+      linha('A\n{{#if contact}}\nContato: {{contact}}\n{{/if}}\nB'),
+    );
+
+    await expect(service.render(SLUG, { contact: '' })).resolves.toBe('A\nB');
+  });
+
+  describe('cai no texto padrão quando o editado não serve', () => {
+    const esperado = 'Padrão: 202609-000045';
+    const variaveis = { protocol: '202609-000045' };
+
+    it('não há linha no banco — o caso comum, antes de alguém editar', async () => {
+      prisma.message_template.findUnique.mockResolvedValue(null);
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+
+    it('a linha está desligada', async () => {
+      prisma.message_template.findUnique.mockResolvedValue(
+        linha('Editado', { is_active: false }),
+      );
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+
+    it('o corpo editado está em branco', async () => {
+      prisma.message_template.findUnique.mockResolvedValue(linha('   '));
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+
+    it('o corpo editado tem sintaxe quebrada', async () => {
+      prisma.message_template.findUnique.mockResolvedValue(
+        linha('{{#if contact}}sem fechar'),
+      );
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+
+    it('o corpo editado renderiza vazio', async () => {
+      // Template só com blocos que não casaram. Mandar mensagem em branco para o
+      // grupo é pior que mandar o texto padrão.
+      prisma.message_template.findUnique.mockResolvedValue(
+        linha('{{#if nada}}oi{{/if}}'),
+      );
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+
+    it('o banco está fora do ar', async () => {
+      prisma.message_template.findUnique.mockRejectedValue(new Error('sem conexão'));
+      await expect(service.render(SLUG, variaveis)).resolves.toBe(esperado);
+    });
+  });
+
+  it('sem tradução no idioma pedido, usa a primeira que existir', async () => {
+    // Um texto escrito só em português continua valendo para quem abriu o painel
+    // em inglês; o contrário seria a equipe receber o padrão por causa do idioma
+    // da sessão.
+    prisma.message_template.findUnique.mockResolvedValue(
+      linha('Só em português'),
+    );
+
+    await expect(service.render(SLUG, {}, 'en')).resolves.toBe('Só em português');
+  });
+
+  it('sem texto padrão no idioma pedido, usa o português', async () => {
+    clearMessageTemplateRegistry();
+    registerMessageTemplates([
+      {
+        slug: SLUG,
+        moduleSlug: 'demo',
+        name: { pt: 'Aviso' },
+        fallback: { pt: PADRAO },
+        variables: {},
+      },
+    ]);
+
+    await expect(service.render(SLUG, { protocol: 'X' }, 'en')).resolves.toBe(
+      'Padrão: X',
+    );
+  });
+
+  it('devolve null só quando o slug não está registrado', async () => {
+    // Nulo aqui é erro de programação — slug digitado errado, library não
+    // carregada —, não configuração. Por isso é o único caso.
+    await expect(service.render('demo.inexistente', {})).resolves.toBeNull();
+  });
+});