ICC

Plataforma web para calcular, publicar e auditar o Indice de Coerencia Cicloviaria por cidade, usando OpenStreetMap como base principal e PostgreSQL para persistencia.

Visao Geral

O ICC mede se a infraestrutura cicloviaria mapeada e coerente com a hierarquia da malha viaria. A nota final vai de 0 a 100 e representa a proporcao ponderada da malha adequadamente atendida.

O projeto combina:

• portal publico com home, ranking e detalhe por cidade;
• calculo autenticado de resultados ICC por cidade;
• pipeline OpenStreetMap/Overpass para malha viaria e infraestrutura cicloviaria;
• persistencia em PostgreSQL;
• rotas locais em /api/auth/* e /api/db/*;
• autenticacao por magic link e painel administrativo.

Metodo ICC

Regras iniciais do MVP:

• vias estruturais exigem ciclovia;
• vias alimentadoras aceitam ciclovia ou ciclofaixa;
• vias locais aceitam qualquer estrutura cicloviaria reconhecida;
• classes sem extensao no municipio redistribuem seu peso;
• ciclovias separadas sao associadas por proximidade no MVP, com aviso de incerteza.

Os pesos iniciais sao:

• estrutural: 0.60;
• alimentadora: 0.25;
• local: 0.15.

Para cada classe viaria, o sistema calcula:

• L_k: extensao total elegivel;
• A_k: extensao adequada;
• D_k: disponibilidade adequada.

Rotas Principais

• / pagina inicial do ICC;
• /sobre explicacao publica do metodo;
• /ranking ranking ICC com resultados persistidos;
• /detalhes-cidades/:cityId detalhe da cidade, decomposicao e mapa;
• /avaliacao tela autenticada para calcular e publicar ICC;
• /login envio de magic link;
• /solicitar-acesso solicitacao de acesso;
• /admin painel administrativo.

Rotas antigas de formulario IDECICLO permanecem protegidas temporariamente para compatibilidade, mas nao fazem parte do fluxo principal do ICC.

Fluxo De Calculo

1. Entrar em /avaliacao.
2. Selecionar UF e cidade via IBGE.
3. Rodar o calculo ICC.
4. O sistema consulta Overpass para obter malha viaria e infraestrutura cicloviaria.
5. O resultado e salvo em icc_city_results.
6. Os segmentos de diagnostico sao salvos em icc_road_segments.
7. A cidade passa a aparecer no ranking quando houver resultado ICC persistido.

Lote Inicial

A lista inicial de capitais esta em src/data/iccTargetCities.json.

Comandos:

npm run icc:batch -- --dry-run --limit 3
npm run icc:batch -- --state PE --force
npm run icc:batch -- --only 2611606,3550308 --pause-ms 60000 --retries 3

O lote real consulta Overpass e grava no banco. Use --dry-run, --limit, --state ou --only para execucao controlada.

Arquitetura Local

Frontend

• React
• TypeScript
• Vite
• React Router
• Tailwind CSS
• shadcn/ui

Dados E Integracoes

• PostgreSQL
• OpenStreetMap / Overpass
• IBGE para estados e municipios
• Mapbox para mapas no frontend
• Node local para /api/auth/* e /api/db/*

Pre-Requisitos

• Node.js 18 ou superior
• npm
• Docker e Docker Compose
• acesso a internet para IBGE e Overpass
• token Mapbox para mapas interativos

Instalacao Local

npm install
cp .env.example .env.local
npm run db:up
npm run db:bootstrap
npm run db:seedsudo
npm run dev

Exemplo minimo de ambiente:

DATABASE_URL=postgresql://icc:change_me_local_password@127.0.0.1:54322/icc
DATABASE_URL=postgresql://icc:change_me_local_password@127.0.0.1:54322/icc
APP_URL=http://127.0.0.1:8080
EMAIL_FROM=no-reply@icc.local
MAGIC_LINK_SECRET=change_me_magic_link_secret
AUTH_COOKIE_SECURE=false
POSTGRES_DATABASE=icc
POSTGRES_USER=icc
POSTGRES_PASSWORD=change_me_local_password
POSTGRES_PORT=54322
VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token_here

Use DATABASE_URL para autenticacao, permissoes e tabelas legadas. Use DATABASE_URL quando os resultados ICC (icc_city_results e icc_road_segments) estiverem em outro banco PostgreSQL.

Comandos Uteis

npm run dev
npm run build
npm run lint
npm run test:icc
npm run icc:batch -- --dry-run --limit 3
npm run db:up
npm run db:down
npm run db:bootstrap
npm run db:seedsudo

Banco

O bootstrap completo fica em supabase/bootstrap_full_schema.sql.

Tabelas ICC principais:

• icc_city_results: resumo de cada calculo por cidade;
• icc_road_segments: segmentos viarios classificados e diagnosticados.

As tabelas antigas de cities, segments, forms e reviews continuam no schema para compatibilidade durante a transicao.

Limitacoes Conhecidas

• O recorte inicial e municipal; rodovias rurais podem afetar a nota.
• Infraestrutura existente, mas ausente no OSM, e tratada como ausente.
• Matching de ciclovia separada usa proximidade simples no MVP.
• Lotes grandes dependem de disponibilidade e limites do Overpass.

Documentacao De Implantacao

O plano de implantacao incremental esta em docs/plano_implantacao_icc.md.

Licenca

Veja LICENSE.md.