City10 — Cidade 3D Virtual com Agentes de IA

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

Software Proprietário — © 2026 Syspanel. Todos os direitos reservados. Veja o arquivo LICENSE para os termos completos de uso.

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

---

© 2026 — Todos os direitos reservados — Powered by Syspanel — www.syspanel.com.br