Merge remote-tracking branch 'origin/main'
# Conflicts: # .claude-plugin/marketplace.json # .gitignore # acidaos/skills/devops/SKILL.md # acidaos/skills/docs/SKILL.md # acidaos/skills/rust-dev/SKILL.md # acidaos/skills/spoke-dev/SKILL.md # automacao/agents/automation-lead.md # automacao/agents/mcp-protocol-developer.md # automacao/agents/n8n-automation-expert.md # automacao/skills/moloni-api/SKILL.md # automacao/skills/n8n/SKILL.md # core-tools/skills/_core/SKILL.md # core-tools/skills/agent-context-injector/SKILL.md # core-tools/skills/component-generator/SKILL.md # core-tools/skills/db-maintenance-manager/SKILL.md # core-tools/skills/infrastructure-manager/SKILL.md # core-tools/skills/metrics/SKILL.md # core-tools/skills/plugin-curator/SKILL.md # core-tools/skills/plugin-manager/SKILL.md # core-tools/skills/plugin-manager/profiles.json # core-tools/skills/quality-validator/SKILL.md # core-tools/skills/relationship-manager/SKILL.md # crm-ops/.claude-plugin/plugin.json # crm-ops/CHANGELOG.md # crm-ops/agents/budget-proposal-specialist.md # crm-ops/agents/lead-approach-strategist.md # crm-ops/agents/lead-qualifier.md # crm-ops/agents/sales-manager.md # crm-ops/agents/support-specialist.md # crm-ops/skills/auto-expense/SKILL.md # crm-ops/skills/billing-check/SKILL.md # crm-ops/skills/crm-admin/SKILL.md # crm-ops/skills/crm/SKILL.md # crm-ops/skills/desk/SKILL.md # crm-ops/skills/estrategia-marca/SKILL.md # crm-ops/skills/estrategia-marca/references/metodologia-acida.md # crm-ops/skills/estrategia-marca/references/template-documento.md # crm-ops/skills/expense/SKILL.md # crm-ops/skills/invoice/SKILL.md # crm-ops/skills/orcamento/SKILL-light.md # crm-ops/skills/orcamento/SKILL.md # crm-ops/skills/proposal-deck/SKILL.md # crm-ops/skills/proposta-visual/SKILL.md # crm-ops/skills/ticket-manage/SKILL.md # crm-ops/skills/ticket-triage/SKILL.md # crm-ops/skills/ticket/SKILL.md # design-media/agents/design-critic.md # design-media/agents/design-generator.md # design-media/agents/design-lead.md # design-media/agents/design-prompt-architect.md # design-media/agents/design-researcher.md # design-media/agents/ui-designer.md # design-media/agents/video-production-specialist.md # design-media/agents/web-designer.md # design-media/skills/brand-guidelines/SKILL.md # design-media/skills/brand-guidelines/references/descomplicar-theme.md # design-media/skills/cinematic-site/SKILL.md # design-media/skills/clone-style/SKILL.md # design-media/skills/design-b2b/SKILL.md # design-media/skills/design-ecommerce/SKILL.md # design-media/skills/design-saude/SKILL.md # design-media/skills/design-solar/SKILL.md # design-media/skills/design/SKILL.md # design-media/skills/design/references/premium-proposals.md # dev-tools/agents/database-design-specialist.md # dev-tools/agents/dev-helper.md # dev-tools/agents/development-lead.md # dev-tools/agents/javascript-fullstack-specialist.md # dev-tools/agents/nextjs-specialist.md # dev-tools/agents/php-fullstack-engineer.md # dev-tools/skills/benchmark/SKILL.md # dev-tools/skills/canary/SKILL.md # dev-tools/skills/chrome/SKILL.md # dev-tools/skills/db-design/SKILL.md # dev-tools/skills/dep-audit/SKILL.md # dev-tools/skills/diagrama/SKILL.md # dev-tools/skills/docx/SKILL-light.md # dev-tools/skills/docx/SKILL.md # dev-tools/skills/docx/scripts/__init__.py # dev-tools/skills/docx/scripts/office/pack.py # dev-tools/skills/docx/scripts/office/unpack.py # dev-tools/skills/docx/scripts/office/validate.py # dev-tools/skills/nextjs/SKILL.md # dev-tools/skills/pdf/SKILL-light.md # dev-tools/skills/pdf/SKILL.md # dev-tools/skills/php-dev/SKILL.md # dev-tools/skills/prompt-refine/SKILL.md # dev-tools/skills/react-patterns/SKILL.md # dev-tools/skills/skill-creator/SKILL.md # dev-tools/skills/skill-creator/references/descomplicar-standards.md # dev-tools/skills/webapp-testing/SKILL.md # dev-tools/skills/webapp-testing/scripts/with_server.py # dev-tools/skills/xlsx/SKILL.md # dev-tools/skills/xlsx/scripts/office/pack.py # dev-tools/skills/xlsx/scripts/office/unpack.py # dev-tools/skills/xlsx/scripts/office/validate.py # dev-tools/skills/youtube-extract/SKILL.md # gestao/.claude-plugin/plugin.json # gestao/agents/analytics-insights-agent.md # gestao/agents/compliance-auditor.md # gestao/agents/project-manager.md # gestao/agents/reflect-agent.md # gestao/agents/software-project-planner.md # gestao/agents/time-management-agent.md # gestao/agents/wiki-knowledge-agent.md # gestao/skills/aiktop-tasks/SKILL.md # gestao/skills/archive/SKILL.md # gestao/skills/calendar-manager/SKILL.md # gestao/skills/cleanup-downloads/SKILL.md # gestao/skills/clip-agent/SKILL.md # gestao/skills/clip-health/SKILL.md # gestao/skills/clip-instructions/SKILL.md # gestao/skills/clip-issue/SKILL.md # gestao/skills/clip-org/SKILL.md # gestao/skills/clip-routine/SKILL.md # gestao/skills/clip-skill/SKILL.md # gestao/skills/clip-vision/SKILL.md # gestao/skills/clip/SKILL.md # gestao/skills/daily-digest/SKILL.md # gestao/skills/deep-research/SKILL.md # gestao/skills/delegate/SKILL.md # gestao/skills/doc-coauthoring/SKILL.md # gestao/skills/dual-review/SKILL.md # gestao/skills/hub-compile/SKILL.md # gestao/skills/hub-search/SKILL.md # gestao/skills/imap-triage/SKILL.md # gestao/skills/index-update/SKILL.md # gestao/skills/knowledge/SKILL.md # gestao/skills/knowledge/docs/workflow.md # gestao/skills/knowledge/references/routing-guide.md # gestao/skills/mindmap/SKILL.md # gestao/skills/monday-briefing/SKILL.md # gestao/skills/notebooklm/SKILL.md # gestao/skills/office-hours/SKILL.md # gestao/skills/onboarding/SKILL.md # gestao/skills/proc-creator/SKILL.md # gestao/skills/reflect/SKILL.md # gestao/skills/report-templates/SKILL.md # gestao/skills/report/SKILL.md # gestao/skills/research-pipeline/SKILL.md # gestao/skills/review-corrections/SKILL.md # gestao/skills/spec-coauthor/SKILL.md # gestao/skills/task-state/SKILL.md # gestao/skills/tasks-overview/SKILL.md # gestao/skills/time/SKILL.md # gestao/skills/today/SETUP_MCPS.md # gestao/skills/today/SKILL.md # gestao/skills/today/prompts/execute.md # gestao/skills/today/templates/daily-report.md # gestao/skills/validate-component/SKILL.md # gestao/skills/worklog/SKILL.md # infraestrutura/.claude-plugin/plugin.json # infraestrutura/agents/backup-specialist.md # infraestrutura/agents/cwp-server-manager.md # infraestrutura/agents/easypanel-specialist.md # infraestrutura/agents/infrastructure-orchestrator.md # infraestrutura/agents/proxmox-specialist.md # infraestrutura/agents/security-compliance-specialist.md # infraestrutura/skills/authentik/SKILL.md # infraestrutura/skills/backup-strategies/SKILL.md # infraestrutura/skills/backup-strategies/references/scripts.md # infraestrutura/skills/cwp/SKILL.md # infraestrutura/skills/easypanel-api/SKILL.md # infraestrutura/skills/easypanel-cicd/SKILL.md # infraestrutura/skills/easypanel-deploy/SKILL.md # infraestrutura/skills/easypanel-init/SKILL.md # infraestrutura/skills/easypanel-monitor/SKILL.md # infraestrutura/skills/easypanel-rollback/SKILL.md # infraestrutura/skills/easypanel-troubleshoot/SKILL.md # infraestrutura/skills/easypanel-validate/SKILL.md # infraestrutura/skills/gateway-check/SKILL.md # infraestrutura/skills/infra-check/SKILL.md # infraestrutura/skills/mcp-dev/SKILL.md # infraestrutura/skills/mcp-dev/references/best-practices.md # infraestrutura/skills/mcp-dev/references/evaluation-guide.md # infraestrutura/skills/mcp-dev/references/templates.md # infraestrutura/skills/pbs-config/SKILL.md # infraestrutura/skills/proxmox-cluster/SKILL.md # infraestrutura/skills/proxmox-ha/SKILL.md # infraestrutura/skills/proxmox-setup/SKILL.md # infraestrutura/skills/security-audit/SKILL.md # infraestrutura/skills/security-check/SKILL.md # infraestrutura/skills/server-health/SKILL.md # infraestrutura/skills/vm-migration/SKILL.md # marketing/.claude-plugin/plugin.json # marketing/CHANGELOG.md # marketing/agents/content-manager.md # marketing/agents/copywriter.md # marketing/agents/marketing-planning-expert.md # marketing/agents/ppc-specialist.md # marketing/agents/seo-specialist.md # marketing/agents/social-media-manager.md # marketing/agents/video-production-specialist.md # marketing/agents/youtube-specialist.md # marketing/skills/ads/SKILL.md # marketing/skills/content-marketing-pt/SKILL.md # marketing/skills/lead-approach/SKILL.md # marketing/skills/marketing-strategy/SKILL.md # marketing/skills/seo-audit/SKILL.md # marketing/skills/seo-audit/references/ferramentas-api.md # marketing/skills/seo-audit/references/template-relatorio-auditoria.md # marketing/skills/seo-content-optimization/SKILL.md # marketing/skills/seo-content-optimization/references/structured-data.md # marketing/skills/seo-report/SKILL.md # marketing/skills/seo-report/references/implementacao-tecnica.md # marketing/skills/seo-report/references/template-relatorio.md # marketing/skills/social-media/SKILL.md # marketing/skills/trend-signal/SKILL.md # marketing/skills/video/SKILL.md # marketing/skills/video/rules/3d.md # marketing/skills/video/rules/animations.md # marketing/skills/video/rules/assets.md # marketing/skills/video/rules/audio.md # marketing/skills/video/rules/calculate-metadata.md # marketing/skills/video/rules/can-decode.md # marketing/skills/video/rules/charts.md # marketing/skills/video/rules/compositions.md # marketing/skills/video/rules/display-captions.md # marketing/skills/video/rules/extract-frames.md # marketing/skills/video/rules/fonts.md # marketing/skills/video/rules/get-audio-duration.md # marketing/skills/video/rules/get-video-dimensions.md # marketing/skills/video/rules/get-video-duration.md # marketing/skills/video/rules/gifs.md # marketing/skills/video/rules/images.md # marketing/skills/video/rules/import-srt-captions.md # marketing/skills/video/rules/lottie.md # marketing/skills/video/rules/maps.md # marketing/skills/video/rules/measuring-dom-nodes.md # marketing/skills/video/rules/measuring-text.md # marketing/skills/video/rules/parameters.md # marketing/skills/video/rules/sequencing.md # marketing/skills/video/rules/tailwind.md # marketing/skills/video/rules/text-animations.md # marketing/skills/video/rules/timing.md # marketing/skills/video/rules/transcribe-captions.md # marketing/skills/video/rules/transitions.md # marketing/skills/video/rules/trimming.md # marketing/skills/video/rules/videos.md # marketing/skills/youtube/SKILL.md # metabase/agents/metabase-analyst.md # metabase/skills/dashboard/SKILL.md # metabase/skills/metabase/SKILL.md # metabase/skills/query/SKILL.md # negocio/agents/ecommerce-architect.md # negocio/agents/finance-manager.md # negocio/agents/research-analyst.md # negocio/agents/saas-architect.md # negocio/skills/ecommerce/SKILL.md # negocio/skills/interview/SKILL.md # negocio/skills/product/SKILL.md # negocio/skills/research/SKILL.md # negocio/skills/saas/SKILL.md # perfex-dev/agents/perfex-crm-module-developer.md # perfex-dev/skills/perfex-controllers/SKILL.md # perfex-dev/skills/perfex-database/SKILL.md # perfex-dev/skills/perfex-forms/SKILL.md # perfex-dev/skills/perfex-hooks/SKILL.md # perfex-dev/skills/perfex-menus/SKILL.md # perfex-dev/skills/perfex-migrations/SKILL.md # perfex-dev/skills/perfex-module-basics/SKILL.md # perfex-dev/skills/perfex-permissions/SKILL.md # perfex-dev/skills/perfex-security/SKILL.md # perfex-dev/skills/perfex-views/SKILL.md # project-manager/.claude-plugin/plugin.json # project-manager/agents/scrum-master.md # project-manager/agents/spec-writer.md # project-manager/hooks/spec-gate.sh # project-manager/skills/brainstorm/SKILL.md # project-manager/skills/discover/SKILL.md # project-manager/skills/scope/SKILL.md # project-manager/skills/spec/SKILL.md # project-manager/skills/sprint/SKILL.md # project-manager/skills/status/SKILL.md # wordpress/.claude-plugin/plugin.json # wordpress/agents/elementor-specialist.md # wordpress/agents/woocommerce-specialist.md # wordpress/agents/wordpress-performance-specialist.md # wordpress/agents/wordpress-plugin-developer.md # wordpress/skills/branda-menu/SKILL.md # wordpress/skills/crocoblock/SKILL.md # wordpress/skills/elementor/SKILL.md # wordpress/skills/jetengine/SKILL.md # wordpress/skills/rank-math/SKILL.md # wordpress/skills/rank-math/references/commands.md # wordpress/skills/seo-post/SKILL.md # wordpress/skills/woocommerce-cli/SKILL.md # wordpress/skills/woocommerce/SKILL.md # wordpress/skills/wp-cli/SKILL.md # wordpress/skills/wp-cli/references/commands.md # wordpress/skills/wp-cli/scripts/wp-auto.sh # wordpress/skills/wp-dev/SKILL.md # wordpress/skills/wp-hardening/SKILL.md # wordpress/skills/wp-performance/SKILL.md # wordpress/skills/wp-translate/SKILL.md # wordpress/skills/wp-update/SKILL.md
This commit is contained in:
@@ -4,7 +4,6 @@ description: >
|
||||
Mede Core Web Vitals e performance antes/depois de alterações. Detecta regressões.
|
||||
Usar antes e depois de qualquer alteração a WP, WooCommerce, Next.js ou infra.
|
||||
Baseado no gstack /benchmark. Eixo 2B.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /benchmark — Performance Antes/Depois
|
||||
|
||||
@@ -4,7 +4,6 @@ description: >
|
||||
Monitorização pós-deploy — detecta regressões em produção. Verifica que o deploy
|
||||
não quebrou nada crítico nos 15min seguintes. Baseado no gstack /canary. Eixo 2B.
|
||||
Usar após qualquer deploy em produção.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /canary — Monitorização Pós-Deploy
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
name: chrome
|
||||
description: Integração com Chrome para automação browser — navegar páginas, preencher formulários, debug de consola, extracção de dados, testes e screenshots.
|
||||
allowed-tools: Bash, Read, Write, Glob
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /chrome - Chrome Browser Integration
|
||||
@@ -155,4 +154,162 @@ crm.example.com, clica "Adicionar Contacto" e preenche nome, email e telefone.
|
||||
### Escrever em Google Docs
|
||||
```
|
||||
Escreve um resumo do projecto baseado nos commits recentes
|
||||
no Google D
|
||||
no Google Doc docs.google.com/document/d/abc123
|
||||
```
|
||||
|
||||
### Extrair dados de paginas
|
||||
```
|
||||
Vai a pagina de produtos e extrai nome, preco e disponibilidade
|
||||
de cada item. Guarda como CSV.
|
||||
```
|
||||
|
||||
### Workflow multi-site
|
||||
```
|
||||
Verifica o meu calendario para reunioes amanha, depois para cada
|
||||
reuniao com participante externo, pesquisa o site da empresa.
|
||||
```
|
||||
|
||||
### Gravar demo GIF (Chrome extensao)
|
||||
```
|
||||
Grava um GIF mostrando o fluxo de checkout, desde adicionar item
|
||||
ao carrinho ate a pagina de confirmacao.
|
||||
```
|
||||
|
||||
### Performance audit (DevTools MCP)
|
||||
```
|
||||
Abre a pagina example.com, grava um performance trace durante 5 segundos
|
||||
e analisa LCP, TBT e CLS. Sugere melhorias.
|
||||
```
|
||||
|
||||
### Debug network (DevTools MCP)
|
||||
```
|
||||
Abre a pagina do dashboard, monitoriza os requests de API
|
||||
e identifica quais estao a falhar ou demorar mais de 2 segundos.
|
||||
```
|
||||
|
||||
### Inspeccionar acessibilidade (DevTools MCP)
|
||||
```
|
||||
Abre a pagina de contacto e verifica a arvore de acessibilidade.
|
||||
Identifica elementos sem labels ou roles ARIA incorrectos.
|
||||
```
|
||||
|
||||
### Debug CSS (DevTools MCP)
|
||||
```
|
||||
Abre a landing page e inspecciona os estilos computados do hero section.
|
||||
Verifica se o layout esta correcto em diferentes larguras.
|
||||
```
|
||||
|
||||
## Comparacao de Backends
|
||||
|
||||
| Feature | Chrome Extensao | DevTools MCP | Puppeteer MCP | WebFetch |
|
||||
|---------|----------------|--------------|---------------|----------|
|
||||
| Sessoes autenticadas | Sim | Sim (se Chrome aberto) | Nao | Nao |
|
||||
| Janela visivel | Sim | Sim | Opcional | N/A |
|
||||
| Sites privados | Sim (se logado) | Sim (se logado) | Nao | Nao |
|
||||
| Headless | Nao | Opcional | Sim | Sim |
|
||||
| Interaccao UI | Completa | Completa | Completa | Nao |
|
||||
| Screenshots | Sim | Sim | Sim | Nao |
|
||||
| Gravar GIF | Sim | Nao | Nao | Nao |
|
||||
| Console logs | Sim | Sim (filtrados) | Sim | Nao |
|
||||
| Network requests | Nao | Sim (detalhado) | Limitado | Nao |
|
||||
| Performance traces | Nao | Sim (LCP/TBT/CLS) | Nao | Nao |
|
||||
| Acessibilidade | Nao | Sim (a11y tree) | Nao | Nao |
|
||||
| DOM/CSS inspection | Basico | Completo | Basico | Nao |
|
||||
| Storage inspection | Nao | Sim (cookies/LS) | Nao | Nao |
|
||||
| Requer extensao | Sim | Nao | Nao | Nao |
|
||||
| Requer Chrome aberto | Sim | Sim (porta 9222) | Nao | Nao |
|
||||
| Context usage | Alto | Medio | Medio | Baixo |
|
||||
|
||||
**Regra de decisao:**
|
||||
- Precisa de login/sessao + GIF? -> **Chrome Extensao**
|
||||
- Debug/performance/network? -> **DevTools MCP**
|
||||
- Automacao headless CI/CD? -> **Puppeteer MCP**
|
||||
- Apenas ler conteudo publico? -> **WebFetch**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### DevTools MCP nao conecta
|
||||
1. Verificar Chrome lancado com `--remote-debugging-port=9222`
|
||||
2. Testar: `curl http://localhost:9222/json/version`
|
||||
3. Verificar MCP registado: `claude mcp list`
|
||||
4. Reiniciar sessao Claude Code
|
||||
|
||||
### DevTools MCP sem ferramentas
|
||||
1. Verificar: `claude mcp list | grep chrome-devtools`
|
||||
2. Se nao aparece: `claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest`
|
||||
3. Reiniciar sessao Claude Code
|
||||
|
||||
### Extensao nao detectada (Chrome extensao)
|
||||
1. Verificar extensao em `chrome://extensions`
|
||||
2. Verificar versao Claude Code: `claude --version` (>= 2.0.73)
|
||||
3. Confirmar Chrome aberto
|
||||
4. `/chrome` -> "Reconnect extension"
|
||||
5. Reiniciar Chrome E Claude Code
|
||||
|
||||
### Browser nao responde
|
||||
1. Verificar se modal dialog esta a bloquear (alert/confirm/prompt)
|
||||
2. Dispensar dialog manualmente, depois continuar
|
||||
3. Pedir nova tab
|
||||
4. Desactivar/reactivar extensao em `chrome://extensions`
|
||||
|
||||
### Conexao cai em sessoes longas
|
||||
- Service worker do Chrome pode ficar idle
|
||||
- Solucao: `/chrome` -> "Reconnect extension"
|
||||
|
||||
### Erros comuns
|
||||
|
||||
| Erro | Causa | Solucao |
|
||||
|------|-------|---------|
|
||||
| "Browser extension is not connected" | Native host nao alcanca extensao | Reiniciar Chrome + Claude, `/chrome` reconnect |
|
||||
| "Extension not detected" | Extensao nao instalada/desactivada | Instalar/activar em `chrome://extensions` |
|
||||
| "No tab available" | Accao antes de tab pronta | Pedir nova tab e retry |
|
||||
| "Receiving end does not exist" | Service worker idle | `/chrome` -> "Reconnect extension" |
|
||||
|
||||
### Verificar instalacao
|
||||
```bash
|
||||
# Chrome instalado?
|
||||
google-chrome --version
|
||||
|
||||
# Claude Code compativel?
|
||||
claude --version
|
||||
|
||||
# --- DevTools MCP ---
|
||||
# MCP registado?
|
||||
claude mcp list | grep chrome-devtools
|
||||
|
||||
# Chrome com debugging activo?
|
||||
curl -s http://localhost:9222/json/version | head -5
|
||||
|
||||
# --- Chrome Extensao ---
|
||||
# Native host configurado?
|
||||
cat ~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json
|
||||
|
||||
# Host script existe?
|
||||
ls -la ~/.claude/chrome/chrome-native-host
|
||||
```
|
||||
|
||||
## Permissoes de Sites
|
||||
|
||||
Permissoes por site sao geridas na **extensao Chrome** (nao no Claude Code):
|
||||
- Abrir extensao Claude in Chrome -> Settings
|
||||
- Configurar quais sites podem ser acedidos
|
||||
- Bloqueios aplicam-se a todas as sessoes
|
||||
|
||||
## Nota de Performance
|
||||
|
||||
Activar Chrome por defeito **aumenta consumo de context window** porque as ferramentas browser ficam sempre carregadas. Se notar degradacao:
|
||||
1. Desactivar default: `/chrome` -> desactivar
|
||||
2. Usar `claude --chrome` apenas quando necessario
|
||||
3. Preferir WebFetch para leituras simples de paginas publicas
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: db-design
|
||||
description: Design e optimização de schemas de base de dados — normalização, índices, planos de migração e particionamento.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Database Design Specialist
|
||||
@@ -20,8 +19,8 @@ Skill para design e optimização de bases de dados seguindo padrões Descomplic
|
||||
|
||||
### 1. Pesquisa Inicial
|
||||
```
|
||||
mcp__mem_search_memories "database [projecto]"
|
||||
mcp__wikijs__search_pages "database schema [sistema]"
|
||||
mcp__mem0__search_memories "database [projecto]"
|
||||
/knowledge (router Hub QR/PROC) + mcp__mem0__search_memories "database schema [sistema]"
|
||||
```
|
||||
|
||||
### 2. Verificar Schema Existente
|
||||
@@ -189,4 +188,68 @@ Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes data
|
||||
### Como Consultar
|
||||
|
||||
```javascript
|
||||
// Pesquisar optimiza
|
||||
// Pesquisar optimização MySQL
|
||||
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "7f63ec0c-6321-488c-b107-980140199850",
|
||||
query: "mysql index optimization slow query"
|
||||
})
|
||||
|
||||
// Padrões de design de bases de dados
|
||||
mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9",
|
||||
query: "database schema design patterns"
|
||||
})
|
||||
|
||||
// RDS e bases de dados AWS
|
||||
mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "cc7f000a-ad86-49b6-b59b-179e65f8a229",
|
||||
query: "RDS aurora postgresql"
|
||||
})
|
||||
```
|
||||
|
||||
### Quando Consultar
|
||||
|
||||
- Antes de desenhar novo schema
|
||||
- Ao optimizar queries lentas
|
||||
- Para escolher tipo de índice adequado
|
||||
- Decidir entre MySQL/PostgreSQL
|
||||
- Configurar bases de dados em cloud
|
||||
|
||||
---
|
||||
**Versão**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
|
||||
## Quando NÃO Usar
|
||||
|
||||
- Para tarefas fora do domínio de especialização desta skill
|
||||
- Quando outra skill mais específica está disponível
|
||||
- Para operações que requerem confirmação manual do utilizador
|
||||
|
||||
|
||||
## Exemplos
|
||||
|
||||
### Exemplo 1: Uso Básico
|
||||
```
|
||||
Input: [descrição da tarefa]
|
||||
Output: [resultado esperado]
|
||||
```
|
||||
|
||||
### Exemplo 2: Uso Avançado
|
||||
```
|
||||
Input: [caso complexo]
|
||||
Output: [resultado detalhado]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
name: dep-audit
|
||||
description: Auditoria de dependencias para projectos Node.js e PHP — vulnerabilidades, pacotes desactualizados, seguranca de ambiente e verificacao de tipos. Obrigatoria antes de commits.
|
||||
disable-model-invocation: true
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /dep-audit - Dependency Security Audit Pre-Commit
|
||||
@@ -211,4 +210,266 @@ Mitigation: [explanation]
|
||||
Fix critical/high vulnerabilities first. See PROC-DEV-SEC-001 for guidance.
|
||||
```
|
||||
|
||||
### 8. Criar F
|
||||
### 8. Criar Flag
|
||||
|
||||
```bash
|
||||
touch ~/.claude-work/.last-security-audit
|
||||
```
|
||||
|
||||
**Propósito:** Hook pre-git-commit verifica esta flag. Se existe e < 1h, permite commit.
|
||||
|
||||
---
|
||||
|
||||
## Recomendações Específicas
|
||||
|
||||
### Para Vulnerabilidades Transitivas
|
||||
|
||||
**Exemplo: form-data via together-ai**
|
||||
|
||||
```json
|
||||
// package.json
|
||||
{
|
||||
"pnpm": {
|
||||
"overrides": {
|
||||
"form-data": ">=4.0.4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Depois:
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm audit # Verificar se resolveu
|
||||
```
|
||||
|
||||
### Para Dependências Incompatíveis
|
||||
|
||||
**Exemplo: @langchain/core desactualizado**
|
||||
|
||||
```bash
|
||||
# langchain pina versão antiga
|
||||
# Solução: instalar como dependência explícita
|
||||
pnpm add @langchain/core@latest
|
||||
```
|
||||
|
||||
### Para Vulnerabilidades Críticas
|
||||
|
||||
**Workflow:**
|
||||
1. Verificar se há fix disponível
|
||||
2. Se sim: actualizar
|
||||
3. Se não: avaliar alternativas ao package
|
||||
4. Se nenhuma: escalar para Security Compliance Specialist
|
||||
|
||||
---
|
||||
|
||||
## Output Examples
|
||||
|
||||
### Exemplo 1: Clean (0 vulnerabilities)
|
||||
|
||||
```
|
||||
## Security Audit Report
|
||||
|
||||
**Status:** ✅ SAFE
|
||||
**Data:** 2026-02-14 03:00
|
||||
|
||||
| Category | Status |
|
||||
|----------|--------|
|
||||
| Vulnerabilities | 0 (all categories) ✅ |
|
||||
| Outdated Packages | 3 (1 major) |
|
||||
| Environment Safety | ✅ Placeholders only |
|
||||
| Type Safety | ✅ 0 errors |
|
||||
|
||||
### Outdated Packages
|
||||
|
||||
**Framework:**
|
||||
- next: 16.1.6 → 16.2.0 (minor)
|
||||
|
||||
**Action Required:** Optional - update at convenience
|
||||
|
||||
### Safe to Commit?
|
||||
|
||||
✅ **YES** - No security issues found
|
||||
|
||||
Created flag: ~/.claude-work/.last-security-audit
|
||||
```
|
||||
|
||||
### Exemplo 2: Transitivas (precisa overrides)
|
||||
|
||||
```
|
||||
## Security Audit Report
|
||||
|
||||
**Status:** ⚠️ ISSUES FOUND (transitivas)
|
||||
**Data:** 2026-02-14 03:00
|
||||
|
||||
| Category | Status |
|
||||
|----------|--------|
|
||||
| Vulnerabilities | 0 critical, 0 high, 2 moderate, 1 low |
|
||||
| Outdated Packages | 5 (2 major) |
|
||||
| Environment Safety | ✅ Placeholders only |
|
||||
| Type Safety | ✅ 0 errors |
|
||||
|
||||
### Vulnerabilities Detail
|
||||
|
||||
#### Moderate (2)
|
||||
- lodash@4.17.21 (via @platejs/ai)
|
||||
- **Issue:** Prototype pollution
|
||||
- **Patched:** >=4.17.23
|
||||
- **Action:** Override
|
||||
|
||||
- undici@6.22.0 (via @platejs/juice → cheerio)
|
||||
- **Issue:** Resource exhaustion
|
||||
- **Patched:** >=6.23.0
|
||||
- **Action:** Override
|
||||
|
||||
#### Low (1)
|
||||
- cookie@0.6.0 (via @auth/core)
|
||||
- **Issue:** Out of bounds characters
|
||||
- **Patched:** >=0.7.0
|
||||
- **Action:** Override
|
||||
|
||||
### Recommended Fix
|
||||
|
||||
Add to package.json:
|
||||
```json
|
||||
{
|
||||
"pnpm": {
|
||||
"overrides": {
|
||||
"lodash": ">=4.17.23",
|
||||
"undici": ">=6.23.0",
|
||||
"cookie": ">=0.7.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run: `pnpm install && pnpm audit`
|
||||
|
||||
### Safe to Commit?
|
||||
|
||||
⚠️ **YES (with documentation)**
|
||||
|
||||
Document in commit message:
|
||||
- 3 moderate/low vulnerabilities (all transitivas)
|
||||
- Fixed with pnpm.overrides
|
||||
```
|
||||
|
||||
### Exemplo 3: Critical (bloquear commit)
|
||||
|
||||
```
|
||||
## Security Audit Report
|
||||
|
||||
**Status:** ❌ CRITICAL
|
||||
**Data:** 2026-02-14 03:00
|
||||
|
||||
| Category | Status |
|
||||
|----------|--------|
|
||||
| Vulnerabilities | 1 critical, 0 high, 0 moderate, 0 low |
|
||||
| Outdated Packages | 8 (3 major) |
|
||||
| Environment Safety | ✅ Placeholders only |
|
||||
| Type Safety | ✅ 0 errors |
|
||||
|
||||
### Vulnerabilities Detail
|
||||
|
||||
#### Critical (1)
|
||||
- form-data@4.0.3 (via together-ai → @types/node-fetch)
|
||||
- **Issue:** Unsafe random function in boundary selection
|
||||
- **Patched:** >=4.0.4
|
||||
- **Action:** Override OR replace together-ai
|
||||
|
||||
### Immediate Action Required
|
||||
|
||||
**Option 1: Override (quick fix)**
|
||||
```json
|
||||
{
|
||||
"pnpm": {
|
||||
"overrides": {
|
||||
"form-data": ">=4.0.4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2: Evaluate alternatives**
|
||||
- Check if together-ai is essential
|
||||
- Evaluate alternative AI SDKs
|
||||
- Contact Security Compliance Specialist
|
||||
|
||||
### Safe to Commit?
|
||||
|
||||
❌ **NO** - Fix critical vulnerability first
|
||||
|
||||
DO NOT create flag. DO NOT commit.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration
|
||||
|
||||
### Com Hook pre-git-commit
|
||||
|
||||
Hook verifica:
|
||||
```bash
|
||||
~/.claude-work/.last-security-audit
|
||||
```
|
||||
|
||||
Se ficheiro existe e < 1h → permite commit
|
||||
Se não existe ou > 1h → **BLOQUEIA** commit
|
||||
|
||||
### Com /time
|
||||
|
||||
```bash
|
||||
# Workflow típico
|
||||
/time start 1446 # Tarefa Desk
|
||||
# ... fazer alterações ...
|
||||
/dep-audit # Antes de commit
|
||||
git commit
|
||||
/time stop
|
||||
```
|
||||
|
||||
### Com /worklog
|
||||
|
||||
```bash
|
||||
# No worklog, mencionar se audit foi executado
|
||||
/worklog
|
||||
# → Incluirá "Security audit: ✅ 0 vulnerabilities"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Escalação
|
||||
|
||||
| Situação | Escalar Para |
|
||||
|----------|--------------|
|
||||
| Vulnerabilidades críticas não corrigíveis | Security Compliance Specialist |
|
||||
| Dúvidas sobre overrides | Development Lead |
|
||||
| Múltiplas vulnerabilidades altas | /dep-audit + manual review |
|
||||
| Alternativas a packages | Research Analyst |
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- [CLAUDE.md Regra #47](/home/ealmeida/.claude/CLAUDE.md)
|
||||
- [PROC-DEV-SEC-001](/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Seguranca/PROC-DEV-SEC-001-Security-Audit.md)
|
||||
- [Agent dev-helper v2.1](/home/ealmeida/.claude/plugins/marketplaces/descomplicar-plugins/dev-tools/agents/dev-helper.md)
|
||||
- [NPM Audit](https://docs.npmjs.com/cli/v10/commands/npm-audit)
|
||||
- [PNPM Audit](https://pnpm.io/cli/audit)
|
||||
- [Composer Audit](https://getcomposer.org/doc/03-cli.md#audit)
|
||||
|
||||
---
|
||||
|
||||
**Skill v1.1** | 12-03-2026 | Descomplicar® | Renomeado de /security-check para /dep-audit
|
||||
**Security First** - Zero vulnerabilities ou documentadas
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -5,7 +5,6 @@ description: "Gera diagramas de arquitectura, fluxo, ER e sequência em três fo
|
||||
version: "1.0.0"
|
||||
created: 2026-04-04
|
||||
tools: [mcp__claude_ai_Excalidraw__export_to_excalidraw, mcp__mcp-mermaid__generate, Write, Bash]
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill: /diagrama
|
||||
@@ -150,4 +149,119 @@ Usar o MCP `mcp__claude_ai_Excalidraw__export_to_excalidraw` para diagramas no e
|
||||
|
||||
## Geração Mermaid
|
||||
|
||||
Usar o MCP `mcp__mcp-mermaid__generate`
|
||||
Usar o MCP `mcp__mcp-mermaid__generate` para diagramas como código.
|
||||
|
||||
### Tipos suportados
|
||||
|
||||
**Fluxograma:**
|
||||
```
|
||||
flowchart TD
|
||||
A[Início] --> B{Condição}
|
||||
B -->|Sim| C[Acção]
|
||||
B -->|Não| D[Fim]
|
||||
```
|
||||
|
||||
**Sequência:**
|
||||
```
|
||||
sequenceDiagram
|
||||
participant U as Utilizador
|
||||
participant A as Claude Code
|
||||
participant N as n8n
|
||||
U->>A: Pedido
|
||||
A->>N: Trigger workflow
|
||||
N-->>A: Resultado
|
||||
A-->>U: Resposta
|
||||
```
|
||||
|
||||
**ER:**
|
||||
```
|
||||
erDiagram
|
||||
CLIENTE ||--o{ PROJECTO : tem
|
||||
PROJECTO ||--o{ TAREFA : contém
|
||||
TAREFA {
|
||||
int id
|
||||
string nome
|
||||
string estado
|
||||
}
|
||||
```
|
||||
|
||||
**Arquitectura de componentes (C4):**
|
||||
```
|
||||
C4Context
|
||||
title Stack Descomplicar
|
||||
Person(eal, "Emanuel", "Utilizador principal")
|
||||
System(cc, "Claude Code", "Interface interactiva")
|
||||
System(clip, "Paperclip", "Agentes autónomos")
|
||||
System(n8n, "n8n", "Automação determinística")
|
||||
Rel(eal, cc, "usa directamente")
|
||||
Rel(cc, clip, "delega tarefas complexas")
|
||||
Rel(cc, n8n, "activa workflows")
|
||||
```
|
||||
|
||||
### Guardar output
|
||||
|
||||
Guardar o código Mermaid em `/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.mmd` e renderizar para SVG/PNG via MCP.
|
||||
|
||||
---
|
||||
|
||||
## Templates prontos por contexto
|
||||
|
||||
### Arquitectura StackDescomplicar
|
||||
|
||||
Gerar diagrama com as três camadas do stack:
|
||||
- **Camada 1:** Claude Code (trabalho interactivo)
|
||||
- **Camada 2:** n8n (automação determinística)
|
||||
- **Camada 3:** Paperclip (raciocínio autónomo)
|
||||
|
||||
### Proposta comercial
|
||||
|
||||
Diagrama da solução para o cliente com:
|
||||
- Infra-estrutura actual (antes)
|
||||
- Solução proposta (depois)
|
||||
- Componentes e integrações
|
||||
|
||||
### Pipeline de dados
|
||||
|
||||
Diagrama de fluxo com:
|
||||
- Fonte → Processamento → Destino
|
||||
- Triggers, transformações, outputs
|
||||
|
||||
### Diagrama ER Desk CRM
|
||||
|
||||
Entidades principais: Lead → Customer → Estimate → Invoice → Payment
|
||||
|
||||
---
|
||||
|
||||
## Boas práticas
|
||||
|
||||
- **Máx. 10-15 elementos** por diagrama (mais → dividir em sub-diagramas)
|
||||
- **Labels curtos:** 2-4 palavras por elemento
|
||||
- **Setas com label** quando o fluxo não é óbvio
|
||||
- **Cor consistente** por tipo de componente (seguir paleta Descomplicar)
|
||||
- **Nome descritivo** no ficheiro (não "diagrama1.drawio")
|
||||
- **Guardar em Hub/tmp/diagramas/** para fácil acesso
|
||||
|
||||
---
|
||||
|
||||
## Instalar draw.io MCP (opcional, para funcionalidades avançadas)
|
||||
|
||||
O vídeo #210 do Stack_Pesquisa_Videos.md demonstra um MCP draw.io com geração automática a partir de análise de código. Para instalar:
|
||||
|
||||
```bash
|
||||
# Verificar se há MCP draw.io disponível no gateway
|
||||
# Ver: Hub/04-Stack/claude-code-context-hygiene.md → secção MCPs
|
||||
```
|
||||
|
||||
Alternativa: usar draw.io via browser em https://app.diagrams.net (gratuito, sem instalação) e importar o `.drawio` gerado.
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: docx
|
||||
description: "Criação, edição e análise de documentos Word (.docx). Versão light para heartbeats."
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# DOCX — Referência Rápida
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: docx
|
||||
description: "Criacao, edicao e analise de documentos Word (.docx). Usar quando o utilizador mencionar \"Word\", \".docx\", ou pedir documentos profissionais com formatacao (indices, cabecalhos, numeracao de paginas, letterheads). Inclui extracao de conteudo, insercao/substituicao de imagens, find-and-replace, tracked changes, comentarios, e conversao de conteudo para Word. Aplica-se a relatorios, memorandos, cartas, templates e propostas em formato .docx. NAO usar para PDFs, folhas de calculo, Google Docs, ou tarefas de codigo nao relacionadas."
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Criacao, edicao e analise de documentos DOCX
|
||||
@@ -142,4 +141,384 @@ const doc = new Document({
|
||||
```javascript
|
||||
// ERRADO - nunca inserir caracteres de bullet manualmente
|
||||
new Paragraph({ children: [new TextRun("* Item")] }) // MAU
|
||||
new Paragraph({ children: [new TextRun("\u2022 Item")]
|
||||
new Paragraph({ children: [new TextRun("\u2022 Item")] }) // MAU
|
||||
|
||||
// CORRECTO - usar config numbering com LevelFormat.BULLET
|
||||
const doc = new Document({
|
||||
numbering: {
|
||||
config: [
|
||||
{ reference: "bullets",
|
||||
levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022", alignment: AlignmentType.LEFT,
|
||||
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
|
||||
{ reference: "numbers",
|
||||
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
|
||||
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
|
||||
]
|
||||
},
|
||||
sections: [{
|
||||
children: [
|
||||
new Paragraph({ numbering: { reference: "bullets", level: 0 },
|
||||
children: [new TextRun("Item com bullet")] }),
|
||||
new Paragraph({ numbering: { reference: "numbers", level: 0 },
|
||||
children: [new TextRun("Item numerado")] }),
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
// ATENCAO: Cada reference cria numeracao INDEPENDENTE
|
||||
// Mesma reference = continua (1,2,3 depois 4,5,6)
|
||||
// Reference diferente = reinicia (1,2,3 depois 1,2,3)
|
||||
```
|
||||
|
||||
### Tabelas
|
||||
|
||||
**CRITICO: Tabelas precisam de larguras duplas** - definir tanto `columnWidths` na tabela COMO `width` em cada celula. Sem ambos, tabelas renderizam incorrectamente em algumas plataformas.
|
||||
|
||||
```javascript
|
||||
// CRITICO: Definir sempre largura da tabela para renderizacao consistente
|
||||
// CRITICO: Usar ShadingType.CLEAR (nao SOLID) para evitar fundos pretos
|
||||
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
|
||||
const borders = { top: border, bottom: border, left: border, right: border };
|
||||
|
||||
new Table({
|
||||
width: { size: 9026, type: WidthType.DXA }, // Sempre usar DXA (percentagens quebram no Google Docs)
|
||||
columnWidths: [4513, 4513], // Deve somar a largura da tabela (DXA: 1440 = 1 polegada)
|
||||
rows: [
|
||||
new TableRow({
|
||||
children: [
|
||||
new TableCell({
|
||||
borders,
|
||||
width: { size: 4513, type: WidthType.DXA }, // Tambem definir em cada celula
|
||||
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR e nao SOLID
|
||||
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Padding da celula (interno, nao adicionado a largura)
|
||||
children: [new Paragraph({ children: [new TextRun("Celula")] })]
|
||||
})
|
||||
]
|
||||
})
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Calculo de largura da tabela:**
|
||||
|
||||
Usar sempre `WidthType.DXA` — `WidthType.PERCENTAGE` quebra no Google Docs.
|
||||
|
||||
```javascript
|
||||
// Largura da tabela = soma de columnWidths = largura do conteudo
|
||||
// A4 com margens de 1": 11906 - 2880 = 9026 DXA
|
||||
width: { size: 9026, type: WidthType.DXA },
|
||||
columnWidths: [7000, 2026] // Deve somar a largura da tabela
|
||||
```
|
||||
|
||||
**Regras de largura:**
|
||||
- **Usar sempre `WidthType.DXA`** — nunca `WidthType.PERCENTAGE` (incompativel com Google Docs)
|
||||
- Largura da tabela deve igualar a soma de `columnWidths`
|
||||
- `width` da celula deve corresponder ao respectivo `columnWidth`
|
||||
- `margins` da celula sao padding interno - reduzem a area de conteudo, nao adicionam a largura
|
||||
- Para tabelas full-width: usar largura de conteudo (largura pagina menos margens esquerda e direita)
|
||||
|
||||
### Imagens
|
||||
|
||||
```javascript
|
||||
// CRITICO: parametro type e OBRIGATORIO
|
||||
new Paragraph({
|
||||
children: [new ImageRun({
|
||||
type: "png", // Obrigatorio: png, jpg, jpeg, gif, bmp, svg
|
||||
data: fs.readFileSync("image.png"),
|
||||
transformation: { width: 200, height: 150 },
|
||||
altText: { title: "Titulo", description: "Desc", name: "Nome" } // Os tres sao obrigatorios
|
||||
})]
|
||||
})
|
||||
```
|
||||
|
||||
### Quebras de pagina
|
||||
|
||||
```javascript
|
||||
// CRITICO: PageBreak deve estar dentro de um Paragraph
|
||||
new Paragraph({ children: [new PageBreak()] })
|
||||
|
||||
// Ou usar pageBreakBefore
|
||||
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nova pagina")] })
|
||||
```
|
||||
|
||||
### Indice (Table of Contents)
|
||||
|
||||
```javascript
|
||||
// CRITICO: Headings devem usar HeadingLevel APENAS - sem estilos custom
|
||||
new TableOfContents("Indice", { hyperlink: true, headingStyleRange: "1-3" })
|
||||
```
|
||||
|
||||
### Cabecalhos/Rodapes
|
||||
|
||||
```javascript
|
||||
sections: [{
|
||||
properties: {
|
||||
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 polegada
|
||||
},
|
||||
headers: {
|
||||
default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabecalho")] })] })
|
||||
},
|
||||
footers: {
|
||||
default: new Footer({ children: [new Paragraph({
|
||||
children: [new TextRun("Pagina "), new TextRun({ children: [PageNumber.CURRENT] })]
|
||||
})] })
|
||||
},
|
||||
children: [/* conteudo */]
|
||||
}]
|
||||
```
|
||||
|
||||
### Regras criticas para docx-js
|
||||
|
||||
- **Definir tamanho de pagina explicitamente** - docx-js assume A4; para documentos PT/EU, A4 (11906 x 16838 DXA) e o padrao correcto
|
||||
- **Paisagem: passar dimensoes retrato** - docx-js troca largura/altura internamente; passar lado curto como `width`, lado longo como `height`, e definir `orientation: PageOrientation.LANDSCAPE`
|
||||
- **Nunca usar `\n`** - usar elementos Paragraph separados
|
||||
- **Nunca usar bullets unicode** - usar `LevelFormat.BULLET` com config numbering
|
||||
- **PageBreak deve estar em Paragraph** - standalone cria XML invalido
|
||||
- **ImageRun requer `type`** - especificar sempre png/jpg/etc
|
||||
- **Definir sempre `width` da tabela com DXA** - nunca usar `WidthType.PERCENTAGE` (quebra no Google Docs)
|
||||
- **Tabelas precisam de larguras duplas** - array `columnWidths` E `width` da celula, ambos devem corresponder
|
||||
- **Largura tabela = soma de columnWidths** - para DXA, garantir que somam exactamente
|
||||
- **Adicionar sempre margins nas celulas** - usar `margins: { top: 80, bottom: 80, left: 120, right: 120 }` para padding legivel
|
||||
- **Usar `ShadingType.CLEAR`** - nunca SOLID para shading de tabelas
|
||||
- **TOC requer HeadingLevel apenas** - sem estilos custom nos paragrafos de heading
|
||||
- **Override built-in styles** - usar IDs exactos: "Heading1", "Heading2", etc.
|
||||
- **Incluir `outlineLevel`** - necessario para TOC (0 para H1, 1 para H2, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Editar documentos existentes
|
||||
|
||||
**Seguir os 3 passos por ordem.**
|
||||
|
||||
### Passo 1: Descompactar
|
||||
```bash
|
||||
python scripts/office/unpack.py document.docx unpacked/
|
||||
```
|
||||
Extrai XML, pretty-prints, funde runs adjacentes e converte smart quotes para entidades XML (`“` etc.) para sobreviverem a edicao. Usar `--merge-runs false` para saltar a fusao de runs.
|
||||
|
||||
### Passo 2: Editar XML
|
||||
|
||||
Editar ficheiros em `unpacked/word/`. Ver Referencia XML abaixo para padroes.
|
||||
|
||||
**Usar "Claude" como autor** para tracked changes e comentarios, salvo se o utilizador pedir outro nome.
|
||||
|
||||
**Usar a ferramenta Edit directamente para substituicao de strings. Nao escrever scripts Python.** Scripts introduzem complexidade desnecessaria. A ferramenta Edit mostra exactamente o que esta a ser substituido.
|
||||
|
||||
**CRITICO: Usar smart quotes para novo conteudo.** Ao adicionar texto com apostrofos ou aspas, usar entidades XML para produzir smart quotes:
|
||||
```xml
|
||||
<!-- Usar estas entidades para tipografia profissional -->
|
||||
<w:t>Here’s a quote: “Hello”</w:t>
|
||||
```
|
||||
| Entidade | Caractere |
|
||||
|----------|-----------|
|
||||
| `‘` | ' (aspas simples esquerda) |
|
||||
| `’` | ' (aspas simples direita / apostrofo) |
|
||||
| `“` | " (aspas duplas esquerda) |
|
||||
| `”` | " (aspas duplas direita) |
|
||||
|
||||
**Adicionar comentarios:** Usar `comment.py` para tratar boilerplate em multiplos ficheiros XML (texto deve ser XML pre-escaped):
|
||||
```bash
|
||||
python scripts/comment.py unpacked/ 0 "Texto do comentario com & e ’"
|
||||
python scripts/comment.py unpacked/ 1 "Texto de resposta" --parent 0 # resposta ao comentario 0
|
||||
python scripts/comment.py unpacked/ 0 "Texto" --author "Autor Custom" # nome de autor custom
|
||||
```
|
||||
Depois adicionar marcadores ao document.xml (ver Comentarios na Referencia XML).
|
||||
|
||||
### Passo 3: Recompactar
|
||||
```bash
|
||||
python scripts/office/pack.py unpacked/ output.docx --original document.docx
|
||||
```
|
||||
Valida com auto-reparacao, condensa XML e cria DOCX. Usar `--validate false` para saltar.
|
||||
|
||||
**Auto-reparacao corrige:**
|
||||
- `durableId` >= 0x7FFFFFFF (regenera ID valido)
|
||||
- `xml:space="preserve"` em falta em `<w:t>` com whitespace
|
||||
|
||||
**Auto-reparacao nao corrige:**
|
||||
- XML malformado, nesting de elementos invalido, relacoes em falta, violacoes de schema
|
||||
|
||||
### Erros comuns
|
||||
|
||||
- **Substituir elementos `<w:r>` inteiros**: Ao adicionar tracked changes, substituir o bloco `<w:r>...</w:r>` completo com `<w:del>...<w:ins>...` como siblings. Nao injectar tags de tracked change dentro de um run.
|
||||
- **Preservar formatacao `<w:rPr>`**: Copiar o bloco `<w:rPr>` do run original para os runs de tracked change para manter bold, tamanho de fonte, etc.
|
||||
|
||||
---
|
||||
|
||||
## Referencia XML
|
||||
|
||||
### Conformidade com schema
|
||||
|
||||
- **Ordem de elementos em `<w:pPr>`**: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`, `<w:rPr>` por ultimo
|
||||
- **Whitespace**: Adicionar `xml:space="preserve"` a `<w:t>` com espacos no inicio/fim
|
||||
- **RSIDs**: Devem ser hex de 8 digitos (ex: `00AB1234`)
|
||||
|
||||
### Tracked Changes
|
||||
|
||||
**Insercao:**
|
||||
```xml
|
||||
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:t>texto inserido</w:t></w:r>
|
||||
</w:ins>
|
||||
```
|
||||
|
||||
**Eliminacao:**
|
||||
```xml
|
||||
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:delText>texto eliminado</w:delText></w:r>
|
||||
</w:del>
|
||||
```
|
||||
|
||||
**Dentro de `<w:del>`**: Usar `<w:delText>` em vez de `<w:t>`, e `<w:delInstrText>` em vez de `<w:instrText>`.
|
||||
|
||||
**Edicoes minimas** - marcar apenas o que muda:
|
||||
```xml
|
||||
<!-- Alterar "30 dias" para "60 dias" -->
|
||||
<w:r><w:t>O prazo e de </w:t></w:r>
|
||||
<w:del w:id="1" w:author="Claude" w:date="...">
|
||||
<w:r><w:delText>30</w:delText></w:r>
|
||||
</w:del>
|
||||
<w:ins w:id="2" w:author="Claude" w:date="...">
|
||||
<w:r><w:t>60</w:t></w:r>
|
||||
</w:ins>
|
||||
<w:r><w:t> dias.</w:t></w:r>
|
||||
```
|
||||
|
||||
**Eliminar paragrafos/itens de lista inteiros** - ao remover TODO o conteudo de um paragrafo, marcar tambem o paragraph mark como eliminado para fundir com o proximo paragrafo. Adicionar `<w:del/>` dentro de `<w:pPr><w:rPr>`:
|
||||
```xml
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:numPr>...</w:numPr> <!-- numeracao de lista se presente -->
|
||||
<w:rPr>
|
||||
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
|
||||
</w:rPr>
|
||||
</w:pPr>
|
||||
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:delText>Conteudo inteiro do paragrafo a ser eliminado...</w:delText></w:r>
|
||||
</w:del>
|
||||
</w:p>
|
||||
```
|
||||
Sem o `<w:del/>` em `<w:pPr><w:rPr>`, aceitar alteracoes deixa um paragrafo/item de lista vazio.
|
||||
|
||||
**Rejeitar insercao de outro autor** - aninhar eliminacao dentro da insercao:
|
||||
```xml
|
||||
<w:ins w:author="Maria" w:id="5">
|
||||
<w:del w:author="Claude" w:id="10">
|
||||
<w:r><w:delText>texto inserido por ela</w:delText></w:r>
|
||||
</w:del>
|
||||
</w:ins>
|
||||
```
|
||||
|
||||
**Restaurar eliminacao de outro autor** - adicionar insercao depois (nao modificar a eliminacao):
|
||||
```xml
|
||||
<w:del w:author="Maria" w:id="5">
|
||||
<w:r><w:delText>texto eliminado</w:delText></w:r>
|
||||
</w:del>
|
||||
<w:ins w:author="Claude" w:id="10">
|
||||
<w:r><w:t>texto eliminado</w:t></w:r>
|
||||
</w:ins>
|
||||
```
|
||||
|
||||
### Comentarios
|
||||
|
||||
Apos executar `comment.py` (ver Passo 2), adicionar marcadores ao document.xml. Para respostas, usar flag `--parent` e aninhar marcadores dentro dos do pai.
|
||||
|
||||
**CRITICO: `<w:commentRangeStart>` e `<w:commentRangeEnd>` sao siblings de `<w:r>`, nunca dentro de `<w:r>`.**
|
||||
|
||||
```xml
|
||||
<!-- Marcadores de comentario sao filhos directos de w:p, nunca dentro de w:r -->
|
||||
<w:commentRangeStart w:id="0"/>
|
||||
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
|
||||
<w:r><w:delText>eliminado</w:delText></w:r>
|
||||
</w:del>
|
||||
<w:r><w:t> mais texto</w:t></w:r>
|
||||
<w:commentRangeEnd w:id="0"/>
|
||||
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
|
||||
|
||||
<!-- Comentario 0 com resposta 1 aninhada dentro -->
|
||||
<w:commentRangeStart w:id="0"/>
|
||||
<w:commentRangeStart w:id="1"/>
|
||||
<w:r><w:t>texto</w:t></w:r>
|
||||
<w:commentRangeEnd w:id="1"/>
|
||||
<w:commentRangeEnd w:id="0"/>
|
||||
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
|
||||
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
|
||||
```
|
||||
|
||||
### Imagens
|
||||
|
||||
1. Adicionar ficheiro de imagem a `word/media/`
|
||||
2. Adicionar relacao a `word/_rels/document.xml.rels`:
|
||||
```xml
|
||||
<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>
|
||||
```
|
||||
3. Adicionar content type a `[Content_Types].xml`:
|
||||
```xml
|
||||
<Default Extension="png" ContentType="image/png"/>
|
||||
```
|
||||
4. Referenciar no document.xml:
|
||||
```xml
|
||||
<w:drawing>
|
||||
<wp:inline>
|
||||
<wp:extent cx="914400" cy="914400"/> <!-- EMUs: 914400 = 1 polegada -->
|
||||
<a:graphic>
|
||||
<a:graphicData uri=".../picture">
|
||||
<pic:pic>
|
||||
<pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
|
||||
</pic:pic>
|
||||
</a:graphicData>
|
||||
</a:graphic>
|
||||
</wp:inline>
|
||||
</w:drawing>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **pandoc**: Extracao de texto
|
||||
- **docx**: `npm install -g docx` (novos documentos)
|
||||
- **LibreOffice**: Conversao PDF (auto-configurado para ambientes sandbox via `scripts/office/soffice.py`)
|
||||
- **Poppler**: `pdftoppm` para imagens
|
||||
|
||||
---
|
||||
|
||||
## Integracao Descomplicar
|
||||
|
||||
### MCPs disponiveis
|
||||
|
||||
| MCP | Uso |
|
||||
|-----|-----|
|
||||
| `mcp__filesystem__*` | Ler/escrever ficheiros .docx locais, listar directorios |
|
||||
| `mcp__google-workspace__*` | Upload para Google Drive, conversao para Google Docs |
|
||||
| `mcp__ssh-unified__*` | Operacoes em ficheiros .docx em servidores remotos |
|
||||
|
||||
### Workflow tipico
|
||||
|
||||
1. **Criar documento** com docx-js conforme instrucoes acima
|
||||
2. **Validar** com `scripts/office/validate.py`
|
||||
3. **Guardar** via `mcp__filesystem__write_file` ou directamente no path do projecto
|
||||
4. **Upload** (opcional) via `mcp__google-workspace__drive_upload_file` para partilha com cliente
|
||||
|
||||
### Convencoes Descomplicar
|
||||
|
||||
- **Formato de data** em documentos: DD-MM-YYYY (ex: 06-03-2026)
|
||||
- **Formato monetario**: 1.234,56 EUR (separador milhar ponto, decimal virgula)
|
||||
- **Fonte padrao**: Arial 12pt
|
||||
- **Tamanho pagina padrao**: A4 (11906 x 16838 DXA)
|
||||
- **Autor para tracked changes**: "Claude" (salvo indicacao contraria)
|
||||
- **Idioma do documento**: PT-PT salvo indicacao contraria
|
||||
|
||||
---
|
||||
**Versao**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
/home/ealmeida/.claude/plugins/anthropic-claude-code/plugins/frontend-design/skills/frontend-design
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: nextjs
|
||||
description: Desenvolvimento Next.js moderno (13+) com App Router, Server Components, rotas API e deployment seguindo padroes Descomplicar.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /nextjs - Next.js Development
|
||||
@@ -23,20 +22,18 @@ mcp__notebooklm__notebook_query({
|
||||
|
||||
## Regra #48 - Dev Container (OBRIGATÓRIO)
|
||||
|
||||
**TODOS os projectos Next.js devem ser desenvolvidos no container dev.**
|
||||
**TODOS os projectos Next.js são desenvolvidos LOCALMENTE no desktop (regra 48 — CT 102 extinto em 20-04-2026).**
|
||||
|
||||
```
|
||||
SSH: server="dev" (mcp__ssh-unified__ssh_execute)
|
||||
Path: /root/Dev/<projecto>
|
||||
Sync: auto -> /media/ealmeida/Dados/Dev/<projecto> (Syncthing)
|
||||
Ambiente: Bash local no desktop (sem SSH)
|
||||
Path: /media/ealmeida/Dados/Dev/<projecto>
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. `mcp__ssh-unified__ssh_execute server:"dev" command:"mkdir -p /root/Dev/<projecto>"`
|
||||
1. `mkdir -p /media/ealmeida/Dados/Dev/<projecto>` (Bash local)
|
||||
2. Desenvolver e testar no container
|
||||
3. `npm run build` no container antes de deploy
|
||||
4. Deploy via EasyPanel
|
||||
5. Syncthing propaga automaticamente
|
||||
|
||||
**NUNCA:** `npx create-next-app` directamente no PC local para projectos colaborativos.
|
||||
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: pdf
|
||||
description: Processamento de ficheiros PDF — leitura, extracção, merge, split, OCR, formulários. Versão light para heartbeats.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# PDF — Referência Rápida
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: pdf
|
||||
description: Processamento completo de ficheiros PDF — leitura, extraccao de texto/tabelas, merge, split, watermarks, encriptacao, OCR, criacao e preenchimento de formularios.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# PDF Processing Guide
|
||||
@@ -194,4 +193,616 @@ Para texto desenhado com canvas (nao Paragraph), ajustar manualmente o tamanho d
|
||||
pdftotext input.pdf output.txt
|
||||
|
||||
# Extract text preserving layout
|
||||
pdftotext -layout
|
||||
pdftotext -layout input.pdf output.txt
|
||||
|
||||
# Extract specific pages
|
||||
pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5
|
||||
```
|
||||
|
||||
### qpdf
|
||||
```bash
|
||||
# Merge PDFs
|
||||
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
|
||||
|
||||
# Split pages
|
||||
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
|
||||
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
|
||||
|
||||
# Rotate pages
|
||||
qpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees
|
||||
|
||||
# Remove password
|
||||
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
|
||||
```
|
||||
|
||||
### pdftk (if available)
|
||||
```bash
|
||||
# Merge
|
||||
pdftk file1.pdf file2.pdf cat output merged.pdf
|
||||
|
||||
# Split
|
||||
pdftk input.pdf burst
|
||||
|
||||
# Rotate
|
||||
pdftk input.pdf rotate 1east output rotated.pdf
|
||||
```
|
||||
|
||||
## Tarefas comuns
|
||||
|
||||
### Extrair texto de PDFs digitalizados (OCR)
|
||||
```python
|
||||
# Requires: pip install pytesseract pdf2image
|
||||
import pytesseract
|
||||
from pdf2image import convert_from_path
|
||||
|
||||
# Convert PDF to images
|
||||
images = convert_from_path('scanned.pdf')
|
||||
|
||||
# OCR each page
|
||||
text = ""
|
||||
for i, image in enumerate(images):
|
||||
text += f"Page {i+1}:\n"
|
||||
text += pytesseract.image_to_string(image)
|
||||
text += "\n\n"
|
||||
|
||||
print(text)
|
||||
```
|
||||
|
||||
### Adicionar watermark
|
||||
```python
|
||||
from pypdf import PdfReader, PdfWriter
|
||||
|
||||
# Create watermark (or load existing)
|
||||
watermark = PdfReader("watermark.pdf").pages[0]
|
||||
|
||||
# Apply to all pages
|
||||
reader = PdfReader("document.pdf")
|
||||
writer = PdfWriter()
|
||||
|
||||
for page in reader.pages:
|
||||
page.merge_page(watermark)
|
||||
writer.add_page(page)
|
||||
|
||||
with open("watermarked.pdf", "wb") as output:
|
||||
writer.write(output)
|
||||
```
|
||||
|
||||
### Extrair imagens
|
||||
```bash
|
||||
# Using pdfimages (poppler-utils)
|
||||
pdfimages -j input.pdf output_prefix
|
||||
|
||||
# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
|
||||
```
|
||||
|
||||
### Proteccao por password
|
||||
```python
|
||||
from pypdf import PdfReader, PdfWriter
|
||||
|
||||
reader = PdfReader("input.pdf")
|
||||
writer = PdfWriter()
|
||||
|
||||
for page in reader.pages:
|
||||
writer.add_page(page)
|
||||
|
||||
# Add password
|
||||
writer.encrypt("userpassword", "ownerpassword")
|
||||
|
||||
with open("encrypted.pdf", "wb") as output:
|
||||
writer.write(output)
|
||||
```
|
||||
|
||||
## Referencia rapida
|
||||
|
||||
| Tarefa | Melhor ferramenta | Comando/codigo |
|
||||
|--------|-------------------|----------------|
|
||||
| Merge PDFs | pypdf | `writer.add_page(page)` |
|
||||
| Split PDFs | pypdf | One page per file |
|
||||
| Extrair texto | pdfplumber | `page.extract_text()` |
|
||||
| Extrair tabelas | pdfplumber | `page.extract_tables()` |
|
||||
| Criar PDFs | reportlab | Canvas or Platypus |
|
||||
| Merge CLI | qpdf | `qpdf --empty --pages ...` |
|
||||
| OCR scanned PDFs | pytesseract | Convert to image first |
|
||||
| Preencher formularios | pypdf ou annotations | Ver seccao abaixo |
|
||||
|
||||
---
|
||||
|
||||
## Preenchimento de formularios
|
||||
|
||||
**Obrigatorio: seguir estes passos por ordem. Nao saltar para codigo directamente.**
|
||||
|
||||
Primeiro verificar se o PDF tem campos preenchíveis. Executar a partir da pasta de scripts desta skill:
|
||||
`python scripts/check_fillable_fields.py <file.pdf>`
|
||||
|
||||
Consoante o resultado, seguir a seccao "Campos preenchíveis" ou "Campos nao preenchíveis".
|
||||
|
||||
### Campos preenchíveis
|
||||
|
||||
Se o PDF tiver campos de formulario nativos:
|
||||
|
||||
1. Extrair informacao dos campos:
|
||||
`python scripts/extract_form_field_info.py <input.pdf> <field_info.json>`
|
||||
|
||||
O JSON resultante contem campos com esta estrutura:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"field_id": "(ID unico do campo)",
|
||||
"page": "(numero da pagina, 1-based)",
|
||||
"rect": "[left, bottom, right, top]",
|
||||
"type": "text | checkbox | radio_group | choice"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Para **checkboxes**: propriedades `checked_value` e `unchecked_value`.
|
||||
Para **radio groups**: lista `radio_options` com `value` e `rect`.
|
||||
Para **choice fields**: lista `choice_options` com `value` e `text`.
|
||||
|
||||
2. Converter PDF para imagens para analise visual:
|
||||
`python scripts/convert_pdf_to_images.py <file.pdf> <output_directory>`
|
||||
Analisar as imagens para determinar o proposito de cada campo.
|
||||
|
||||
3. Criar `field_values.json`:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"field_id": "last_name",
|
||||
"description": "Apelido do utilizador",
|
||||
"page": 1,
|
||||
"value": "Silva"
|
||||
},
|
||||
{
|
||||
"field_id": "Checkbox12",
|
||||
"description": "Checkbox para maiores de 18",
|
||||
"page": 1,
|
||||
"value": "/On"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
4. Preencher:
|
||||
`python scripts/fill_fillable_fields.py <input.pdf> <field_values.json> <output.pdf>`
|
||||
|
||||
### Campos nao preenchíveis
|
||||
|
||||
Se o PDF nao tiver campos nativos, usar anotacoes de texto. Tentar primeiro extraccao por estrutura (mais preciso), depois estimativa visual como fallback.
|
||||
|
||||
#### Passo 1: extraccao por estrutura
|
||||
|
||||
`python scripts/extract_form_structure.py <input.pdf> form_structure.json`
|
||||
|
||||
Extrai labels de texto, linhas horizontais e checkboxes com coordenadas exactas.
|
||||
|
||||
**Se form_structure.json tiver labels significativos** -> usar abordagem A (estrutura).
|
||||
**Se o PDF for digitalizado/imagem** -> usar abordagem B (visual).
|
||||
|
||||
#### Abordagem A: coordenadas por estrutura (preferida)
|
||||
|
||||
Analisar form_structure.json e identificar:
|
||||
- **Label groups**: elementos de texto adjacentes que formam um label
|
||||
- **Row structure**: labels com `top` similar estao na mesma linha
|
||||
- **Field columns**: areas de entrada comecam apos o label (x0 = label.x1 + gap)
|
||||
- **Checkboxes**: usar coordenadas directamente do JSON
|
||||
|
||||
Criar fields.json com `pdf_width`/`pdf_height`:
|
||||
```json
|
||||
{
|
||||
"pages": [
|
||||
{"page_number": 1, "pdf_width": 612, "pdf_height": 792}
|
||||
],
|
||||
"form_fields": [
|
||||
{
|
||||
"page_number": 1,
|
||||
"description": "Campo apelido",
|
||||
"field_label": "Apelido",
|
||||
"label_bounding_box": [43, 63, 87, 73],
|
||||
"entry_bounding_box": [92, 63, 260, 79],
|
||||
"entry_text": {"text": "Silva", "font_size": 10}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Abordagem B: estimativa visual (fallback)
|
||||
|
||||
1. Converter PDF para imagens:
|
||||
`python scripts/convert_pdf_to_images.py <input.pdf> <images_dir/>`
|
||||
|
||||
2. Identificar campos e posicoes aproximadas nas imagens.
|
||||
|
||||
3. Refinar com zoom (ImageMagick):
|
||||
```bash
|
||||
magick <page_image> -crop <width>x<height>+<x>+<y> +repage <crop_output.png>
|
||||
```
|
||||
|
||||
Converter coordenadas do crop de volta para coordenadas da imagem completa:
|
||||
- full_x = crop_x + crop_offset_x
|
||||
- full_y = crop_y + crop_offset_y
|
||||
|
||||
4. Criar fields.json com `image_width`/`image_height`.
|
||||
|
||||
#### Abordagem hibrida
|
||||
|
||||
Quando a extraccao por estrutura funciona para a maioria dos campos mas falta alguns:
|
||||
1. Usar abordagem A para campos detectados
|
||||
2. Usar abordagem B para campos em falta
|
||||
3. Converter todas as coordenadas para PDF:
|
||||
- pdf_x = image_x * (pdf_width / image_width)
|
||||
- pdf_y = image_y * (pdf_height / image_height)
|
||||
4. Usar sistema de coordenadas unico com `pdf_width`/`pdf_height`
|
||||
|
||||
#### Validacao e preenchimento
|
||||
|
||||
Validar bounding boxes antes de preencher:
|
||||
`python scripts/check_bounding_boxes.py fields.json`
|
||||
|
||||
Preencher o formulario:
|
||||
`python scripts/fill_pdf_form_with_annotations.py <input.pdf> fields.json <output.pdf>`
|
||||
|
||||
Verificar resultado:
|
||||
`python scripts/convert_pdf_to_images.py <output.pdf> <verify_images/>`
|
||||
|
||||
Criar imagem de validacao com bounding boxes sobrepostas:
|
||||
`python scripts/create_validation_image.py <page_number> <fields.json> <input_image> <output_image>`
|
||||
|
||||
---
|
||||
|
||||
## Referencia avancada
|
||||
|
||||
### pypdfium2 — rendering rapido
|
||||
|
||||
```python
|
||||
import pypdfium2 as pdfium
|
||||
from PIL import Image
|
||||
|
||||
# Load PDF
|
||||
pdf = pdfium.PdfDocument("document.pdf")
|
||||
|
||||
# Render page to image
|
||||
page = pdf[0]
|
||||
bitmap = page.render(scale=2.0, rotation=0)
|
||||
img = bitmap.to_pil()
|
||||
img.save("page_1.png", "PNG")
|
||||
|
||||
# Process multiple pages
|
||||
for i, page in enumerate(pdf):
|
||||
bitmap = page.render(scale=1.5)
|
||||
img = bitmap.to_pil()
|
||||
img.save(f"page_{i+1}.jpg", "JPEG", quality=90)
|
||||
```
|
||||
|
||||
### pdfplumber — funcionalidades avancadas
|
||||
|
||||
#### Texto com coordenadas precisas
|
||||
```python
|
||||
import pdfplumber
|
||||
|
||||
with pdfplumber.open("document.pdf") as pdf:
|
||||
page = pdf.pages[0]
|
||||
|
||||
# Extract all text with coordinates
|
||||
chars = page.chars
|
||||
for char in chars[:10]:
|
||||
print(f"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}")
|
||||
|
||||
# Extract text by bounding box (left, top, right, bottom)
|
||||
bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text()
|
||||
```
|
||||
|
||||
#### Tabelas complexas com settings customizados
|
||||
```python
|
||||
import pdfplumber
|
||||
import pandas as pd
|
||||
|
||||
with pdfplumber.open("complex_table.pdf") as pdf:
|
||||
page = pdf.pages[0]
|
||||
|
||||
table_settings = {
|
||||
"vertical_strategy": "lines",
|
||||
"horizontal_strategy": "lines",
|
||||
"snap_tolerance": 3,
|
||||
"intersection_tolerance": 15
|
||||
}
|
||||
tables = page.extract_tables(table_settings)
|
||||
|
||||
# Visual debugging for table extraction
|
||||
img = page.to_image(resolution=150)
|
||||
img.save("debug_layout.png")
|
||||
```
|
||||
|
||||
### reportlab — relatorios profissionais com tabelas
|
||||
|
||||
```python
|
||||
from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph
|
||||
from reportlab.lib.styles import getSampleStyleSheet
|
||||
from reportlab.lib import colors
|
||||
|
||||
data = [
|
||||
['Produto', 'Q1', 'Q2', 'Q3', 'Q4'],
|
||||
['Widgets', '120', '135', '142', '158'],
|
||||
['Gadgets', '85', '92', '98', '105']
|
||||
]
|
||||
|
||||
doc = SimpleDocTemplate("report.pdf")
|
||||
elements = []
|
||||
|
||||
styles = getSampleStyleSheet()
|
||||
title = Paragraph("Relatorio Trimestral de Vendas", styles['Title'])
|
||||
elements.append(title)
|
||||
|
||||
table = Table(data)
|
||||
table.setStyle(TableStyle([
|
||||
('BACKGROUND', (0, 0), (-1, 0), colors.grey),
|
||||
('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
|
||||
('ALIGN', (0, 0), (-1, -1), 'CENTER'),
|
||||
('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
|
||||
('FONTSIZE', (0, 0), (-1, 0), 14),
|
||||
('BOTTOMPADDING', (0, 0), (-1, 0), 12),
|
||||
('BACKGROUND', (0, 1), (-1, -1), colors.beige),
|
||||
('GRID', (0, 0), (-1, -1), 1, colors.black)
|
||||
]))
|
||||
elements.append(table)
|
||||
|
||||
doc.build(elements)
|
||||
```
|
||||
|
||||
### JavaScript — pdf-lib (criacao e modificacao)
|
||||
|
||||
#### Load and Manipulate Existing PDF
|
||||
```javascript
|
||||
import { PDFDocument } from 'pdf-lib';
|
||||
import fs from 'fs';
|
||||
|
||||
async function manipulatePDF() {
|
||||
const existingPdfBytes = fs.readFileSync('input.pdf');
|
||||
const pdfDoc = await PDFDocument.load(existingPdfBytes);
|
||||
|
||||
const pageCount = pdfDoc.getPageCount();
|
||||
const newPage = pdfDoc.addPage([600, 400]);
|
||||
newPage.drawText('Added by pdf-lib', { x: 100, y: 300, size: 16 });
|
||||
|
||||
const pdfBytes = await pdfDoc.save();
|
||||
fs.writeFileSync('modified.pdf', pdfBytes);
|
||||
}
|
||||
```
|
||||
|
||||
#### Advanced Merge and Split
|
||||
```javascript
|
||||
import { PDFDocument } from 'pdf-lib';
|
||||
import fs from 'fs';
|
||||
|
||||
async function mergePDFs() {
|
||||
const mergedPdf = await PDFDocument.create();
|
||||
|
||||
const pdf1 = await PDFDocument.load(fs.readFileSync('doc1.pdf'));
|
||||
const pdf2 = await PDFDocument.load(fs.readFileSync('doc2.pdf'));
|
||||
|
||||
const pdf1Pages = await mergedPdf.copyPages(pdf1, pdf1.getPageIndices());
|
||||
pdf1Pages.forEach(page => mergedPdf.addPage(page));
|
||||
|
||||
const pdf2Pages = await mergedPdf.copyPages(pdf2, [0, 2, 4]);
|
||||
pdf2Pages.forEach(page => mergedPdf.addPage(page));
|
||||
|
||||
fs.writeFileSync('merged.pdf', await mergedPdf.save());
|
||||
}
|
||||
```
|
||||
|
||||
### Operacoes avancadas CLI
|
||||
|
||||
#### poppler-utils
|
||||
```bash
|
||||
# Text with bounding box coordinates
|
||||
pdftotext -bbox-layout document.pdf output.xml
|
||||
|
||||
# High-resolution PNG conversion
|
||||
pdftoppm -png -r 300 document.pdf output_prefix
|
||||
|
||||
# Specific page range with high resolution
|
||||
pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages
|
||||
|
||||
# Extract all embedded images with metadata
|
||||
pdfimages -j -p document.pdf page_images
|
||||
|
||||
# List image info without extracting
|
||||
pdfimages -list document.pdf
|
||||
```
|
||||
|
||||
#### qpdf avancado
|
||||
```bash
|
||||
# Split PDF into groups of pages
|
||||
qpdf --split-pages=3 input.pdf output_group_%02d.pdf
|
||||
|
||||
# Complex page ranges from multiple PDFs
|
||||
qpdf --empty --pages doc1.pdf 1-3 doc2.pdf 5-7 doc3.pdf 2,4 -- combined.pdf
|
||||
|
||||
# Optimize for web (linearize)
|
||||
qpdf --linearize input.pdf optimized.pdf
|
||||
|
||||
# Repair corrupted PDF
|
||||
qpdf --check input.pdf
|
||||
qpdf --fix-qdf damaged.pdf repaired.pdf
|
||||
|
||||
# Advanced encryption with permissions
|
||||
qpdf --encrypt user_pass owner_pass 256 --print=none --modify=none -- input.pdf encrypted.pdf
|
||||
|
||||
# Check encryption status
|
||||
qpdf --show-encryption encrypted.pdf
|
||||
```
|
||||
|
||||
### Processamento em lote com error handling
|
||||
|
||||
```python
|
||||
import os
|
||||
import glob
|
||||
from pypdf import PdfReader, PdfWriter
|
||||
import logging
|
||||
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def batch_process_pdfs(input_dir, operation='merge'):
|
||||
pdf_files = glob.glob(os.path.join(input_dir, "*.pdf"))
|
||||
|
||||
if operation == 'merge':
|
||||
writer = PdfWriter()
|
||||
for pdf_file in pdf_files:
|
||||
try:
|
||||
reader = PdfReader(pdf_file)
|
||||
for page in reader.pages:
|
||||
writer.add_page(page)
|
||||
logger.info(f"Processed: {pdf_file}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to process {pdf_file}: {e}")
|
||||
continue
|
||||
|
||||
with open("batch_merged.pdf", "wb") as output:
|
||||
writer.write(output)
|
||||
|
||||
elif operation == 'extract_text':
|
||||
for pdf_file in pdf_files:
|
||||
try:
|
||||
reader = PdfReader(pdf_file)
|
||||
text = ""
|
||||
for page in reader.pages:
|
||||
text += page.extract_text()
|
||||
|
||||
output_file = pdf_file.replace('.pdf', '.txt')
|
||||
with open(output_file, 'w', encoding='utf-8') as f:
|
||||
f.write(text)
|
||||
logger.info(f"Extracted text from: {pdf_file}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to extract text from {pdf_file}: {e}")
|
||||
continue
|
||||
```
|
||||
|
||||
### Cropping avancado
|
||||
|
||||
```python
|
||||
from pypdf import PdfWriter, PdfReader
|
||||
|
||||
reader = PdfReader("input.pdf")
|
||||
writer = PdfWriter()
|
||||
|
||||
page = reader.pages[0]
|
||||
page.mediabox.left = 50
|
||||
page.mediabox.bottom = 50
|
||||
page.mediabox.right = 550
|
||||
page.mediabox.top = 750
|
||||
|
||||
writer.add_page(page)
|
||||
with open("cropped.pdf", "wb") as output:
|
||||
writer.write(output)
|
||||
```
|
||||
|
||||
### Gestao de memoria para PDFs grandes
|
||||
|
||||
```python
|
||||
def process_large_pdf(pdf_path, chunk_size=10):
|
||||
reader = PdfReader(pdf_path)
|
||||
total_pages = len(reader.pages)
|
||||
|
||||
for start_idx in range(0, total_pages, chunk_size):
|
||||
end_idx = min(start_idx + chunk_size, total_pages)
|
||||
writer = PdfWriter()
|
||||
|
||||
for i in range(start_idx, end_idx):
|
||||
writer.add_page(reader.pages[i])
|
||||
|
||||
with open(f"chunk_{start_idx//chunk_size}.pdf", "wb") as output:
|
||||
writer.write(output)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### PDFs encriptados
|
||||
```python
|
||||
from pypdf import PdfReader
|
||||
|
||||
try:
|
||||
reader = PdfReader("encrypted.pdf")
|
||||
if reader.is_encrypted:
|
||||
reader.decrypt("password")
|
||||
except Exception as e:
|
||||
print(f"Failed to decrypt: {e}")
|
||||
```
|
||||
|
||||
### PDFs corrompidos
|
||||
```bash
|
||||
qpdf --check corrupted.pdf
|
||||
qpdf --replace-input corrupted.pdf
|
||||
```
|
||||
|
||||
### Falha na extraccao de texto (fallback para OCR)
|
||||
```python
|
||||
import pytesseract
|
||||
from pdf2image import convert_from_path
|
||||
|
||||
def extract_text_with_ocr(pdf_path):
|
||||
images = convert_from_path(pdf_path)
|
||||
text = ""
|
||||
for i, image in enumerate(images):
|
||||
text += pytesseract.image_to_string(image)
|
||||
return text
|
||||
```
|
||||
|
||||
## Dicas de performance
|
||||
|
||||
1. **PDFs grandes**: usar streaming em vez de carregar tudo em memoria; `qpdf --split-pages` para dividir
|
||||
2. **Extraccao de texto**: `pdftotext -bbox-layout` e o mais rapido; pdfplumber para tabelas
|
||||
3. **Extraccao de imagens**: `pdfimages` e muito mais rapido que rendering de paginas
|
||||
4. **Preenchimento de formularios**: pdf-lib mantem melhor a estrutura do formulario
|
||||
5. **Memoria**: processar paginas individualmente com pypdfium2 para documentos grandes
|
||||
|
||||
---
|
||||
|
||||
## Integracao Descomplicar
|
||||
|
||||
### Caminhos frequentes para PDFs
|
||||
|
||||
| Localizacao | Caminho |
|
||||
|-------------|---------|
|
||||
| Documentos empresa | `/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/` |
|
||||
| Propostas | `/media/ealmeida/Dados/Hub/03-Propostas/` |
|
||||
| Arquivo clientes | `/media/ealmeida/Dados/GDrive/Arquivo_de_Clientes/` |
|
||||
| Knowledge Base | `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/PDFs/` |
|
||||
| Backups | `/media/ealmeida/Externo/LocalBackups/` (espelhado p/ GDrive via rclone) |
|
||||
| Temporarios | `~/.claude-work/` (limpar ao concluir) |
|
||||
|
||||
### MCPs relevantes
|
||||
|
||||
- **mcp__filesystem__read_file** / **write_file**: ler e escrever PDFs locais
|
||||
- **mcp__filesystem__search_files**: encontrar PDFs no sistema
|
||||
- **mcp__google-workspace__drive_search_files**: encontrar PDFs no Google Drive
|
||||
- **mcp__google-workspace__drive_read_file_content**: ler conteudo de ficheiros no Drive
|
||||
- **mcp__google-workspace__drive_upload_file**: enviar PDFs processados para o Drive
|
||||
|
||||
### Workflow tipico Descomplicar
|
||||
|
||||
1. Localizar PDF (filesystem ou Google Drive)
|
||||
2. Descarregar para `~/.claude-work/` se necessario
|
||||
3. Processar (extrair, merge, split, OCR, etc.)
|
||||
4. Guardar resultado no destino final
|
||||
5. Limpar temporarios de `~/.claude-work/`
|
||||
|
||||
---
|
||||
|
||||
## Licencas das bibliotecas
|
||||
|
||||
- **pypdf**: BSD | **pdfplumber**: MIT | **pypdfium2**: Apache/BSD | **reportlab**: BSD
|
||||
- **poppler-utils**: GPL-2 | **qpdf**: Apache | **pdf-lib**: MIT | **pdfjs-dist**: Apache
|
||||
|
||||
---
|
||||
**Versao**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,8 +1,7 @@
|
||||
---
|
||||
name: php-dev
|
||||
description: Desenvolvimento PHP moderno com Laravel, Symfony e APIs RESTful — autenticação (JWT, OAuth, Sanctum), service classes e refactorização de código legacy seguindo padrões PSR.
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments
|
||||
layer: wiki
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments
|
||||
---
|
||||
|
||||
# PHP Fullstack Engineer
|
||||
@@ -34,7 +33,7 @@ mcp__notebooklm__notebook_query({
|
||||
|
||||
Integrar insights do NotebookLM nas recomendações e decisões.
|
||||
|
||||
> **Regra #48:** Projectos PHP/Laravel/Symfony devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/<projecto>`). Sincroniza automaticamente com o PC local via Syncthing.
|
||||
> **Regra #48:** Projectos PHP/Laravel/Symfony são desenvolvidos **localmente no desktop** em `/media/ealmeida/Dados/Dev/<projecto>` (Bash local, sem SSH — CT 102 extinto em 20-04-2026).
|
||||
|
||||
## Quando Usar
|
||||
|
||||
@@ -48,8 +47,8 @@ Integrar insights do NotebookLM nas recomendações e decisões.
|
||||
|
||||
### 1. Pesquisa Inicial
|
||||
```
|
||||
mcp__mem_search_memories "[keywords php/laravel]"
|
||||
mcp__wikijs__search_pages "[framework] best practices"
|
||||
mcp__mem0__search_memories "[keywords php/laravel]"
|
||||
/knowledge (router Hub QR/PROC) + mcp__mem0__search_memories "[framework] best practices"
|
||||
mcp__context7__get-library-docs para documentação actualizada
|
||||
```
|
||||
|
||||
@@ -202,3 +201,206 @@ class ProductService
|
||||
}
|
||||
|
||||
public function create(array $data): Product
|
||||
{
|
||||
return $this->repository->create($data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Repository
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace App\Repositories;
|
||||
|
||||
use App\Models\Product;
|
||||
use Illuminate\Pagination\LengthAwarePaginator;
|
||||
|
||||
/**
|
||||
* ProductRepository - Acesso a dados Produtos
|
||||
*
|
||||
* @author Descomplicar® Crescimento Digital
|
||||
* @link https://descomplicar.pt
|
||||
* @copyright 2025 Descomplicar®
|
||||
*/
|
||||
class ProductRepository
|
||||
{
|
||||
public function paginate(array $filters = []): LengthAwarePaginator
|
||||
{
|
||||
return Product::query()
|
||||
->when($filters['category'] ?? null, fn($q, $cat) => $q->where('category_id', $cat))
|
||||
->when($filters['active'] ?? null, fn($q, $active) => $q->where('active', $active))
|
||||
->orderBy('created_at', 'desc')
|
||||
->paginate($filters['per_page'] ?? 15);
|
||||
}
|
||||
|
||||
public function create(array $data): Product
|
||||
{
|
||||
return Product::create($data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging PHP
|
||||
|
||||
### Xdebug
|
||||
|
||||
```php
|
||||
// php.ini
|
||||
zend_extension=xdebug.so
|
||||
xdebug.mode=debug
|
||||
xdebug.start_with_request=yes
|
||||
xdebug.client_host=127.0.0.1
|
||||
xdebug.client_port=9003
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
```php
|
||||
// Monolog exemplo
|
||||
use Monolog\Logger;
|
||||
use Monolog\Handler\StreamHandler;
|
||||
|
||||
$log = new Logger('app');
|
||||
$log->pushHandler(new StreamHandler('logs/app.log', Logger::DEBUG));
|
||||
|
||||
$log->info('User logged in', ['user_id' => $userId]);
|
||||
$log->error('Database error', ['exception' => $e->getMessage()]);
|
||||
```
|
||||
|
||||
### Profiling
|
||||
|
||||
```bash
|
||||
# Com Blackfire
|
||||
blackfire run php script.php
|
||||
|
||||
# Com Xhprof
|
||||
php -d extension=xhprof.so script.php
|
||||
```
|
||||
|
||||
## Testes Unitários
|
||||
|
||||
### PHPUnit
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class ProductServiceTest extends TestCase
|
||||
{
|
||||
private ProductService $service;
|
||||
|
||||
protected function setUp(): void
|
||||
{
|
||||
$this->service = new ProductService(
|
||||
new InMemoryProductRepository()
|
||||
);
|
||||
}
|
||||
|
||||
public function test_create_product(): void
|
||||
{
|
||||
$product = $this->service->create([
|
||||
'name' => 'Test Product',
|
||||
'price' => 99.99
|
||||
]);
|
||||
|
||||
$this->assertInstanceOf(Product::class, $product);
|
||||
$this->assertEquals('Test Product', $product->name);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pest (alternativa moderna)
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
test('creates product', function () {
|
||||
$product = app(ProductService::class)->create([
|
||||
'name' => 'Test',
|
||||
'price' => 99.99
|
||||
]);
|
||||
|
||||
expect($product)
|
||||
->toBeInstanceOf(Product::class)
|
||||
->name->toBe('Test');
|
||||
});
|
||||
```
|
||||
|
||||
## Checklist Entrega
|
||||
|
||||
- [ ] Assinatura Descomplicar® em todos os ficheiros
|
||||
- [ ] php -l sem erros
|
||||
- [ ] PHPDoc em funções públicas
|
||||
- [ ] Type hints completos
|
||||
- [ ] PSR-12 compliant
|
||||
- [ ] Segurança validada (injection, XSS)
|
||||
- [ ] Se API: documentação endpoints
|
||||
- [ ] Testes unitários (cobertura >70%)
|
||||
|
||||
---
|
||||
|
||||
## Datasets Dify (Consulta Obrigatória)
|
||||
|
||||
Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes datasets via MCP:
|
||||
|
||||
| Dataset | ID | Prioridade |
|
||||
|---------|----|-----------:|
|
||||
| **TI (Tecnologia da Informação)** | `7f63ec0c-6321-488c-b107-980140199850` | 1 |
|
||||
| **Desenvolvimento de Software** | `e7c7decc-0ded-4351-ab14-b110b3c38ec9` | 1 |
|
||||
| **Wordpress** | `9da0b2b9-5051-4b99-b9f6-20bf35067092` | 2 |
|
||||
| **PerfexCRM** | `43354eb6-f0b2-40cc-aa53-44e375ab347c` | 3 |
|
||||
|
||||
### Como Consultar
|
||||
|
||||
```javascript
|
||||
# PRIMARIO: NotebookLM (Gemini 2.5 RAG)
|
||||
# mcp__notebooklm__notebook_query({notebook_id: "2876d1fe-5cea-4d98-8140-b0e1a81c6bc4", query: "<tema>"}) // Claude Code
|
||||
# mcp__notebooklm__notebook_query({notebook_id: "73102308-70ef-403e-9be9-eae0cfc62d55", query: "<tema>"}) // Desenvolvimento de MCPs
|
||||
# mcp__notebooklm__notebook_query({notebook_id: "57d9c6c9-48ba-4d83-8f71-cc890f348a53", query: "<tema>"}) // AI Code Editors
|
||||
# mcp__notebooklm__notebook_query({notebook_id: "24947ffa-0019-448a-a340-2f4a275d2eb1", query: "<tema>"}) // Programacao
|
||||
# mcp__notebooklm__notebook_query({notebook_id: "ebee9fe1-78fd-4f85-8938-f19f3ea32131", query: "<tema>"}) // Obsidian + Claude
|
||||
# FALLBACK: Dify KB (se NotebookLM insuficiente)
|
||||
|
||||
// Pesquisar padrões Laravel
|
||||
mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9",
|
||||
query: "laravel service repository pattern"
|
||||
})
|
||||
|
||||
// APIs e autenticação
|
||||
mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "7f63ec0c-6321-488c-b107-980140199850",
|
||||
query: "api rest jwt sanctum"
|
||||
})
|
||||
|
||||
// Desenvolvimento Perfex
|
||||
mcp__dify-kb__dify_kb_retrieve_segments({
|
||||
dataset_id: "43354eb6-f0b2-40cc-aa53-44e375ab347c",
|
||||
query: "module development hooks"
|
||||
})
|
||||
```
|
||||
|
||||
### Quando Consultar
|
||||
|
||||
- Implementar padrões de arquitectura
|
||||
- Desenvolver APIs RESTful
|
||||
- Integrar sistemas de autenticação
|
||||
- Criar módulos Perfex CRM
|
||||
- Refactorizar código legacy
|
||||
|
||||
---
|
||||
**Versão**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,8 +1,7 @@
|
||||
---
|
||||
name: prompt-refine
|
||||
description: Transforma um pedido vago em prompt de excelência — especificação detalhada, inequívoca e estruturada para agentes de IA. Usar quando "refinar prompt", "melhorar prompt", "engenharia de prompts", "prompt para agente", "estruturar instrução IA", "prompt engineering".
|
||||
allowed-tools: Read, Write, mcp__mem_search_memories
|
||||
layer: wiki
|
||||
allowed-tools: Read, Write, mcp__mem0__search_memories
|
||||
---
|
||||
|
||||
# /prompt-refine — Engenharia de Prompts
|
||||
@@ -21,7 +20,7 @@ Transforma um pedido em linguagem natural num **prompt de excelência** pronto p
|
||||
### 1. Pesquisar contexto relevante
|
||||
|
||||
```
|
||||
mcp__mem_search_memories "<palavras-chave do pedido>"
|
||||
mcp__mem0__search_memories "<palavras-chave do pedido>"
|
||||
```
|
||||
|
||||
Verificar se há padrões ou decisões anteriores relacionadas.
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: react-patterns
|
||||
description: Padroes modernos React (18+/19) -- hooks, context, composicao, memoizacao, lazy loading e Server Components.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# React Patterns
|
||||
@@ -23,7 +22,7 @@ mcp__notebooklm__notebook_query({
|
||||
})
|
||||
```
|
||||
|
||||
> **Regra #48:** Projectos React devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/<projecto>`). Sincroniza via Syncthing.
|
||||
> **Regra #48:** Projectos React são desenvolvidos **localmente no desktop** em `/media/ealmeida/Dados/Dev/<projecto>` (Bash local, sem SSH — CT 102 extinto em 20-04-2026).
|
||||
|
||||
## Quando Usar
|
||||
|
||||
@@ -178,4 +177,27 @@ components/
|
||||
ui/ # Componentes base (Button, Input, Card)
|
||||
features/ # Componentes feature-specific
|
||||
layouts/ # Layout components
|
||||
providers/ # Context
|
||||
providers/ # Context providers
|
||||
|
||||
hooks/
|
||||
useAuth.ts
|
||||
useLocalStorage.ts
|
||||
useDebounce.ts
|
||||
```
|
||||
|
||||
## Referencias
|
||||
|
||||
- `references/composition-patterns.md` - Compound components, providers, dependency injection (Vercel Engineering)
|
||||
- `references/custom-hooks.md` - useDebounce, useLocalStorage, useFetch com codigo completo
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Criar, melhorar e empacotar skills para o sistema de plugins Descomplicar. Usar quando o utilizador pede para criar uma nova skill, actualizar uma skill existente, ou quando é necessário estruturar conhecimento especializado em formato skill. Inclui padrões Anthropic oficiais (progressive disclosure, graus de liberdade) adaptados ao ecossistema Descomplicar com PT-PT estrito.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
@@ -137,4 +136,65 @@ Calibrar o nível de especificidade ao risco da tarefa:
|
||||
- [ ] Scripts testados (se incluídos)
|
||||
- [ ] Sem ficheiros auxiliares (README.md, CHANGELOG.md, etc.)
|
||||
|
||||
**Padrões Descompl
|
||||
**Padrões Descomplicar:**
|
||||
- [ ] Assinatura Descomplicar® no código (quando aplicável)
|
||||
- [ ] MCPs relevantes referenciados
|
||||
- [ ] Monetário em EUR sem casas decimais desnecessárias
|
||||
|
||||
---
|
||||
|
||||
### Passo 6: Empacotar
|
||||
|
||||
**Script de packaging Anthropic** (quando disponível):
|
||||
```bash
|
||||
python scripts/package_skill.py <path/para/pasta-skill>
|
||||
# ou com output directory:
|
||||
python scripts/package_skill.py <path/para/pasta-skill> ./dist
|
||||
```
|
||||
|
||||
O script valida frontmatter, naming conventions, estrutura de directórios, e gera ficheiro `.skill` (zip com extensão .skill).
|
||||
|
||||
Se não estiver disponível, verificar manualmente com o checklist do Passo 5.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Padrões a Evitar
|
||||
|
||||
**Má skill (demasiado vaga):**
|
||||
```yaml
|
||||
description: Ajuda com PHP.
|
||||
```
|
||||
|
||||
**Má skill (conteúdo duplicado em references e SKILL.md):**
|
||||
Documentar a mesma informação em dois locais — viola o princípio progressive disclosure.
|
||||
|
||||
**Má skill (ficheiros auxiliares):**
|
||||
Criar README.md, CHANGELOG.md, INSTALLATION_GUIDE.md — não devem existir numa skill.
|
||||
|
||||
**Boa skill:**
|
||||
```yaml
|
||||
description: >
|
||||
Desenvolvimento PHP moderno com Laravel e Symfony — autenticação JWT/OAuth,
|
||||
service classes, refactorização legacy. Usar quando: (1) criar APIs RESTful,
|
||||
(2) implementar autenticação, (3) desenvolver service classes, (4) refactorizar
|
||||
código PHP existente.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplos Concretos: Bom vs Mau
|
||||
|
||||
Ver `references/anthropic-patterns.md` para exemplos detalhados de progressive disclosure.
|
||||
Ver `references/descomplicar-standards.md` para exemplos de skills Descomplicar bem estruturadas.
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -35,7 +35,7 @@ description: >
|
||||
name: nome-da-skill
|
||||
description: >
|
||||
Descrição da skill. Usar quando [contexto].
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories
|
||||
---
|
||||
```
|
||||
|
||||
@@ -120,10 +120,10 @@ Para skills que aprendem com execuções anteriores:
|
||||
## Memória
|
||||
|
||||
Pesquisar experiência anterior antes de começar:
|
||||
`mcp__mem_search_memories "[keywords relevantes]"`
|
||||
`mcp__mem0__search_memories "[keywords relevantes]"`
|
||||
|
||||
Guardar aprendizagens ao concluir:
|
||||
`mcp__mem_save_memory { text: "[domínio/skill] ..." }`
|
||||
`mcp__mem0__save_memory { content: "...", tags: ["domínio", "skill"] }`
|
||||
```
|
||||
|
||||
---
|
||||
@@ -213,7 +213,7 @@ O Anthropic define apenas `name` e `description` como obrigatórios. O sistema D
|
||||
name: nome-da-skill
|
||||
description: >
|
||||
Descrição completa com triggers.
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__notebooklm__notebook_query
|
||||
allowed-tools: Read, Write, Edit, Bash, mcp__mem0__search_memories, mcp__notebooklm__notebook_query
|
||||
---
|
||||
```
|
||||
|
||||
@@ -292,7 +292,7 @@ description: >
|
||||
|
||||
## Protocolo obrigatório
|
||||
|
||||
1. Pesquisar memória: `mcp__mem_search_memories "[keywords]"`
|
||||
1. Pesquisar memória: `mcp__mem0__search_memories "[keywords]"`
|
||||
2. Consultar NotebookLM: ver tabela em references/notebooklm-context.md
|
||||
3. Implementar com padrões Laravel: ver references/laravel-patterns.md
|
||||
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: webapp-testing
|
||||
description: Testes e automacao de aplicacoes web locais com Playwright — verificacao de frontend, debug de UI, screenshots, logs de consola e gestao de ciclo de vida de servidores.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Web Application Testing
|
||||
@@ -114,4 +113,46 @@ with sync_playwright() as p:
|
||||
|
||||
| MCP | Uso com webapp-testing |
|
||||
|-----|----------------------|
|
||||
| `chrome-devtools` | Performance traces, network inspection
|
||||
| `chrome-devtools` | Performance traces, network inspection, DOM/CSS debugging — usar via skill /chrome |
|
||||
| `claude-in-chrome` | Testes em sites autenticados com sessao activa — usar via skill /chrome |
|
||||
| `lighthouse` | Auditorias completas de performance, SEO, a11y — complementa testes Playwright |
|
||||
| `puppeteer` | Alternativa headless para automacao simples sem Playwright |
|
||||
|
||||
### Workflow tipico Descomplicar
|
||||
|
||||
1. **Desenvolvimento local**: Playwright (esta skill) para testes funcionais headless
|
||||
2. **Debug visual**: /chrome (DevTools MCP) para inspeccao DOM/CSS/network em tempo real
|
||||
3. **Performance**: /chrome (DevTools MCP traces) + MCP lighthouse para auditorias
|
||||
4. **CI/CD**: Scripts Playwright commitados no repositorio, executados em pipeline Gitea Actions
|
||||
|
||||
### Executar no servidor dev (regra #48)
|
||||
|
||||
Para testes que requerem Node.js/Python:
|
||||
```bash
|
||||
# Via SSH MCP para o servidor dev
|
||||
cd /media/ealmeida/Dados/Dev/projecto && python test_automation.py # Bash local no desktop
|
||||
```
|
||||
|
||||
### Instalacao Playwright (se necessario)
|
||||
|
||||
```bash
|
||||
pip install playwright
|
||||
playwright install chromium
|
||||
```
|
||||
|
||||
No desktop, Playwright está disponível nos projectos em `/media/ealmeida/Dados/Dev`.
|
||||
|
||||
---
|
||||
**Versao**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
name: xlsx
|
||||
description: Criacao, edicao e analise de ficheiros Excel (.xlsx, .xlsm, .csv, .tsv) — formulas, formatacao, modelos financeiros e integracao com facturacao Moloni.
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Excel / XLSX Specialist
|
||||
@@ -131,4 +130,257 @@ df.describe() # Estatisticas
|
||||
df.to_excel('output.xlsx', index=False)
|
||||
```
|
||||
|
||||
#
|
||||
## Workflows Excel
|
||||
|
||||
## CRITICO: Usar formulas, NAO valores hardcoded
|
||||
|
||||
**Usar SEMPRE formulas Excel em vez de calcular valores em Python e hardcoda-los.** Isto garante que a folha permanece dinamica e actualizavel.
|
||||
|
||||
### ERRADO - Hardcoding de valores calculados
|
||||
```python
|
||||
# Mau: calcular em Python e hardcodar resultado
|
||||
total = df['Vendas'].sum()
|
||||
sheet['B10'] = total # Hardcoda 5000
|
||||
|
||||
# Mau: calcular taxa de crescimento em Python
|
||||
growth = (df.iloc[-1]['Receita'] - df.iloc[0]['Receita']) / df.iloc[0]['Receita']
|
||||
sheet['C5'] = growth # Hardcoda 0.15
|
||||
|
||||
# Mau: calculo Python para media
|
||||
avg = sum(values) / len(values)
|
||||
sheet['D20'] = avg # Hardcoda 42.5
|
||||
```
|
||||
|
||||
### CORRECTO - Usar formulas Excel
|
||||
```python
|
||||
# Bom: deixar Excel calcular a soma
|
||||
sheet['B10'] = '=SUM(B2:B9)'
|
||||
|
||||
# Bom: taxa de crescimento como formula Excel
|
||||
sheet['C5'] = '=(C4-C2)/C2'
|
||||
|
||||
# Bom: media usando funcao Excel
|
||||
sheet['D20'] = '=AVERAGE(D2:D19)'
|
||||
```
|
||||
|
||||
Isto aplica-se a TODOS os calculos - totais, percentagens, racios, diferencas, etc. A folha deve poder recalcular quando os dados de origem mudam.
|
||||
|
||||
## Workflow comum
|
||||
1. **Escolher ferramenta**: pandas para dados, openpyxl para formulas/formatacao
|
||||
2. **Criar/Carregar**: Criar novo workbook ou carregar ficheiro existente
|
||||
3. **Modificar**: Adicionar/editar dados, formulas e formatacao
|
||||
4. **Guardar**: Escrever para ficheiro
|
||||
5. **Recalcular formulas (OBRIGATORIO SE USAR FORMULAS)**: Usar o script scripts/recalc.py
|
||||
```bash
|
||||
python scripts/recalc.py output.xlsx
|
||||
```
|
||||
6. **Verificar e corrigir erros**:
|
||||
- O script retorna JSON com detalhes de erros
|
||||
- Se `status` for `errors_found`, verificar `error_summary` para tipos e localizacoes
|
||||
- Corrigir os erros identificados e recalcular novamente
|
||||
- Erros comuns a corrigir:
|
||||
- `#REF!`: Referencias de celula invalidas
|
||||
- `#DIV/0!`: Divisao por zero
|
||||
- `#VALUE!`: Tipo de dados errado na formula
|
||||
- `#NAME?`: Nome de formula nao reconhecido
|
||||
|
||||
### Criar novos ficheiros Excel
|
||||
|
||||
```python
|
||||
# Usando openpyxl para formulas e formatacao
|
||||
from openpyxl import Workbook
|
||||
from openpyxl.styles import Font, PatternFill, Alignment
|
||||
|
||||
wb = Workbook()
|
||||
sheet = wb.active
|
||||
|
||||
# Adicionar dados
|
||||
sheet['A1'] = 'Descricao'
|
||||
sheet['B1'] = 'Valor'
|
||||
sheet.append(['Linha', 'de', 'dados'])
|
||||
|
||||
# Adicionar formula
|
||||
sheet['B2'] = '=SUM(A1:A10)'
|
||||
|
||||
# Formatacao
|
||||
sheet['A1'].font = Font(bold=True, color='FF0000')
|
||||
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
|
||||
sheet['A1'].alignment = Alignment(horizontal='center')
|
||||
|
||||
# Largura da coluna
|
||||
sheet.column_dimensions['A'].width = 20
|
||||
|
||||
wb.save('output.xlsx')
|
||||
```
|
||||
|
||||
### Editar ficheiros Excel existentes
|
||||
|
||||
```python
|
||||
# Usando openpyxl para preservar formulas e formatacao
|
||||
from openpyxl import load_workbook
|
||||
|
||||
# Carregar ficheiro existente
|
||||
wb = load_workbook('existente.xlsx')
|
||||
sheet = wb.active # ou wb['NomeFolha'] para folha especifica
|
||||
|
||||
# Trabalhar com multiplas folhas
|
||||
for sheet_name in wb.sheetnames:
|
||||
sheet = wb[sheet_name]
|
||||
print(f"Folha: {sheet_name}")
|
||||
|
||||
# Modificar celulas
|
||||
sheet['A1'] = 'Novo Valor'
|
||||
sheet.insert_rows(2) # Inserir linha na posicao 2
|
||||
sheet.delete_cols(3) # Eliminar coluna 3
|
||||
|
||||
# Adicionar nova folha
|
||||
new_sheet = wb.create_sheet('NovaFolha')
|
||||
new_sheet['A1'] = 'Dados'
|
||||
|
||||
wb.save('modificado.xlsx')
|
||||
```
|
||||
|
||||
## Recalcular formulas
|
||||
|
||||
Ficheiros Excel criados ou modificados com openpyxl contem formulas como strings mas nao valores calculados. Usar o script `scripts/recalc.py` para recalcular formulas:
|
||||
|
||||
```bash
|
||||
python scripts/recalc.py <ficheiro_excel> [timeout_segundos]
|
||||
```
|
||||
|
||||
Exemplo:
|
||||
```bash
|
||||
python scripts/recalc.py output.xlsx 30
|
||||
```
|
||||
|
||||
O script:
|
||||
- Configura automaticamente a macro LibreOffice na primeira execucao
|
||||
- Recalcula todas as formulas em todas as folhas
|
||||
- Analisa TODAS as celulas a procura de erros Excel (#REF!, #DIV/0!, etc.)
|
||||
- Retorna JSON com localizacoes e contagens detalhadas de erros
|
||||
- Funciona em Linux e macOS
|
||||
|
||||
## Checklist de verificacao de formulas
|
||||
|
||||
Verificacoes rapidas para garantir que as formulas funcionam correctamente:
|
||||
|
||||
### Verificacao essencial
|
||||
- [ ] **Testar 2-3 referencias exemplo**: Verificar que obtem valores correctos antes de construir modelo completo
|
||||
- [ ] **Mapeamento de colunas**: Confirmar que colunas Excel correspondem (ex.: coluna 64 = BL, nao BK)
|
||||
- [ ] **Offset de linhas**: Lembrar que linhas Excel sao 1-indexed (DataFrame linha 5 = Excel linha 6)
|
||||
|
||||
### Armadilhas comuns
|
||||
- [ ] **Tratamento de NaN**: Verificar valores nulos com `pd.notna()`
|
||||
- [ ] **Colunas distantes**: Dados FY frequentemente em colunas 50+
|
||||
- [ ] **Multiplas correspondencias**: Pesquisar todas as ocorrencias, nao apenas a primeira
|
||||
- [ ] **Divisao por zero**: Verificar denominadores antes de usar `/` em formulas (#DIV/0!)
|
||||
- [ ] **Referencias erradas**: Verificar que todas as referencias apontam para celulas pretendidas (#REF!)
|
||||
- [ ] **Referencias entre folhas**: Usar formato correcto (Folha1!A1) para ligar folhas
|
||||
|
||||
### Estrategia de teste de formulas
|
||||
- [ ] **Comecar pequeno**: Testar formulas em 2-3 celulas antes de aplicar amplamente
|
||||
- [ ] **Verificar dependencias**: Confirmar que todas as celulas referenciadas existem
|
||||
- [ ] **Testar edge cases**: Incluir zero, negativos e valores muito grandes
|
||||
|
||||
### Interpretar output do scripts/recalc.py
|
||||
O script retorna JSON com detalhes de erros:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"total_errors": 0,
|
||||
"total_formulas": 42,
|
||||
"error_summary": {
|
||||
"#REF!": {
|
||||
"count": 2,
|
||||
"locations": ["Folha1!B5", "Folha1!C10"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Boas praticas
|
||||
|
||||
### Seleccao de biblioteca
|
||||
- **pandas**: Melhor para analise de dados, operacoes em massa e exportacao simples
|
||||
- **openpyxl**: Melhor para formatacao complexa, formulas e funcionalidades especificas do Excel
|
||||
|
||||
### Trabalhar com openpyxl
|
||||
- Indices de celula sao 1-based (row=1, column=1 refere-se a celula A1)
|
||||
- Usar `data_only=True` para ler valores calculados: `load_workbook('ficheiro.xlsx', data_only=True)`
|
||||
- **Atencao**: Se aberto com `data_only=True` e guardado, as formulas sao substituidas por valores e perdidas permanentemente
|
||||
- Para ficheiros grandes: Usar `read_only=True` para leitura ou `write_only=True` para escrita
|
||||
- Formulas sao preservadas mas nao avaliadas — usar scripts/recalc.py para actualizar valores
|
||||
|
||||
### Trabalhar com pandas
|
||||
- Especificar tipos de dados para evitar problemas de inferencia: `pd.read_excel('ficheiro.xlsx', dtype={'id': str})`
|
||||
- Para ficheiros grandes, ler colunas especificas: `pd.read_excel('ficheiro.xlsx', usecols=['A', 'C', 'E'])`
|
||||
- Tratar datas correctamente: `pd.read_excel('ficheiro.xlsx', parse_dates=['coluna_data'])`
|
||||
|
||||
## Estilo de codigo
|
||||
**IMPORTANTE**: Ao gerar codigo Python para operacoes Excel:
|
||||
- Escrever codigo Python minimo e conciso sem comentarios desnecessarios
|
||||
- Evitar nomes de variaveis verbosos e operacoes redundantes
|
||||
- Evitar print statements desnecessarios
|
||||
|
||||
**Para os ficheiros Excel em si**:
|
||||
- Adicionar comentarios em celulas com formulas complexas ou pressupostos importantes
|
||||
- Documentar fontes de dados para valores hardcoded
|
||||
- Incluir notas para calculos-chave e seccoes do modelo
|
||||
|
||||
---
|
||||
|
||||
## Integracao Descomplicar
|
||||
|
||||
### Acesso a ficheiros via MCP filesystem
|
||||
```python
|
||||
# Ler ficheiros do sistema local
|
||||
mcp__filesystem__read_file(path="/media/ealmeida/Dados/...")
|
||||
|
||||
# Listar ficheiros para encontrar spreadsheets
|
||||
mcp__filesystem__list_directory(path="/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/")
|
||||
```
|
||||
|
||||
### Integracao com Moloni (facturacao)
|
||||
Para exportar dados de facturacao Moloni para Excel:
|
||||
```python
|
||||
# Obter facturas do Moloni
|
||||
mcp__moloni__moloni_documents_invoices_getall(company_id=..., year=2026)
|
||||
|
||||
# Obter produtos
|
||||
mcp__moloni__moloni_products_products_getall(company_id=..., category_id=...)
|
||||
|
||||
# Obter clientes
|
||||
mcp__moloni__moloni_entities_customers_getall(company_id=...)
|
||||
```
|
||||
|
||||
### Integracao com Desk CRM
|
||||
Para exportar dados do CRM para Excel:
|
||||
```python
|
||||
# Relatorio de clientes
|
||||
mcp__desk-crm-v3__get_customers(limit=100)
|
||||
|
||||
# Relatorio de facturas
|
||||
mcp__desk-crm-v3__invoice_analytics(period="this_year")
|
||||
|
||||
# Relatorio de despesas
|
||||
mcp__desk-crm-v3__expense_analytics(period="this_year")
|
||||
```
|
||||
|
||||
### Tabela de precos Descomplicar
|
||||
O ficheiro de referencia de precos esta em:
|
||||
`/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/Servicos/tabela-geral.csv`
|
||||
|
||||
---
|
||||
**Versao**: 1.0.0 | **Autor**: Descomplicar®
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
|
||||
|
||||
```jsonl
|
||||
{"date":"","issue":"","fix":"","source":"user|auto"}
|
||||
```
|
||||
|
||||
*Adicionar nova linha após cada erro corrigido.*
|
||||
|
||||
@@ -5,7 +5,6 @@ description: "Extrai transcrições e metadados de vídeos, playlists e canais Y
|
||||
version: "1.0.0"
|
||||
created: 2026-04-04
|
||||
tools: [Bash]
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# Skill: /youtube-extract
|
||||
|
||||
Reference in New Issue
Block a user