MEDGRUPOGIT · automatizador · Sep 18, 2025
diff --git a/docs/AUTO_DOC.md b/docs/AUTO_DOC.md
@@ -0,0 +1,201 @@
+# Documentação Técnica — windowSoftInputMode (Cordova/Android)
+
+## Visão Geral
+
+Este repositório contém um plugin Cordova para Android que permite alterar dinamicamente o `windowSoftInputMode` da janela da Activity em tempo de execução, via JavaScript. Isso é útil para adequar o comportamento da tela quando o teclado virtual (soft keyboard) é exibido, especialmente em telas com campos de entrada que precisam preservar a visibilidade e o layout.
+
+- ID do plugin: `com.medgrupo.window-soft-input-mode`
+- Plataforma suportada: Android
+- Linguagens: Java (nativo Android) e JavaScript (Camada JS do Cordova)
+- Licença: MIT (vide `package.json`)
+
+## Objetivo de Negócio (Regras)
+
+- Permitir que telas Cordova/Hybrid controlarem, em tempo real, o comportamento da UI frente ao teclado virtual, sem necessidade de rebuild nativo.
+- Modos suportados:
+  - `adjustPan`: a janela é “movida” para que o foco permaneça visível; o layout não é redimensionado.
+  - `adjustResize`: o layout é redimensionado para abrir espaço ao teclado.
+  - `adjustNothing`: nenhum ajuste automático é feito (mantém layout como está).
+- A aplicação cliente decide em qual momento aplicar cada modo, por exemplo:
+  - Formulários longos: `adjustResize` para evitar sobreposição do teclado.
+  - Telas com layouts fixos ou quando o pan é suficiente: `adjustPan`.
+  - Casos específicos em que nenhum ajuste é desejado: `adjustNothing`.
+
+## Arquitetura e Padrões
+
+- Padrão Cordova Plugin:
+  - Camada JS exposta em `www/windowSoftManager.js` com a API pública.
+  - Ponte (bridge) nativa via `cordova/exec`, chamando a classe Java `windowSoftManager`.
+  - Empacotamento e declaração via `plugin.xml`.
+- Execução em UI Thread:
+  - A mudança de `softInputMode` é executada no thread de UI (Android) para garantir consistência com a API de janela.
+- Sem estado interno persistente:
+  - O plugin aplica o modo solicitado diretamente na janela corrente (`cordova.getActivity().getWindow()`), sem armazenar estado ou preferências.
+
+## Estrutura do Projeto
+
+- `package.json`: Metadados do plugin (nome, versão, engines, palavras-chave).
+- `plugin.xml`: Define o módulo JS, a feature Android e a classe nativa `windowSoftManager`.
+- `www/windowSoftManager.js`: API JavaScript exposta ao app Cordova.
+- `src/android/windowSoftManager.java`: Implementação nativa Android.
+- `README.md`: Instruções rápidas de uso e instalação (histórico do projeto original).
+- `docs/`: Pasta de documentação (este arquivo).
+
+## API JavaScript (Uso)
+
+Importação (automática via Cordova) e chamada:
+
+```js
+// Mudar para adjustPan
+windowSoftManager.setMode(windowSoftManager.MODES.SOFT_INPUT_ADJUST_PAN);
+
+// Mudar para adjustResize
+windowSoftManager.setMode(windowSoftManager.MODES.SOFT_INPUT_ADJUST_RESIZE);
+
+// Mudar para adjustNothing
+windowSoftManager.setMode(windowSoftManager.MODES.SOFT_INPUT_ADJUST_NOTHING);
+```
+
+Assinatura atual:
+
+```js
+windowSoftManager.setMode(modeString)
+```
+
+- `modeString` deve ser um dos valores de `windowSoftManager.MODES`.
+- A implementação atual não retorna valor e não utiliza os callbacks de sucesso/erro para repassar resultado ao JS (ver seção “Melhorias Sugeridas”).
+
+Constantes expostas:
+
+```js
+windowSoftManager.MODES = {
+  SOFT_INPUT_ADJUST_PAN: "adjustPan",
+  SOFT_INPUT_ADJUST_RESIZE: "adjustResize",
+  SOFT_INPUT_ADJUST_NOTHING: "adjustNothing"
+}
+```
+
+## Ponte Nativa (Android)
+
+- Classe: `windowSoftManager` (Java)
+- Método de entrada: `execute(String action, JSONArray args, CallbackContext callbackContext)`
+- Mapeamento de ações (strings):
+  - `"adjustPan"` → `WindowManager.LayoutParams.SOFT_INPUT_ADJUST_PAN`
+  - `"adjustResize"` → `WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE`
+  - `"adjustNothing"` → `WindowManager.LayoutParams.SOFT_INPUT_ADJUST_NOTHING`
+
+A mudança é aplicada dentro de `cordova.getActivity().runOnUiThread(...)` para garantir que a alteração de layout seja feita na UI thread.
+
+## Compatibilidade e Requisitos
+
+- Cordova: `>= 3.0.0` (conforme `package.json`).
+- Plataforma: Android.
+- Não requer permissões adicionais.
+- Observação: o `plugin.xml` referencia a classe Java sem namespace de pacote (classe default). Em versões mais novas do `cordova-android`, recomenda-se usar um pacote totalmente qualificado para evitar conflitos. Caso surjam problemas de build, ver a seção “Manutenção e Extensibilidade”.
+
+## Instalação e Remoção
+
+Instalação via caminho local (recomendado quando usando este repositório diretamente):
+
+```bash
+cordova plugin add <caminho/para/este/repo>
+```
+
+Instalação via Git (se o repositório público estiver acessível):
+
+```bash
+cordova plugin add https://github.com/MEDGRUPOGIT/windowSoftInputMode
+```
+
+Remoção:
+
+```bash
+cordova plugin remove com.medgrupo.window-soft-input-mode
+```
+
+Notas:
+- O `README.md` menciona forks anteriores por questões de compatibilidade; utilize preferencialmente o identificador e repositório deste projeto.
+- Após instalar, o Cordova injeta o módulo JS em `windowSoftManager` (clobber).
+
+## Fluxo de Execução (end-to-end)
+
+1. App chama `windowSoftManager.setMode("adjustResize" | "adjustPan" | "adjustNothing")`.
+2. `www/windowSoftManager.js` invoca `cordova.exec(success, error, "windowSoftManager", actionString, [])`.
+3. Cordova roteia para a classe Java `windowSoftManager` definida em `plugin.xml`.
+4. `execute(...)` compara a string de ação e aplica o `setSoftInputMode` correspondente na `Window` da Activity.
+5. Retorna `true` ao Cordova indicando que a ação foi tratada (sem payload de retorno).
+
+## Tecnologias
+
+- Cordova (bridge JS ↔ Android nativo)
+- Android SDK (APIs de `WindowManager.LayoutParams`)
+- Java (plugin nativo)
+- JavaScript (módulo de integração Cordova)
+
+## Banco de Dados
+
+- Não há uso de banco de dados. O plugin é stateless e efêmero: apenas aplica um modo na janela ativa.
+
+## Qualidade, Testes e Validação
+
+Sugestões para validação manual:
+- Crie um projeto Cordova Android com uma tela de formulário contendo inputs próximos à parte inferior.
+- Aplique `adjustResize` e valide se o layout é redimensionado mantendo o input visível ao abrir o teclado.
+- Aplique `adjustPan` e valide o “empurrão” do conteúdo sem redimensionar o layout.
+- Aplique `adjustNothing` e verifique que não há alteração automática na UI.
+
+Cenários adicionais:
+- Alternar modos em runtime navegando entre telas/modalidades distintas da aplicação.
+- Conferir comportamento em diferentes OEMs/teclados.
+
+## Logs e Tratamento de Erros
+
+- O plugin não gera logs específicos nem encaminha mensagens de erro ao JS.
+- `exec` recebe callbacks, mas a implementação JS atual não utiliza `result` nem propaga status ao chamador.
+- Para depuração, recomenda-se adicionar logs no Java (via `Log.d(TAG, ...)`) e, se necessário, ajustar a camada JS para expor callbacks ou Promises.
+
+## Segurança e Permissões
+
+- Não requer permissões especiais no Android.
+- A operação limita-se à Activity atual do container Cordova.
+
+## Manutenção e Extensibilidade
+
+Melhorias sugeridas:
+- Namespace do pacote Java: mover `windowSoftManager.java` para um pacote dedicado (ex.: `com.medgrupo.windowsoftinputmode`) e atualizar `plugin.xml` com o `android-package` totalmente qualificado. Isso reduz risco de conflito de nomes e melhora compatibilidade com `cordova-android` recentes.
+- Callbacks/Promises: adaptar `www/windowSoftManager.js` para aceitar callbacks de sucesso/erro ou retornar uma Promise, sinalizando conclusão e permitindo tratar falhas.
+- Novos modos: adicionar suporte a outros flags do Android, se necessário (ex.: `SOFT_INPUT_ADJUST_UNSPECIFIED`). Para isso:
+  1. Incluir a constante no objeto `MODES` em `www/windowSoftManager.js`.
+  2. Mapear a nova ação no `execute(...)` em `windowSoftManager.java`.
+  3. Atualizar o `README.md` e este documento.
+- Consultar modo atual: expor um método `getMode()` (JS) mapeado a uma ação nativa que retorne o modo corrente (exigirá armazenar/derivar o último modo aplicado ou consultar atributos da janela quando possível).
+- Robustez: validar o `action` no Java, responder `callbackContext.error(...)` para valores não reconhecidos e retornar `false` em `execute(...)` quando não tratar a ação.
+- Testes automatizados: adicionar testes de integração em um app de exemplo Cordova.
+
+Checklist de versão/publicação:
+- Atualizar `version` em `package.json` e em `plugin.xml`.
+- Validar instalação e uso em um projeto Cordova limpo (Android recente).
+- Atualizar `README.md` com instruções e compatibilidade.
+
+## Limitações Conhecidas
+
+- Android apenas: não há implementação para iOS ou outras plataformas.
+- Classe Java sem pacote: pode causar conflitos ou falhas de build em ambientes mais novos; considere migrar para um pacote.
+- Retorno/erros não propagados: a API JS atual é “fire-and-forget”.
+- Dependente do comportamento do teclado/OEM: alguns fabricantes/teclados podem apresentar variações sutis no ajuste da janela.
+
+## Referências
+
+- Android `WindowManager.LayoutParams`: documentação oficial para `SOFT_INPUT_ADJUST_*`.
+- Cordova Plugin Development Guide: estrutura de plugins e `cordova.exec`.
+- Arquivos do repositório:
+  - `plugin.xml`
+  - `www/windowSoftManager.js`
+  - `src/android/windowSoftManager.java`
+  - `package.json`
+  - `README.md`
+
+---
+
+Última atualização deste documento: gerado automaticamente a partir do código-fonte presente no repositório.
+