Tainacan Colab

Plugin WordPress independente que permite aos visitantes sugerir correções nos metadados de itens do Tainacan, no estilo de uma enciclopédia colaborativa. As sugestões são revisadas pela equipe antes de serem aplicadas.

Identificador interno (slug/pasta/text-domain): tainacan-metadata-crowdsource. "Tainacan Colab" é apenas o nome de exibição.

Como funciona

1. Na página pública de um item, o formulário aparece automaticamente (um botão que abre um drawer lateral não-bloqueante — o visitante continua vendo e rolando o item enquanto escreve), ou é colocado manualmente com o shortcode [tmc_suggest_form item_id="123"].
2. O visitante (mesmo anônimo) edita o texto diretamente nos campos, já pré-preenchidos com os valores atuais — como numa wiki. Só os campos que ele alterar são enviados.
3. Após responder a verificação anti-spam local (uma soma simples), as sugestões ficam pendentes no painel administrativo, agrupadas por envio.
4. A equipe revisa. Ao aprovar, o valor sugerido é gravado no item Tainacan automaticamente (o gestor pode ainda ajustar o valor antes de aprovar). Rejeições e aprovações ficam registradas com autor, data e notas.
5. Se o valor original mudar antes da revisão (ex.: a equipe editou o item), a sugestão é marcada como desatualizada para que o revisor reavalie.

Principais recursos

• Edição inline estilo wiki: o colaborador corrige diretamente o campo; multivalorados são editados um valor por linha, com botão de restaurar o original.
• Exibição automática: botão inserido nas páginas de item Tainacan que abre o formulário em um drawer lateral não-bloqueante, com indicador flutuante para reabrir depois de fechado. Sem configuração por item; pode ser desligado nas configurações.
• Controle por coleção: na aba Coleções, escolha exatamente quais metadados de cada coleção aceitam sugestões (allowlist), ou desative o crowdsourcing em coleções específicas. Coleções não configuradas liberam todos os metadados públicos (comportamento padrão).
• Moderação por submissão: cada metadado é aprovado/rejeitado/excluído separadamente; diferenças (atual × sugerida) destacadas via wp_text_diff; histórico de revisão; e agradecimento por e-mail ao colaborador. Confirmações e notas em painéis inline com toasts — sem diálogos nativos do navegador.
• Curadoria do gestor: o valor sugerido é editável na moderação e o valor final é auditado (quem editou).
• Detecção de "desatualizadas": sugestões pendentes cujo valor original mudou são sinalizadas.
• Anti-spam 100% local: pergunta aritmética de uso único + honeypot + time-trap + rate-limit por IP. Sem serviços externos e sem CDN.
• Notificação por e-mail ao moderador a cada nova sugestão.

Requisitos

• WordPress 6.0+
• PHP 8.0+
• Tainacan instalado e ativado

Onde fica no admin

No menu do Tainacan, dentro do grupo "Outros", item Colab (cai no menu raiz se o grupo "Outros" estiver oculto nas opções de UI do Tainacan). A página segue o layout canônico das extensões Tainacan — grade com barra lateral de resumo por status, instruções de uso e nota de anti-spam — e tem três abas:

• Sugestões — moderação (pendentes, desatualizadas, aprovadas, rejeitadas).
• Coleções — allowlist de metadados por coleção.
• Configurações — habilitar sugestões, exibição automática, notificação e e-mail do moderador.

Anti-spam

Verificação 100% local, sem terceiros e sem CDN:

• Pergunta aritmética — desafio de uso único, verificado no servidor e carregado via REST para ser imune a page cache.
• Honeypot — campo oculto que apenas bots preenchem.
• Time-trap — submissões rápidas demais para serem humanas são rejeitadas.
• Rate-limit por IP (1 envio a cada 15s, com teto por hora).

Instalação

1. Copie a pasta tainacan-metadata-crowdsource para wp-content/plugins/.
2. Ative em Plugins → Instalados (o Tainacan precisa estar ativo).
3. Defina o e-mail do moderador em Tainacan → (Outros) → Colab → Configurações.
4. (Opcional) Em Colab → Coleções, escolha quais metadados de cada coleção aceitam sugestões.
5. A exibição automática já vem ligada; para colocação manual, use o shortcode abaixo.

Uso

[tmc_suggest_form item_id="123"]

Substitua 123 pelo ID do item Tainacan. O formulário exibe os metadados públicos do item que estão habilitados para a coleção (na aba Coleções). Se a coleção não foi configurada, exibe todos os metadados públicos.

Estrutura

tainacan-metadata-crowdsource/
├── tainacan-metadata-crowdsource.php   Bootstrap do plugin
├── uninstall.php                        Limpeza ao desinstalar
├── includes/
│   ├── Core/          Plugin, Activator, Deactivator
│   ├── Database/      Schema da tabela wp_tmc_suggestions
│   ├── REST/          Endpoints /wp-json/tmc/v1/*
│   ├── Frontend/      Shortcode [tmc_suggest_form] + auto-injeção
│   ├── Admin/         Página de administração (AdminPage + settings-page.php + views/ por aba)
│   ├── Settings/      CollectionConfig (allowlist por coleção)
│   ├── Security/      Captcha (anti-spam local)
│   └── SuggestionsManager.php   Lógica central de CRUD
└── assets/            CSS e JS (public + admin)

Endpoints REST

Integração com Tainacan

O plugin usa as APIs oficiais \Tainacan\Repositories\Items, \Tainacan\Repositories\Item_Metadata, Metadata e Collections. Não depende de nenhum outro plugin além do próprio Tainacan. Ao aprovar uma sugestão, o metadado é gravado via Item_Metadata::insert() respeitando validação e cardinalidade do Tainacan. A página administrativa integra-se ao menu/layout do Tainacan estendendo \Tainacan\Pages.

Detecção de "desatualizada" (stale)

Ao salvar qualquer post Tainacan (custom post type tnc_col_*_item), o plugin reavalia as sugestões pendentes desse item: se o hash do valor original mudou, a sugestão é marcada como desatualizada.

Desenvolvimento

composer install
composer lint           # phpcs --standard=phpcs.xml.dist (WPCS Core/Docs/Extra/Security + PHPCompatibility 8.0)
wp i18n make-pot . languages/tainacan-metadata-crowdsource.pot

O bundle de assets (CSS/JS) é versionado no repositório — não há passo de build no deploy. O identificador interno permanece tainacan-metadata-crowdsource (pasta, text-domain, prefixos TMC_/tmc_, namespace REST tmc/v1, tabela wp_tmc_suggestions).

Desde a v1.7.0 o plugin segue o padrão canônico de UI/integração de extensões Tainacan (TAINACAN_UI_PATTERNS.md, referência tainacan-ai): declare(strict_types=1) em todos os arquivos, wiring no init com guarda de Tainacan, tela admin com grid + sidebar e tokens CSS espelhando o tema, drawer no front-end e REST com args validados no registro. Contexto para mantenedores e assistentes de IA em AGENTS.md.

Licença

GPL-3.0-or-later