marcocosta10000
e7498e1566
- Add two airports (north/south) with full geometry: runways, taxiways,
aprons, terminals, hangars, stands, and helipads; walkable airport
grounds extend beyond city bounds.
- Introduce ATC AI agent ("Torre de Controle City10") using AI_ATC_MODEL
to generate takeoff clearances; includes dispatch endpoint with
30-second cooldown and deterministic fallback on failure.
- Implement AI model fallback chain: preferred model → AI_FALLBACK_MODEL
before failing, applied in ChatController and PersonTalkController.
- Add luminous sign labels (letreiros) for plazas, beach, food, hospital,
school, city hall, and airports with day/night glow.
- Fix city presence cache: compute is_me per viewer instead of baking
into shared per-second cache to prevent cross-user flag leakage.
- Add tests: AirportTest, CityPresenceTest, SignLabelsTest, and
PersonTalkTest fallback model retry scenario.
150 lines
5.8 KiB
Markdown
Executable File
150 lines
5.8 KiB
Markdown
Executable File
# RULES.md — Regras para IA e Desenvolvedores do City10
|
|
|
|
Este documento reúne as regras obrigatórias que **modelos de IA** (agentes,
|
|
copilotos, assistentes de código) e **desenvolvedores humanos** devem seguir
|
|
ao trabalhar neste repositório.
|
|
|
|
---
|
|
|
|
## 1. Diretrizes Gerais
|
|
|
|
1.1. **Priorize a segurança.** Nunca introduza código que exponha, registre ou
|
|
transmita segredos (chaves de API, senhas, tokens). Chave do OpenRouter
|
|
vive apenas em `.env` (não versionado).
|
|
|
|
1.2. **Não remova a proteção LGPD.** Consentimento, banner de cookies,
|
|
trilha de auditoria e direitos do titular são obrigatórios e não podem
|
|
ser desativados ou contornados.
|
|
|
|
1.3. **Comentários PHPDoc em inglês.** Todo arquivo PHP de origem deve
|
|
possuir comentários técnicos em inglês usando o padrão PHPDoc.
|
|
|
|
1.4. **Multi-idioma.** Toda string visível ao usuário deve existir nos
|
|
arquivos `lang/pt_BR.json`, `lang/en.json` e `lang/es.json`.
|
|
|
|
1.5. **CSRF em formulários.** Todo formulário HTML deve incluir `@csrf`.
|
|
Nunca desative o middleware `VerifyCsrfToken`.
|
|
|
|
1.6. **CAPTCHA nos formulários públicos.** Login e registro devem manter o
|
|
CAPTCHA matemático (soma) nativo, sem bibliotecas externas.
|
|
|
|
1.7. **Senhas com ícone "eye".** Campos de senha em formulários devem exibir
|
|
o botão de alternar visibilidade (olho).
|
|
|
|
---
|
|
|
|
## 2. Regras para Modelos de IA (Agentes do City10)
|
|
|
|
2.1. **Somente modelos allow-listed.** Agentes só podem usar modelos
|
|
definidos em `config/ai.php` (`allowed_models`). A validação
|
|
acontece no backend (`AiAgentRequest`) — não contorne. Por padrão a
|
|
lista contém modelos gratuitos; **exceção aprovada pelo responsável**:
|
|
`xiaomi/mimo-v2.6-flash` (pago, custo mínimo ~1,4e-7/token,
|
|
verificado ao vivo) — atua como **modelo de fallback** das cadeias
|
|
de chamada (`AI_FALLBACK_MODEL`): preferido → default → fallback.
|
|
|
|
2.2. **Nunca envie dados pessoais ao modelo.** Ao chamar o OpenRouter, envie
|
|
apenas contexto simulado da cidade (posições, metas, estado de lojas).
|
|
Nunca inclua nome, e-mail, senha ou outros dados cadastrais de usuários.
|
|
|
|
2.3. **Respeite o intervalo de raciocínio.** Não faça chamadas à API com
|
|
frequência maior que `config('ai.think_interval')` por agente.
|
|
|
|
2.4. **Trate falhas com backoff.** Erros da API devem incrementar
|
|
`error_count` e usar espera exponencial; não repita chamadas em loop.
|
|
|
|
2.5. **Persista metas e decisões.** O estado do agente (`current_goal`,
|
|
`last_decision`) deve ser gravado no banco para auditoria e retomada.
|
|
|
|
2.6. **Não execute ações destrutivas por conta própria.** Decisões que
|
|
alterem dados de usuários ou excluam recursos exigem aprovação humana.
|
|
|
|
---
|
|
|
|
## 3. Regras para Desenvolvedores
|
|
|
|
3.1. **Estrutura Laravel 13 (estilo atual)**
|
|
- Middleware customizado em `app/Http/Middleware/`, registrado em
|
|
`bootstrap/app.php` via alias.
|
|
- Controllers em `app/Http/Controllers/{Api,Web}/`.
|
|
- Validação em `app/Http/Requests/`.
|
|
- Rotas em `routes/api.php` e `routes/web.php`.
|
|
|
|
3.2. **Migrations**
|
|
- Nunca edite uma migration já executada em produção; crie uma nova.
|
|
- Use tipos adequados (`foreignId`, `decimal` para coordenadas 3D).
|
|
|
|
3.3. **Eloquent**
|
|
- Declare relações e `casts()` nos models.
|
|
- Use `$fillable` (ou attributes `#[Fillable]`) para evitar mass-assignment.
|
|
|
|
3.4. **Autorização**
|
|
- `admin` e `user` são os papéis suportados (`User::ROLE_*`).
|
|
- Proteja rotas administrativas com o middleware `admin`.
|
|
|
|
3.5. **Testes**
|
|
- Rode `php artisan test` antes de considerar uma tarefa concluída.
|
|
- Rode `./vendor/bin/pint --test` para validar o estilo de código.
|
|
|
|
3.6. **Bibliotecas e licenças**
|
|
- Antes de adicionar qualquer dependência, verifique a licença.
|
|
- Apenas licenças que permitam uso comercial (MIT, Apache-2.0, BSD,
|
|
ISC, etc.) são aceitáveis.
|
|
- Registre a licença e o autor aqui (ver seção 4).
|
|
|
|
3.7. **Imagens e assets**
|
|
- Use apenas imagens, fontes e ícones de licença livre ou própria.
|
|
|
|
3.8. **Variáveis de ambiente**
|
|
- Adicione novas chaves ao `.env.example` (sem valores secretos).
|
|
- Documente o propósito no `.env` com comentário.
|
|
|
|
---
|
|
|
|
## 4. Registro de Bibliotecas e Licenças
|
|
|
|
| Biblioteca | Licença | Autor / Origem | Uso |
|
|
|---|---|---|---|
|
|
| Laravel Framework | MIT | Laravel LLC / Taylor Otwell | Backend |
|
|
| Laravel Sanctum | MIT | Laravel LLC | Tokens de API |
|
|
| Laravel Boost | MIT | Laravel LLC | Diretrizes do agente de IA |
|
|
| Three.js | MIT | Ricardo Cabello (Mr.doob) e contribuidores | Renderização 3D (Fase 2) |
|
|
| Tailwind CSS | MIT | Tailwind Labs | Estilos |
|
|
| Instrument Sans | OFL 1.1 | Instrument (Google Fonts) | Tipografia |
|
|
| PHP | PHP License | The PHP Group | Runtime |
|
|
| MariaDB | GPL / comercial | MariaDB Foundation | Banco de dados |
|
|
|
|
> Observação: licenças MIT, Apache-2.0, BSD, ISC e OFL permitem uso comercial
|
|
> livremente, atendendo à exigência da Syspanel. Registre aqui toda nova
|
|
> dependência antes de mergear.
|
|
|
|
---
|
|
|
|
## 5. Padrões de Código
|
|
|
|
5.1. Siga o estilo do Laravel (Pint). Formate com `./vendor/bin/pint`.
|
|
|
|
5.2. Prefira código explícito a "mágica" obscura; legibilidade primeiro.
|
|
|
|
5.3. Valide sempre a entrada do usuário (Form Requests).
|
|
|
|
5.4. Retorne respostas de erro consistentes (JSON com `message` e `errors`).
|
|
|
|
5.5. Use as traduções (`__()` / `@lang`) em vez de strings literais
|
|
no meio das views e controllers.
|
|
|
|
---
|
|
|
|
## 6. Commits e Versionamento
|
|
|
|
6.1. Mensagens de commit claras e no imperativo (ex.: `Add store CRUD API`).
|
|
|
|
6.2. Nunca commite: `.env`, chaves, `storage/logs/*`, `vendor/`, `node_modules/`.
|
|
|
|
6.3. Uma mudança por commit quando possível; mantenha o histórico legível.
|
|
|
|
---
|
|
|
|
© 2026 — Todos os direitos reservados — Powered by
|
|
[Syspanel](https://syspanel.com.br) — www.syspanel.com.br
|