@hed-hog/core 0.0.398 → 0.0.400

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

@@ -0,0 +1,163 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+
+import { MessageTemplateAdminService } from './message-template-admin.service';
+import {
+  clearMessageTemplateRegistry,
+  registerMessageTemplates,
+} from './message-template.registry';
+
+/**
+ * O CRUD da tela, que no SAC não tinha cobertura nenhuma.
+ *
+ * O que estes testes protegem é o desenho: a listagem vem do REGISTRY e o banco
+ * entra por cima. Um modelo recém-declarado por uma library precisa aparecer
+ * antes de existir linha no banco — senão volta a dor dos prompts de IA, em que
+ * prompt sem seed simplesmente não aparece.
+ */
+describe('MessageTemplateAdminService', () => {
+  let prisma: any;
+  let service: MessageTemplateAdminService;
+
+  const SLUG = 'demo.aviso';
+
+  beforeEach(() => {
+    clearMessageTemplateRegistry();
+    registerMessageTemplates([
+      {
+        slug: SLUG,
+        moduleSlug: 'demo',
+        name: { pt: 'Aviso' },
+        description: { pt: 'Sai quando algo acontece.' },
+        fallback: { pt: 'Padrão {{protocol}}', en: 'Default {{protocol}}' },
+        variables: { protocol: { sample: '202609-000045' } },
+      },
+      {
+        slug: 'outro.aviso',
+        moduleSlug: 'outro',
+        name: { pt: 'Outro' },
+        fallback: { pt: 'Outro padrão' },
+        variables: {},
+      },
+    ]);
+
+    prisma = {
+      message_template: {
+        findMany: jest.fn().mockResolvedValue([]),
+        findUnique: jest.fn().mockResolvedValue(null),
+        upsert: jest.fn().mockResolvedValue({ id: 7, slug: SLUG }),
+        delete: jest.fn().mockResolvedValue({}),
+      },
+      message_template_locale: { upsert: jest.fn().mockResolvedValue({}) },
+      locale: { findFirst: jest.fn().mockResolvedValue({ id: 1 }) },
+    };
+
+    service = new MessageTemplateAdminService(prisma);
+  });
+
+  describe('list', () => {
+    it('mostra o modelo antes de existir linha no banco', async () => {
+      const { data } = await service.list();
+
+      expect(data).toHaveLength(2);
+      const item = data.find((d) => d.slug === SLUG)!;
+      expect(item.customized).toBe(false);
+      expect(item.is_active).toBe(true);
+      expect(item.body.pt).toBe('Padrão {{protocol}}');
+    });
+
+    it('o texto editado vence o padrão, por idioma', async () => {
+      prisma.message_template.findMany.mockResolvedValue([
+        {
+          slug: SLUG,
+          is_active: true,
+          message_template_locale: [
+            { body: 'Editado {{protocol}}', locale: { code: 'pt' } },
+          ],
+        },
+      ]);
+
+      const { data } = await service.list();
+      const item = data.find((d) => d.slug === SLUG)!;
+
+      expect(item.customized).toBe(true);
+      expect(item.body.pt).toBe('Editado {{protocol}}');
+      // O inglês não foi editado: segue o padrão do código.
+      expect(item.body.en).toBe('Default {{protocol}}');
+      // E o padrão continua exposto, para a tela poder restaurar.
+      expect(item.fallback.pt).toBe('Padrão {{protocol}}');
+    });
+
+    it('filtra por módulo, para o agrupamento da tela', async () => {
+      const { data } = await service.list('outro');
+      expect(data.map((d) => d.slug)).toEqual(['outro.aviso']);
+    });
+  });
+
+  describe('update', () => {
+    it('cria a linha na primeira edição', async () => {
+      await service.update(SLUG, { locale: { pt: { body: 'Novo {{protocol}}' } } });
+
+      expect(prisma.message_template.upsert).toHaveBeenCalledWith(
+        expect.objectContaining({ where: { slug: SLUG } }),
+      );
+      expect(prisma.message_template_locale.upsert).toHaveBeenCalled();
+    });
+
+    it('recusa corpo com sintaxe quebrada antes de gravar', async () => {
+      // Aceitar deixaria a tela dizendo "salvo" enquanto o aviso sai com o texto
+      // padrão, sem explicação nenhuma.
+      await expect(
+        service.update(SLUG, { locale: { pt: { body: '{{#if x}}sem fechar' } } }),
+      ).rejects.toThrow(BadRequestException);
+
+      expect(prisma.message_template.upsert).not.toHaveBeenCalled();
+    });
+
+    it('não mexe em is_active quando o corpo não o menciona', async () => {
+      await service.update(SLUG, { locale: { pt: { body: 'ok' } } });
+
+      expect(prisma.message_template.upsert).toHaveBeenCalledWith(
+        expect.objectContaining({ update: {} }),
+      );
+    });
+
+    it('recusa slug que nenhuma library registrou', async () => {
+      await expect(service.update('demo.fantasma', {})).rejects.toThrow(
+        NotFoundException,
+      );
+    });
+  });
+
+  describe('restore', () => {
+    it('apaga a linha em vez de copiar o padrão para dentro dela', async () => {
+      // Copiar congelaria o texto na versão de hoje, e a próxima melhoria que
+      // viesse por deploy não chegaria a quem restaurou.
+      await service.restore(SLUG);
+
+      expect(prisma.message_template.delete).toHaveBeenCalledWith({
+        where: { slug: SLUG },
+      });
+    });
+
+    it('restaurar um modelo que nunca foi editado não é erro', async () => {
+      prisma.message_template.delete.mockRejectedValue(new Error('não existe'));
+      await expect(service.restore(SLUG)).resolves.toBeDefined();
+    });
+  });
+
+  describe('preview', () => {
+    it('renderiza com as amostras declaradas pelo registry', () => {
+      expect(service.preview(SLUG, 'Chamado {{protocol}}')).toEqual({
+        text: 'Chamado 202609-000045',
+      });
+    });
+
+    it('recusa sintaxe quebrada', () => {
+      expect(() => service.preview(SLUG, '{{#if x}}')).toThrow(BadRequestException);
+    });
+  });
+
+  it('modules lista os módulos que declararam algum modelo', () => {
+    expect(service.modules()).toEqual({ data: ['demo', 'outro'] });
+  });
+});

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();
+}