feat: new ref tracking tables

Author: caiopizzol

README.md

@@ -50,13 +50,27 @@ pnpm crawl -- --brand 59 --model 5940         # Modelo específico
 pnpm crawl -- --brand 59 --model 5940,5941    # Múltiplos modelos
 pnpm crawl -- --reference 328                 # Tabela de referência específica
 pnpm crawl -- --classify                      # Classificar modelos novos via AI
+pnpm crawl -- --force                         # Re-buscar tudo ignorando status de sync
 ALLOWED_BRANDS=21,22,23 pnpm crawl            # Limitar marcas via env
 
 pnpm status                                   # Estatísticas do banco
 pnpm classify                                 # Classificar modelos sem segmento
 pnpm classify -- --dry-run                    # Preview da classificação
 ```
 
+## Como Funciona o Crawl
+
+O crawler usa um sistema de **sync granular** que rastreia o progresso por tabela de referência:
+
+1. **Fase 1 - Brands**: Busca marcas da API e armazena no banco
+2. **Fase 2 - Models**: Para cada marca, busca modelos
+3. **Fase 3 - Model-Years**: Para cada modelo, busca anos/combustíveis
+4. **Fase 4 - Prices**: Para cada ano, busca o preço
+
+Cada fase é rastreada independentemente. Se o crawl for interrompido, continua de onde parou na próxima execução.
+
+Use `--force` para ignorar o status de sync e re-buscar todos os dados.
+
 ## Docker
 
 ```bash

initial.sql

@@ -3,7 +3,8 @@ CREATE TABLE IF NOT EXISTS reference_tables (
   code INTEGER UNIQUE NOT NULL,
   month INTEGER NOT NULL,
   year INTEGER NOT NULL,
-  crawled_at TIMESTAMP
+  crawled_at TIMESTAMP,
+  brands_crawled_at TIMESTAMP
 );
 
 CREATE TABLE IF NOT EXISTS brands (
@@ -55,3 +56,36 @@ CREATE INDEX IF NOT EXISTS idx_models_segment ON models(segment);
 CREATE INDEX IF NOT EXISTS idx_reference_year_month ON reference_tables(year, month);
 CREATE INDEX IF NOT EXISTS idx_model_years_year ON model_years(year);
 CREATE INDEX IF NOT EXISTS idx_brands_name ON brands(name);
+
+-- Crawl status tracking tables (per reference)
+CREATE TABLE IF NOT EXISTS reference_brands (
+  id SERIAL PRIMARY KEY,
+  reference_table_id INTEGER NOT NULL REFERENCES reference_tables(id),
+  brand_id INTEGER NOT NULL REFERENCES brands(id),
+  models_crawled_at TIMESTAMP,
+  UNIQUE(reference_table_id, brand_id)
+);
+
+CREATE TABLE IF NOT EXISTS reference_models (
+  id SERIAL PRIMARY KEY,
+  reference_table_id INTEGER NOT NULL REFERENCES reference_tables(id),
+  model_id INTEGER NOT NULL REFERENCES models(id),
+  years_crawled_at TIMESTAMP,
+  UNIQUE(reference_table_id, model_id)
+);
+
+CREATE TABLE IF NOT EXISTS reference_model_years (
+  id SERIAL PRIMARY KEY,
+  reference_table_id INTEGER NOT NULL REFERENCES reference_tables(id),
+  model_year_id INTEGER NOT NULL REFERENCES model_years(id),
+  price_crawled_at TIMESTAMP,
+  UNIQUE(reference_table_id, model_year_id)
+);
+
+-- Crawl status indexes
+CREATE INDEX IF NOT EXISTS idx_reference_brands_ref ON reference_brands(reference_table_id);
+CREATE INDEX IF NOT EXISTS idx_reference_brands_brand ON reference_brands(brand_id);
+CREATE INDEX IF NOT EXISTS idx_reference_models_ref ON reference_models(reference_table_id);
+CREATE INDEX IF NOT EXISTS idx_reference_models_model ON reference_models(model_id);
+CREATE INDEX IF NOT EXISTS idx_reference_model_years_ref ON reference_model_years(reference_table_id);
+CREATE INDEX IF NOT EXISTS idx_reference_model_years_my ON reference_model_years(model_year_id);