From 8f582c6f2db70a7f9e7465a0417dff28e6370c3f Mon Sep 17 00:00:00 2001 From: Benevanio Santos Date: Sun, 22 Mar 2026 20:56:04 -0300 Subject: [PATCH] docs: enhance README with project overview, features, and usage instructions --- README.md | 118 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 3307917b..bb97926a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,39 @@ -# Vagas Full Monorepo +# Painel de Vagas -Projeto reorganizado em monorepo com dois workspaces: +Uma plataforma interna para transformar arquivos XLSX de vagas em uma experiencia visual rapida, filtravel e pronta para decisao. -- `frontend`: dashboard React/Vite/Tailwind -- `backend`: scraper + API Express para leitura de vagas em XLSX +O projeto esta organizado em monorepo e conecta duas frentes: -## Estrutura +- frontend: dashboard em React + Vite + Tailwind +- backend: scraper + API em Express para leitura e exposicao dos dados + +## O que ja entregamos + +- Dashboard com visual profissional em tema claro e escuro +- Leitura automatica dos arquivos XLSX gerados no fluxo de scraping +- Busca global por titulo, empresa, local e link +- Filtros por palavra-chave +- Selecao de arquivo de origem para alternar datasets +- Tabela paginada com controle de itens por pagina +- Endpoint de saude e endpoints de listagem/consulta de vagas +- Suite de testes (unitarios + integracao) em frontend e backend +- Cobertura de testes com alvo minimo de 80% + +## Demo + +### Interface em tema escuro e claro + + + +Image + + +Image + + +Image + +## Arquitetura do produto ```text . @@ -15,31 +43,36 @@ Projeto reorganizado em monorepo com dois workspaces: └─ package.json ``` +## Stack + +- Frontend: React 19, TypeScript, Vite 8, Tailwind CSS +- Backend: Node.js 22+, Express 5, XLSX, Axios, Cheerio +- Qualidade: Vitest, Testing Library, coverage v8 +- Orquestracao local: npm workspaces + Docker Compose + ## Requisitos - Node.js 22+ - npm - Docker (opcional) -## Instalar dependencias +## Comecando rapido -Na raiz do projeto: +Instale tudo na raiz do monorepo: ```bash npm install ``` -Como o projeto usa `workspaces`, esse comando instala dependencias da raiz e dos pacotes `frontend` e `backend`. +Como usamos workspaces, esse comando instala as dependencias da raiz e tambem de `frontend` e `backend`. -## Rodar em desenvolvimento - -Subir frontend e backend juntos: +Suba a plataforma completa em desenvolvimento: ```bash npm run dev ``` -Rodar separadamente: +Subida separada por servico: ```bash npm run dev:frontend @@ -48,37 +81,38 @@ npm run dev:backend ## Scripts principais -Na raiz: +### Raiz - `npm run dev`: frontend + backend juntos - `npm run dev:frontend`: sobe apenas frontend -- `npm run dev:backend`: sobe apenas backend (API) -- `npm run scraper`: executa scraping via backend workspace -- `npm run scraper:watch`: scraping com nodemon via backend workspace -- `npm run test`: testes do backend +- `npm run dev:backend`: sobe apenas backend +- `npm run scraper`: executa scraping no backend +- `npm run scraper:watch`: scraping com hot reload +- `npm run test`: executa testes do backend - `npm run build`: build do frontend - `npm run validate`: teste backend + lint/build frontend -- `npm run test:coverage`: coverage frontend + backend (threshold 80%) +- `npm run test:coverage`: coverage frontend + backend -No backend (`backend/package.json`): +### Backend - `npm run start`: sobe API (`src/server.js`) - `npm run dev`: sobe API (`src/server.js`) - `npm run scraper`: executa scraping (`index.js`) -- `npm run scraper:watch`: scraping com hot reload (`nodemon index.js`) -- `npm run api`: alias para subir API (`src/server.js`) +- `npm run scraper:watch`: scraping com nodemon +- `npm run api`: alias para subir API - `npm run test`: testes com Vitest +- `npm run test:coverage`: cobertura com Vitest - `npm run test:watch`: testes em modo watch -- `npm run validate`: valida backend (`npm test`) +- `npm run validate`: valida backend -No frontend (`frontend/package.json`): +### Frontend - `npm run dev`: Vite dev server - `npm run build`: build de producao - `npm run lint`: lint com ESLint - `npm run preview`: preview do build - `npm run test`: testes com Vitest -- `npm run test:coverage`: coverage com Vitest (threshold 80%) +- `npm run test:coverage`: coverage com Vitest ## Testes e cobertura @@ -87,14 +121,14 @@ Estrutura de testes: - backend: `backend/tests/unit` e `backend/tests/integration` - frontend: `frontend/tests/unit` e `frontend/tests/integration` -Cobertura minima exigida: +Meta minima de cobertura: - lines >= 80% - statements >= 80% - functions >= 80% - branches >= 80% -Comandos: +Comandos de cobertura: ```bash npm run test:coverage @@ -102,21 +136,18 @@ npm --workspace frontend run test:coverage npm --workspace backend run test:coverage ``` -Guia de boas praticas de testes: [TESTING.md](https://github.com/Benevanio/Jobs_Scraper_Global/blob/master/TESTING.md). +Guia de boas praticas: [TESTING.md](TESTING.md) ## Variaveis de ambiente -Arquivo base: - -- `backend/.env.example` +Arquivos: -Arquivo local: - -- `backend/.env` +- `backend/.env.example` (base) +- `backend/.env` (local) ## Docker -Subir frontend e backend: +Subir frontend + backend: ```bash docker compose up --build @@ -128,7 +159,7 @@ Subir em background: docker compose up --build -d ``` -Parar e remover containers/rede do projeto: +Parar e remover containers/rede: ```bash docker compose down @@ -140,30 +171,25 @@ Rebuild apenas backend: docker compose build backend ``` -Executar scraping via Docker (execucao pontual): +Rodar scraping pontual via container: ```bash docker compose run --rm backend node index.js ``` -Ver logs dos servicos: +Logs: ```bash docker compose logs -f -``` - -Ver logs apenas do backend: - -```bash docker compose logs -f backend ``` -Servicos: +Servicos em desenvolvimento: -- `frontend`: http://localhost:5173 -- `backend`: http://localhost:3001 +- frontend: http://localhost:5173 +- backend: http://localhost:3001 -A API le planilhas de `backend/output/`. +A API le planilhas localizadas em `backend/output/`. ## Endpoints da API