shuangying0001-beep/wechat-notify

Notificações via WeChat

Fonte: Pacote de Construção "Crescimento Infantil" AI要怎么做.md §3.3 Notificações WeChat/WeCom – agora desacoplado do projeto e tornado uma especificação genérica de integração.

O que é

Notificações são um recurso padrão na maioria dos miniprogramas. Este skill fornece especificações de integração e scripts geradores para as duas abordagens mais comuns: Webhook do WeCom (a mais simples, 5 minutos) e Mensagens de Template do WeChat Official Account (exige que o usuário siga a conta). Também impõe regras rigorosas de armazenamento de credenciais.

O script vem com --self-test: ele usa httpx para simular e verificar a estrutura do payload de três tipos de envio (texto / cartão markdown / mensagem de template), comprovando que o módulo gerado é funcional – sem necessidade de Webhook real ou conexão com a internet.

Quando usar

• Quando o usuário disser: "Integrar notificação do WeChat" / "Webhook do WeCom" / "Mensagens de Template da Conta Oficial" / "Envio de mensagens pelo WeChat"
• Qualquer cenário que precise enviar mensagens do sistema para o WeChat (grupo ou usuário): lembretes de tarefas, notificações de status, alertas

Opção 1: Webhook do WeCom (recomendado, integração em 5 minutos)

• POST {webhook_url} enviando JSON: {"msgtype":"text","text":{"content":"conteúdo da mensagem"}}
• Suporta formato markdown, com links e imagens.
• Não requer aprovação; qualquer administrador de grupo pode criar (Grupo → Adicionar Robô → Copiar URL do Webhook)

Opção 2: Mensagens de Template da Conta Oficial

• Primeiro, obtenha o access_token (válido por 7200s, deve ser armazenado em cache Redis/memória, proibido obter a cada requisição)
• POST https://api.weixin.qq.com/cgi-bin/message/template/send
• Requer que o usuário siga a Conta Oficial e que o template seja aprovado no painel da Conta Oficial.

Requisitos de Segurança (P0)

• O URL do Webhook do WeCom deve ser tratado como credencial, armazenado somente em .env, nunca no código-fonte.
• O AppSecret da Conta Oficial deve ficar apenas no servidor, nunca enviado ao frontend.
• Nunca faça commit de credenciais no repositório Git; use em conjunto com as diretrizes de segurança de wechat-miniprogram-devrules.

Uso do Script (Gerar Módulo de Notificação)

# 0) Teste os payloads primeiro (recomendado executar ao menos uma vez antes de usar)
python gen_notify.py --self-test

# 1) Gere o módulo
python gen_notify.py --out ./notify_module

Gera:

• notify_module/wecom_bot.py – Envio pelo Webhook do WeCom (texto / markdown, com retry e rate limiting, oferece também markdown_card() para cartões de notificação)
• notify_module/mp_template.py – Mensagens de Template da Conta Oficial (cache de access_token + envio, com retry e rate limiting)
• notify_module/.env.example – Campos de credenciais a serem preenchidos

Observações

• Webhook do WeCom é adequado para alertas/notificações "sistema → grupo"; Mensagens de Template da Conta Oficial são para comunicações "sistema → usuário específico" (ex.: lembretes de tarefas, créditos recebidos).
• A chave de cache do access_token deve incluir tempo de expiração e ser renovada antes de expirar, para evitar múltiplas requisições simultâneas que disparem limitações de frequência.
• O conteúdo da mensagem de template é limitado pela categoria da Conta Oficial e pelos campos do template; verifique a correspondência dos nomes dos campos antes do envio.
• Use em conjunto com ai-work-acceptance para validação: verifique principalmente se as URLs de Webhook e AppSecrets não foram hardcoded ou salvos em banco de dados.