# 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