Files

T

marcocosta10000 e7498e1566 feat(city): add airports, ATC agent, luminous signs, and AI model fallback chain

- 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.

2026-10-31 22:06:18 -03:00

5.8 KiB

Executable File

Raw Blame History

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.

5.8 KiB Executable File Raw Blame History