Help

Status: 🟡 Em fluxo (ajuda contextual + manual canônico) Code: backend/app/modules/help UI: frontend/src/app/(admin)/[slug]/admin/help-admin + /admin/manual (manual) Última revisão deste doc: 2026-05-13 por Felipe + Claude

1. Identidade

O que faz (uma frase)

Suporte contextual via IA (Claude Haiku com cache ephemeral consulta ~100 artigos hardcoded + aprovados do DB), feature requests dos users com email automático, scanner noturno que sugere novos artigos via Claude Sonnet, e Manual do Sistema (este manual!) servido como markdown via API.

Por que existe (negócio)

User pergunta "como crio uma campanha?" → IA responde com steps reais. Sem este módulo:

User abre help externo (Notion/docs estática).
Feedback vira email manual.
Documentação técnica fica em repo separado sem UI.

Com Help:

"Posso fazer X?" via IA contextualizada → resposta [DISPONÍVEL] ou [NÃO DISPONÍVEL].
Feedback vira help_feature_request + email pra suporte.
Manual canônico servido em /admin/manual (este doc!).

Status atual

Em fluxo. Manual System recém-adicionado (2026-05-13).

2. Cases de uso reais

Case 1: User pergunta "como crio campanha email?"

UI help → POST /api/help/query {question, page_context} → Claude Haiku consulta knowledge_base.py + aprovados → retorna {answer, can_do=true}.

Case 2: User envia feature request

UI feedback button → POST /api/help/feature-request → salva DB + email Brevo pra suporte@mandir.com.br (fire-and-forget).

Case 3: Manual canônico

UI /admin/manual → backend serve manual_content/*.md → react-markdown renderiza com TOC + status badges.

3. Oportunidades de negócio

Help vendido como add-on: "AI Help Center" tier premium pra clientes Mandir.
Manual auto-gerado: scanner que mantém docs atualizados via IA.
Multi-language: Claude traduz dinamicamente.

4. Arquitetura interna

Arquivos

models.py — 2 tabelas.
routes.py — 8 endpoints + manual_routes include.
manual_routes.py — Manual System (parseia README + serve documents).
knowledge_base.py — ARTICLES (~100 hardcoded).
scanner.py — scanner via Claude Sonnet.
tasks.py — Celery wrapper.
manual_content/ — markdown synced de mandir-docs/manual/.

Tasks

Task	Schedule	O que faz
`help.scan_articles`	Beat nightly (TBD)	Lê routes.py de todos módulos → Claude Sonnet sugere artigos pendentes

5. Tabelas (2)

`help_article_suggestion`

Coluna	Notas
`article_id`	UNIQUE string
`module`	idx
`title` / `summary` / `steps` (JSONB) / `use_cases` (JSONB) / `tags` (JSONB)
`status`	`pending` / `approved` / `rejected`
`source`	`nightly` / `manual`
`reviewed_at`

`help_feature_request`

Coluna	Notas
`tenant_id`
`question` / `description` (max 3000)
`page_context` / `module_context`
`user_email`	Opcional

6. API / Endpoints (8 + 3 manual)

Prefixo /api/help.

Help (8)

Método	Rota	O que faz
GET	`/articles?module=X`	Lista (estáticos + aprovados)
POST	`/query`	LLM com cache ephemeral (Haiku)
POST	`/feature-request`	Salva + email Brevo
GET	`/suggestions?status=`	Admin lista
POST	`/suggestions/scan`	Trigger manual
PATCH	`/suggestions/{id}/approve`	Approve
PATCH	`/suggestions/{id}/reject`	Reject
GET	`/suggestions/stats`	Contadores

Manual (3)

Método	Rota	O que faz
GET	`/manual/index`	Parseia README → domains + modules
GET	`/manual/document/{slug}`	Markdown cru
GET	`/manual/readme`	Atalho pro README

7. Configuração

Env vars

Var	Propósito
`ANTHROPIC_API_KEY`	Claude (compartilhado)
`BREVO_API_KEY` / `BREVO_SENDER_EMAIL` / `BREVO_SENDER_NAME`	Email feature request

8. Operações + Troubleshooting

Sintoma: Manual não carrega doc

Causa: Slug inválido (não match [a-zA-Z0-9_-]+) ou arquivo ausente em manual_content/. Fix: Verificar ls manual_content/.

Sintoma: Feature request não envia email

Causa: Brevo falhou (fire-and-forget). Diagnóstico: Logs help.feature_request.email.failed.

9. Limitações e débitos técnicos

#	Item
1	LLM cache ephemeral
2	Email fire-and-forget
3	Scanner heurístico
4	Manual sem versionamento
5	~100 artigos inline no prompt — Se > 500, considerar embeddings

10. Histórico

2026-05-13 — Manual System adicionado (este doc!).
Em prod desde Suite v2.