feat: add City10 platform with Laravel 13, AI agents, 3D viewer, and LGPD compliance

Initial commit of the complete City10 virtual city simulation platform. Backend (Laravel 13): - REST API with Sanctum tokens and session-based web authentication - Role-based access control (admin/user) with middleware protection - AI agent CRUD with OpenRouter.ai integration restricted to free models - Store management with 3D coordinates and AI shopkeeper assignment - Versioned legal documents (Terms, Privacy, Cookies) with LGPD audit trail - Math CAPTCHA on public forms and multi-language support (pt_BR, en, es) Frontend: - Responsive Blade templates with Tailwind CSS v4 - Three.js 3D city viewer with SSE chat streaming to AI agents - Admin panel for store and user administration Infrastructure: - MariaDB/MySQL database with comprehensive migrations - Database seeders for demo content and test accounts - PHPUnit test suite and Laravel Pint code styling - Vite build configuration with hot reload
2026-10-17 20:46:15 -03:00
commit 79d12fa2f4
128 changed files with 17053 additions and 0 deletions
@@ -0,0 +1,218 @@
+# 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](https://openrouter.ai), restrita a uma lista de
+modelos gratuitos.
+
+> Plataforma operada pela **Syspanel** — Santa Rita do Sapucaí/MG, Brasil.
+> Contato: [contato@syspanel.com.br](mailto:contato@syspanel.com.br) ·
+> WhatsApp: (35) 99226-1684 · [www.syspanel.com.br](https://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
+
+```bash
+composer install
+```
+
+### 2. Configuração do ambiente
+
+```bash
+cp .env.example .env
+php artisan key:generate
+```
+
+Edite o `.env` e configure o banco de dados:
+
+```env
+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:
+
+```env
+OPENROUTER_API_KEY=<sua_chave>
+AI_DEFAULT_MODEL=deepseek/deepseek-v4-flash-0731
+```
+
+### 4. Banco de dados
+
+```bash
+php artisan migrate --seed
+```
+
+### 5. Servidor de desenvolvimento
+
+```bash
+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:
+
+```bash
+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`](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`](RULES.md).
+
+---
+
+## Contato
+
+- **E-mail**: [contato@syspanel.com.br](mailto:contato@syspanel.com.br)
+- **WhatsApp**: (35) 99226-1684
+- **Site**: [www.syspanel.com.br](https://syspanel.com.br)
+- **Localização**: Santa Rita do Sapucaí — Minas Gerais — Brasil
+
+---
+
+© 2026 — Todos os direitos reservados — Powered by
+[Syspanel](https://syspanel.com.br) — www.syspanel.com.br