first commit

2026-06-04 13:38:35 -03:00
commit 4e2ade5f5f
9 changed files with 786 additions and 0 deletions
@@ -0,0 +1,107 @@
+# read-update-xlsx
+
+Script TypeScript que consulta erros de regra de negócio (`BusinessRuleError`) na API do Planview Adaptive Work (Clarizen) e imprime o resultado no terminal.
+
+A comunicação com a API usa a biblioteca [@arco/clarizen-lib](https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib), instalada automaticamente via Git ao rodar `npm install`.
+
+## Pré-requisitos
+
+- [Node.js](https://nodejs.org/) 18 ou superior
+- Acesso ao Gitea da Rivus Lab (para baixar `clarizen-lib` na instalação)
+- Chave de API do Adaptive Work (ou credenciais equivalentes já usadas no time)
+
+## Clonar e instalar
+
+```bash
+git clone https://gitea.rivuslab.com/leonardotoniolo/read-update-xlsx.git
+cd read-update-xlsx
+npm install
+```
+
+Se o repositório `clarizen-lib` for privado, configure autenticação no Git antes do `npm install`:
+
+- **SSH:** chave cadastrada no Gitea e dependência no formato  
+  `git+ssh://git@gitea.rivuslab.com/leonardotoniolo/clarizen-lib.git#main` (se necessário, ajuste no `package.json`)
+- **HTTPS:** token de acesso no Gitea (Personal Access Token) configurado no Git ou no `.npmrc`
+
+Na primeira instalação, o npm clona `clarizen-lib` e executa o build (`prepare` → `tsc`), gerando a pasta `dist/` dentro de `node_modules/@arco/clarizen-lib`.
+
+## Configurar variáveis de ambiente
+
+Copie o exemplo e preencha a API key:
+
+```bash
+cp .env.example .env
+```
+
+Edite `.env` na **raiz do projeto** (não dentro de `src/`):
+
+```env
+CLARIZEN_BASE_URL=https://api.clarizen.com
+CLARIZEN_API_KEY=sua_chave_aqui
+```
+
+Alternativa aceita pelo código: `API_KEY_AW` em vez de `CLARIZEN_API_KEY`.
+
+O carregador de ambiente também tenta usar `../clarizen-lib/.env` se existir (útil em desenvolvimento local com monorepo).
+
+## Rodar o projeto
+
+```bash
+npm start
+```
+
+Isso executa `tsx src/index.ts`, que:
+
+1. Valida se há API key configurada
+2. Consulta até 5000 registros de `BusinessRuleError` com os campos definidos em `src/index.ts`
+3. Exibe a quantidade e cada entidade no console
+
+## Outros comandos
+
+| Comando | Descrição |
+| -------- | --------- |
+| `npm start` | Executa a consulta ao Clarizen |
+| `npm run check:clarizen` | Testa se `@arco/clarizen-lib` foi instalada e compilada corretamente (deve imprimir `OK Clarizen`) |
+
+## Estrutura relevante
+
+```text
+read_update_xlsx/
+├── .env.example      # modelo de variáveis
+├── .env              # suas credenciais (não commitar)
+├── package.json      # dependência clarizen-lib via Git
+├── src/
+│   ├── index.ts      # consulta BusinessRuleError
+│   └── load-env.ts   # carrega .env da raiz do projeto
+└── README.md
+```
+
+## Dependência clarizen-lib
+
+No `package.json` a lib está referenciada assim:
+
+```json
+"@arco/clarizen-lib": "git+https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib.git#main"
+```
+
+O `package-lock.json` fixa o commit exato usado na instalação. Documentação completa da biblioteca: [clarizen-lib](https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib).
+
+### Desenvolvimento local com a lib ao lado
+
+Se você tiver `clarizen-lib` clonada na pasta irmã (`../clarizen-lib`), pode trocar temporariamente no `package.json`:
+
+```json
+"@arco/clarizen-lib": "file:../clarizen-lib"
+```
+
+Rode `npm install` e `npm run build` dentro de `clarizen-lib`. Não commite essa alteração se o repositório for usado só via Git.
+
+## Problemas comuns
+
+| Sintoma | O que fazer |
+| -------- | ------------ |
+| Erro ao clonar `clarizen-lib` no `npm install` | Verificar login SSH/HTTPS no Gitea |
+| `Cannot find module .../dist/index.js` | Rodar de novo `npm install` (o `prepare` da lib deve compilar o `dist`) ou `npm run check:clarizen` |
+| `Defina CLARIZEN_API_KEY...` | Criar `.env` na raiz com `CLARIZEN_API_KEY` ou `API_KEY_AW` |
+| Instalação dentro de monorepo npm | Usar `npm install --workspaces=false` nesta pasta para não sobrescrever o lock com `file:../clarizen-lib` |