fluig-best-practices
Revisa a aderência de código de customização Fluig às boas práticas oficiais da plataforma (convenções de widget com SuperWidget, Custom Elements, i18n, uso do Style Guide, chamadas REST internas e ES6+) e produz achados classificados por severidade, cada um referenciando a regra do arquivo de contexto. Use quando o desenvolvedor pedir uma revisão de conformidade com os padrões Fluig de um trecho ou arquivo antes de merge, sem reescrever o código.
totvs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add totvs/fluig-agent-skills --skill fluig-best-practices技能说明
name: fluig-best-practices description: Revisa a aderência de código de customização Fluig às boas práticas oficiais da plataforma (convenções de widget com SuperWidget, Custom Elements, i18n, uso do Style Guide, chamadas REST internas e ES6+) e produz achados classificados por severidade, cada um referenciando a regra do arquivo de contexto. Use quando o desenvolvedor pedir uma revisão de conformidade com os padrões Fluig de um trecho ou arquivo antes de merge, sem reescrever o código. argument-hint: o código/arquivo Fluig alvo da revisão de boas práticas (trecho ou arquivo selecionado), idealmente com o tipo de artefato
Revisão de Aderência às Boas Práticas do Fluig
Esta skill revisa a aderência do código às boas práticas oficiais do Fluig e emite achados por severidade; ela não duplica convenções — o arquivo de context/ é a fonte de verdade, referenciada abaixo. A skill não reescreve o código.
Objetivo
Revisar, com responsabilidade única, a aderência de código de customização Fluig às boas práticas oficiais da plataforma — convenções de widget, Custom Elements, i18n, uso do Style Guide, chamadas REST internas e ES6+ — produzindo um relatório de achados classificados por severidade, cada um vinculado à regra correspondente do arquivo de contexto.
Quando Usar
- Antes de um merge, para verificar conformidade com os padrões oficiais do Fluig.
- Quando há dúvida se o código segue as convenções de widget/Custom Element da plataforma.
- Quando se quer garantir compatibilidade e manutenibilidade alinhadas ao padrão Fluig.
- Como complemento às revisões especializadas (
fluig-review-performance,fluig-review-security,fluig-review-accessibility).
Entradas Esperadas
| Entrada | Descrição | Obrigatória |
|---|---|---|
| Código alvo | Trecho ou arquivo de customização a revisar (widget, Custom Element, .ftl, CSS) | sim |
| Tipo de artefato | Tipo em que o código roda (widget, layout, form) | não |
| Foco solicitado | Convenções prioritárias da revisão, se houver | não |
Contexto de Referência (Fonte de Verdade)
Leia antes de executar — não reproduza o conteúdo aqui:
- conventions.md — ES6+, nomenclatura, convenções de widget (
fluig-style-guidena raiz,instanceIdsó emidcom_,instance()seminstanceId, bindings), Custom Elements, comunicação por eventos, i18n, segurança via APIs públicas, chamadas REST internas e CSS. - style-guide.md — componentes, grid, classes helper
fs-*e variáveis CSS de tema (var(--fs-color-*), dark mode).
Regras Aplicáveis (Resumo Executivo)
Somente o mínimo para orientar a revisão; o detalhe está no contexto. Cada achado deve citar a regra de origem.
- ES6+ para código novo:
const/let, arrow functions, template literals,async/await; sem misturar jQuery e ES6+ no mesmo arquivo → verconventions.md. - Convenções de widget: raiz com
fluig-style-guide;instanceIdapenas emidcom_;instance()seminstanceId; bindings com chave sem o prefixodata-→ verconventions.md. - Custom Elements: nome de arquivo
[name].[category].js; classe PascalCase; sem Shadow DOM; topo do arquivo só comimport→ verconventions.md. - i18n: texto visível via
${i18n.getTranslation('chave')}; nunca acessari18ncomo objeto JS → verconventions.md. - Style Guide: reutilizar componentes/helpers/grid antes de criar CSS próprio;
var(--fs-color-*)para cores de tema → verconventions.mdestyle-guide.md. - REST interna: chamadas via
WCMAPI/FLUIGC.ajax(nuncafetch/$.ajaxdireto) → verconventions.md. - Nomenclatura: nomes descritivos em Inglês; booleanos com
is/has/can/should→ verconventions.md.
Tabela de Anti-padrões de Widget
Instrumento rápido de revisão: identifique o anti-padrão no código e aplique a
alternativa recomendada. A tabela não duplica a regra — cada item aponta para
a regra-fonte completa em context/, que permanece a fonte de verdade.
| ❌ Anti-padrão | ✅ Alternativa | Regra-fonte |
|---|---|---|
| Widget monolítico com responsabilidades misturadas | Modularizar em métodos/funções menores, com responsabilidade única; init() delega a métodos claros | conventions.md › JavaScript Moderno (ES6+) |
| Nomes vagos ou abreviações obscuras | Nomenclatura descritiva e consistente, em Inglês; booleanos com is/has/can/should | conventions.md › Nomenclatura |
| Strings fixas sem i18n quando há chave disponível | Resolver o texto via ${i18n.getTranslation('chave')} (e variantes getTranslationP1/getJSTranslation) | conventions.md › Internacionalização (i18n) |
Customização inline em HTML (style inline) | Classe dedicada no CSS, escopada à raiz do widget | conventions.md › CSS |
Seletor frágil com id, cadeia longa e !important | Escopo por classe da widget, com especificidade controlada | conventions.md › CSS |
Variáveis globais ou window.* para comunicação entre artefatos | Eventos: CustomEvent/dispatchEvent (Web Components) ou WCMAPI.fireEvent/addListener (widgets) | conventions.md › Comunicação entre artefatos (eventos) |
fetch()/$.ajax() direto a endpoint interno | Cliente público: FLUIGC.ajax (ES6+) ou WCMAPI.Read/Create/Update/Delete (legado) | conventions.md › Chamadas REST internas |
| CSS customizado onde já existe helper/componente do Style Guide | Reutilizar componentes/helpers fs-*; cores de tema via var(--fs-color-*) | style-guide.md › Classes helper fs-* |
Escala de Severidade
Classifique cada achado em um destes níveis:
| Severidade | Critério | Exemplos típicos | |------
阅读完整来源 ↗