marcocosta10000
79d12fa2f4
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
219 lines
7.2 KiB
Markdown
Executable File
219 lines
7.2 KiB
Markdown
Executable File
# 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
|