City10 é uma plataforma full-stack de simulação urbana 3D com agentes de inteligência artificial autônomos, construída sobre Laravel 13 e Three.js. Agentes (Prefeito, pedestres, lojistas) tomam decisões estratégicas em tempo real através da API OpenRouter.ai, restrita a uma lista de modelos gratuitos.

Plataforma operada pela Syspanel — Santa Rita do Sapucaí/MG, Brasil. Contato: contato@syspanel.com.br · WhatsApp: (35) 99226-1684 · www.syspanel.com.br

Visão Geral da Arquitetura

Camada	Tecnologia	Responsabilidade
Backend / Painel Admin	Laravel 13 (PHP ≥ 8.3)	Autenticação, API REST, regras de negócio, consentimento LGPD
Banco de Dados	MariaDB (MySQL)	Persistência de usuários, lojas, agentes e consentimentos
Cache / Fila	Redis / Database	Sessões, cache e jobs
Frontend 3D	Three.js (Fase 2+)	Renderização da cidade no navegador
Tempo Real	Laravel Reverb (planejado)	Sincronização de estado entre clientes
Cérebro dos Agentes	OpenRouter.ai	Raciocínio dos NPCs com modelos gratuitos

Fase 1 (Atual) — Entregue

Estrutura Laravel 13 com autenticação diferenciada (Admin / Usuário Comum).
Migrations: usuários com role, lojas com coordenadas 3D (pos_x, pos_y, pos_z), agentes de IA e trilha de consentimento legal (LGPD).
API REST (Sanctum) para usuários, lojas, agentes, cidade e documentos legais.
CAPTCHA matemático próprio (soma), sem dependências externas, nos formulários públicos.
Multi-idioma: Português (Brasil), Inglês e Espanhol — selecionável pelo usuário.
Termos de Uso, Política de Privacidade e Política de Cookies (LGPD), versionados e com aceite auditável (data, hora, versão, IP).
Banner de cookies com link para os Termos de Uso e Privacidade.
Página inicial responsiva (desktop e smartphone).

Requisitos

PHP ≥ 8.3 (com pdo_mysql, mbstring, curl, zip, gd, bcmath)
Composer 2
MariaDB ≥ 10.6 (ou MySQL ≥ 8.0)
Node.js ≥ 18 (apenas para assets Vite/Tailwind, opcional na Fase 1)
Docker (opcional, para o ambiente dockercity10)

Instalação

1. Dependências PHP

composer install

2. Configuração do ambiente

cp .env.example .env
php artisan key:generate

Edite o .env e configure o banco de dados:

DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=<sua_senha>

3. Chave do OpenRouter.ai

A chave não é versionada. Insira-a apenas no .env local:

OPENROUTER_API_KEY=<sua_chave>
AI_DEFAULT_MODEL=deepseek/deepseek-v4-flash-0731

4. Banco de dados

php artisan migrate --seed

5. Servidor de desenvolvimento

php artisan serve --port=16980

A aplicação ficará disponível em http://localhost:16980.

Ambiente Docker (dockercity10)

O container dockercity10 já expõe a aplicação na porta do host 16980 (container :80, Apache + PHP-FPM) e o MariaDB na porta 16981. Após clonar o projeto em /app (bind-mount), rode as migrations dentro do container:

docker exec -it dockercity10 bash -c "cd /app && php artisan migrate --seed"

Contas de Teste (ambiente de desenvolvimento)

Papel	E-mail	Senha
Administrador	`marcocosta@gmx.com`	`Mega886ax`
Usuário Comum	`user@sistema.net`	`User123`

⚠️ Estas credenciais são exclusivas para desenvolvimento. Altere-as ou remova-as (php artisan db:seed --class=UserSeeder após ajustar) antes de qualquer implantação em produção.

Estrutura de Endpoints da API

Base URL: http://localhost:16980/api

Públicos

Método	Rota	Descrição
GET	`/auth/captcha`	Gera desafio matemático (necessário para login/registro)
POST	`/auth/login`	Autentica e emite token Sanctum
POST	`/auth/register`	Cria conta de usuário comum
GET	`/legal/documents`	Lista a versão atual dos documentos legais

Autenticados (Bearer token)

Método	Rota	Descrição
GET	`/auth/me`	Perfil + status de consentimento
PATCH	`/auth/profile`	Atualiza nome, idioma ou senha
POST	`/auth/logout`	Revoga o token atual
GET	`/city/world`	Snapshot da cidade (lojas + agentes com coordenadas 3D)
GET/POST	`/stores`	Lista/cria lojas
GET/PUT/DELETE	`/stores/{id}`	Gerencia uma loja (dono ou admin)
GET	`/legal/status`	Status de aceite dos documentos
POST	`/legal/accept`	Registra o aceite (auditoria LGPD)
GET	`/legal/history`	Histórico de consentimentos do usuário

Somente Administrador (`/admin`)

Método	Rota	Descrição
GET/POST	`/admin/users`	Lista/cria usuários
GET/PUT/DELETE	`/admin/users/{id}`	Gerencia usuários
GET/POST	`/admin/agents`	Lista/cria agentes de IA
GET/PUT/DELETE	`/admin/agents/{id}`	Gerencia agentes
GET	`/admin/agents-meta/models`	Lista os modelos gratuitos permitidos

Modelos de IA Permitidos

Somente os modelos gratuitos abaixo podem ser atribuídos a agentes (validado no backend em config/ai.php):

poolside/laguna-m.1:free          cohere/north-mini-code:free
deepseek/deepseek-v4-flash-0731:free     qwen/qwen3.8-27b:free
nvidia/nemotron-3-ultra-550b-a55b:free   nvidia/nemotron-3-super-120b-a12b:free
google/gemma-4-31b-it:free        google/gemma-4-26b-a4b-it:free
openai/gpt-oss-20b:free           nvidia/nemotron-nano-12b-v2-vl:free
nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free
nvidia/nemotron-3-nano-30b-a3b:free      nvidia/nemotron-nano-9b-v2:free
poolside/laguna-xs-2.1:free       inclusionai/ling-3.0-flash-vl:free
qwen/qwen3.7-flash:free

Segurança e Conformidade (LGPD)

Senhas armazenadas com bcrypt (cast hashed).
Tokens de API (Sanctum) revogáveis por usuário.
RBAC: papéis admin / user com middleware dedicado.
CAPTCHA matemático nos formulários públicos (login/registro).
Consentimento auditável: data, hora, versão do documento, IP e user-agent gravados em user_consents (imutáveis).
Banner de cookies com opção de aceitar/recusar cookies não essenciais.
Direitos do titular (art. 18 LGPD): histórico de consentimentos disponível ao usuário; contato para exercer direitos: contato@syspanel.com.br.

Licença

Bibliotecas de terceiros utilizadas são compatíveis com uso comercial (por exemplo: Laravel — MIT; Three.js — MIT). O crédito aos autores originais está registrado em RULES.md.

Contato

E-mail: contato@syspanel.com.br
WhatsApp: (35) 99226-1684
Site: www.syspanel.com.br
Localização: Santa Rita do Sapucaí — Minas Gerais — Brasil

README.md

City10 — Cidade 3D Virtual com Agentes de IA