City10/docs/superpowers/plans/2026-10-18-citizens-persistence.md

Cidadãos Persistentes — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Each admin-approved user gets a persistent human-like character (needs, jobs, housing, family, chat) in a multi-city world that progresses via an always-on scheduler without requiring anyone online.

Architecture: Laravel 13 + MariaDB hold all character/world state. city:tick (every minute) applies need decay, salaries, building progress and simple offline AI. The existing Three.js viewer becomes a client for the caller's character (throttled position sync) plus action HUD/UI. Admin manages citizen approval, territory expansion and new cities.

Tech Stack: Laravel 13, PHP 8.3+, MariaDB, Sanctum (existing), Three.js viewer (existing), PHPUnit, Playwright MCP. No new production dependencies.

Spec: docs/superpowers/specs/2026-10-18-citizens-persistence-design.md

Global Constraints

• PHP 8.3+; follow existing conventions (Form Requests, #[Fillable], English PHPDoc, Pint).
• All user-visible strings in lang/pt_BR.json, lang/en.json, lang/es.json.
• LGPD protections, CAPTCHA, CSRF unchanged; no secrets in repo.
• php artisan test and vendor/bin/pint --test must pass before considering a task done.
• Registration must leave users pending until admin approval.
• World must progress with zero users online (city:tick + schedule:run).
• Character death is not simulated; needs floor at 0 with energy penalties only.

Review Focus

1. Unapproved login: user with status=pending must not enter dashboard/city; expect friendly wait screen + logout.
2. Tick idempotency: running city:tick twice in one minute must not double-decay needs or double-pay salary (guard by last_tick_at).
3. Ownership: actions (eat/build/sleep/position) must reject another user's character ID (403/422).
4. Build occupancy: two characters must not complete houses on the same footprint (unique site check by AABB).
5. City bounds: movement and building must clamp/fail outside active city bounds; new city layout must derive from cities.bounds, not only store positions.
6. Family graph: spouse requires accepted friendship; child requires both spouses; child NPC has user_id=null and never logs in.
7. Migration safety: existing is_active users become active and can still log in after the status column ships.

---

Task 1: Schema + seeders (cities, characters, buildings, relationships, inventory, transactions, jobs, messages)

Files:

• Create: database/migrations/2026_10_18_000100_add_status_to_users_table.php
• Create: database/migrations/2026_10_18_000200_create_cities_table.php
• Create: database/migrations/2026_10_18_000300_create_characters_table.php
• Create: database/migrations/2026_10_18_000400_create_buildings_table.php
• Create: database/migrations/2026_10_18_000500_create_relationships_table.php
• Create: database/migrations/2026_10_18_000600_create_inventory_items_table.php
• Create: database/migrations/2026_10_18_000700_create_transactions_table.php
• Create: database/migrations/2026_10_18_000800_create_jobs_table.php
• Create: database/migrations/2026_10_18_000900_create_character_messages_table.php
• Create: app/Models/City.php, Character.php, Building.php, Relationship.php, InventoryItem.php, Transaction.php, Job.php, CharacterMessage.php
• Create: database/factories/CharacterFactory.php, CityFactory.php
• Create: database/seeders/CityWorldSeeder.php (City10 + jobs; backfill users status; ensure characters for active users)
• Modify: database/seeders/DatabaseSeeder.php (register seeder)
• Modify: app/Models/User.php (status const/cast/relation)

Steps:

• Write migrations/models/factories/seeder per spec §3
• php artisan migrate in container
• Feature test: seeder creates City10 + character for active user; users.status backfilled
• Run php artisan test --filter=CityWorld and Pint
• Commit

Task 2: Registration pending + admin citizens approval

Files:

• Create: app/Http/Controllers/Web/Admin/CitizenAdminController.php
• Create: resources/views/admin/citizens/index.blade.php
• Create: app/Http/Requests/... if needed
• Modify: app/Http/Controllers/Web/AuthController.php (register → pending; login branch for pending)
• Create: resources/views/auth/pending.blade.php
• Modify: routes/web.php (admin citizens routes; pending view route or inline response)
• Modify: app/Http/Middleware/EnsureUserIsActive.php if needed
• Modify: lang files (pending/approve/ban strings)
• Modify: resources/views/dashboard or layout nav (Admin → Cidadãos link)

Steps:

• Failing tests: register creates pending; login as pending redirects to wait screen; admin approve activates + creates character; banned cannot login
• Implement controller/views/routes
• php artisan test --filter=Citizen green + Pint
• Commit

Task 3: World ticker city:tick + schedule

Files:

• Create: app/Console/Commands/CityTick.php
• Modify: routes/console.php (everyMinute)
• Create: tests/Feature/CityTickTest.php

Steps:

• Failing test: needs decay once per call; second immediate call no-ops; sleep recovers energy; work pays; building progress completes at 100
• Implement command + offline AI rules (spec §4)
• Tests green + Pint; php artisan schedule:list shows entry
• Commit

Task 4: City data payload + layout from bounds + character position sync

Files:

• Modify: app/Http/Controllers/Web/CityViewerController.php (city param, characters/buildings/jobs/bounds; layout from city bounds)
• Modify: app/Http/Controllers/Api/... if mirrored
• Create: app/Http/Controllers/Web/CityActionController.php (position + actions stubs for this task: position only)
• Modify: routes/web.php
• Create: tests/Feature/CityDataTest.php, CityPositionTest.php

Steps:

• Failing tests: /city/data includes own character + bounds; layout covers full bounds; position POST persists and clamps to bounds; cannot set another character
• Implement
• Tests green + Pint
• Commit

Task 5: Actions API (eat/drink/sleep/wake/work/study/buy/sell/build)

Files:

• Modify: app/Http/Controllers/Web/CityActionController.php
• Create: Form Requests under app/Http/Requests/
• Create: tests/Feature/CityActionsTest.php
• Modify: lang files (action labels/errors)

Steps:

• Failing tests per action happy path + key rejects (no house, no job, no money, occupied site, insufficient materials)
• Implement actions with DB transactions where money/inventory move
• Tests green + Pint
• Commit

Task 6: Social (friends, spouse, child, character chat)

Files:

• Modify: app/Http/Controllers/Web/CitySocialController.php (create)
• Create: app/Http/Controllers/Web/CharacterChatController.php or extend ChatController
• Create: tests/Feature/CitySocialTest.php
• Modify: lang files

Steps:

• Failing tests: friend request/accept; marry requires accepted friend + no existing spouse; child creates NPC character with parent links; message POST persists and is readable by recipient
• Implement
• Tests green + Pint
• Commit

Task 7: Admin territory expand + multi-city

Files:

• Create: app/Http/Controllers/Web/Admin/CityAdminController.php
• Create: resources/views/admin/cities/* (index + create + expand form)
• Modify: routes/web.php
• Create: tests/Feature/CityExpansionTest.php
• Modify: lang files

Steps:

• Failing tests: create city; expand bounds +40 up to cap; layout for new city uses its bounds
• Implement
• Tests green + Pint
• Commit

Task 8: Viewer frontend — own character, HUD needs, action menu, citizens, buildings

Files:

• Modify: resources/views/city/viewer.blade.php (HUD + action panel markup)
• Modify: public/js/city/app.js (own character control, needs HUD poll, action fetches, render characters/buildings from payload, bounds clamp, position throttle)
• Modify: lang files

Steps:

• Manual/Playwright: after Task 2–7, load /city, see own avatar, move persists (reload keeps position), action buttons update needs/money, second character visible, build marker
• No console errors; Pint N/A (JS); node --check app.js
• Commit

Task 9: End-to-end Playwright + bugfix pass

Files:

• Screenshots under .playwright-mcp/
• Fix any bugs found in previous tasks

Steps:

• Full journey: register → pending screen → admin approves → login → accept terms if needed → /city → move → eat/work/sleep → build house → friend with second user → chat → admin expand → new city
• Console clean; PHPUnit full suite green; Pint green
• Final commit