ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/300-internal-tenant-model-naming-consolidation/tasks.md
ahmido 292d555eac refactor: consolidate internal tenant model naming (#355) 
## Summary
- consolidate internal platform naming from `Tenant` to `Environment` / `ManagedEnvironment` across models, controllers, services, and Filament resources
- rename environment-scoped UI surfaces such as dashboards, chooser flows, navigation, and related widgets to match the updated environment-first domain language
- align middleware, onboarding/review lifecycle services, jobs, and route/context controllers with the new environment-scoped architecture

## Validation
- not rerun as part of this commit/push/PR request

## Notes
- branch is 1 commit ahead of `platform-dev`
- main commit: `refactor: consolidate internal tenant model naming`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #355
2026-05-14 11:13:28 +00:00

176 lines
18 KiB
Markdown
Raw Permalink Blame History

# Tasks: Internal Tenant Model Naming Consolidation
**Input**: Design documents from `/specs/300-internal-tenant-model-naming-consolidation/`
**Prerequisites**: `spec.md`, `plan.md`, `tenant-reference-inventory.md`, `allowed-tenant-references.md`
**Tests**: Required. This is a runtime structural rename with route/RBAC equivalence requirements. Use Pest 4.3.1 and existing Browser smoke anchors.
## Test Governance Checklist
- [ ] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [ ] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
- [ ] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
- [ ] Planned validation commands cover the change without pulling in unrelated lane cost.
- [ ] The declared surface test profile or `standard-native-filament` relief is explicit.
- [ ] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel when files are disjoint.
- **[Story]**: US1 platform naming, US2 route/RBAC equivalence, US3 provider terminology.
- **Paths**: Use absolute repo paths in implementation notes and final report where useful.
## Phase 1: Setup And Baseline Safety
**Purpose**: Confirm the branch, repo state, dependency state, route truth, and scan volume before touching runtime code.
- [x] T001 Run `git status --short --branch`, `git diff --stat`, and `git log -1 --oneline` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`; stop if unrelated uncommitted changes exist.
- [x] T002 Confirm the implementation branch is `300-internal-tenant-model-naming-consolidation` or an isolated session branch derived from it.
- [x] T003 Review `/Users/ahmeddarrazi/Documents/projects/wt-plattform/AGENTS.md`, `.specify/memory/constitution.md`, this spec package, and Specs 297, 298, and 299.
- [x] T004 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/t|admin/tenants|workspaces/.*/environments|provider-connections|required-permissions|operations"`.
- [x] T005 Run the broad tenant scan from `spec.md` and capture output/counts in `specs/300-internal-tenant-model-naming-consolidation/tenant-reference-inventory.md`.
- [x] T006 Run the provider-specific scan from `spec.md` and capture output/counts in `specs/300-internal-tenant-model-naming-consolidation/allowed-tenant-references.md`.
- [x] T007 Run the migration/schema scan from `spec.md` and capture output/counts in `tenant-reference-inventory.md`.
- [x] T008 Confirm no production customer data or shared staging migration requirement exists. If this is false, stop and report `blocked by migration/schema risk`.
- [x] T009 Confirm current repo truth: `App\Models\ManagedEnvironment` and `managed_environments` are canonical; no active `App\Models\Tenant` model exists.
- [x] T010 Confirm scope boundary: no feature work, no compatibility layer, no broad provider abstraction, no OperationRun architecture change, no navigation redesign.
**Checkpoint**: Baseline inventory exists and implementation can proceed safely.
## Phase 2: Guard Tests First
**Purpose**: Add or update failing/protective tests before broad rename work.
- [x] T011 [P] [US1] Add/update a guard test in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php` proving no active `App\Models\Tenant`, `TenantFactory`, platform-owned `TenantResource`, `TenantDashboard`, `TenantDiagnostics`, or `TenantRequiredPermissions` owner remains after implementation.
- [x] T012 [P] [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php` to assert canonical environment URLs still generate `/admin/workspaces/{workspace}/environments/...`.
- [x] T013 [P] [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php` to assert `/admin/t/...`, `/admin/tenants/...`, and active `filament.admin.resources.tenants.*` route names remain absent.
- [x] T014 [P] [US2] Add/update route binding coverage in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ManagedEnvironment/ManagedEnvironmentRouteBindingTest.php` for `{environment}` or final chosen environment route parameter names.
- [ ] T015 [P] [US1] Add/update a stale helper guard proving `setTenantPanelContext`, `panel: 'tenant'`, and `panel: "tenant"` remain absent except documented negative guard literals.
- [ ] T016 [P] [US3] Add/update provider terminology tests proving `Microsoft tenant ID`, `Entra tenant ID`, `tenantId`, `entra_tenant_id`, and `microsoft_tenant_id` remain where provider-owned.
- [ ] T017 Run the new/updated focused guard tests and confirm they fail only for expected pre-implementation stale names.
**Checkpoint**: Guard coverage is in place before renames.
## Phase 3: DB, Migration, Factory, And Model Naming
**Purpose**: Align active platform-owned schema/model names with Managed Environment truth without compatibility shims.
- [ ] T018 [US1] Review all migration files under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/database/migrations` whose filenames or constraints mention tenants while operating on `managed_environments`.
- [ ] T019 [US1] Rename platform-owned migration filenames/comments/index/constraint names from tenant-first to managed-environment-first where safe under LEAN-001.
- [ ] T020 [US1] Preserve provider-owned columns such as `entra_tenant_id` and raw provider payload keys.
- [ ] T021 [US1] Rename platform-owned table names such as `tenant_permissions`, `tenant_role_mappings`, `tenant_settings`, `tenant_reviews`, `tenant_review_sections`, `tenant_triage_reviews`, and `managed_tenant_onboarding_sessions` only after classification confirms they represent Managed Environment truth.
- [ ] T022 [US1] Rename platform-owned model classes and factories that correspond to renamed tables, updating relationships, `$table`, casts, policies, factories, seeders, and tests.
- [ ] T023 [US1] Keep `App\Models\ManagedEnvironment`, `ManagedEnvironmentFactory`, `managed_environments`, and `managed_environment_id` as source-of-truth names.
- [ ] T024 [US1] Remove any old compatibility aliases created during the rename before moving past this phase.
- [ ] T025 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan migrate:fresh --seed` or document in `tenant-reference-inventory.md` why targeted migration validation is the narrower safe proof.
**Checkpoint**: Schema/model naming is environment-first or explicitly classified.
## Phase 4: Filament Resource, Page, Widget, And Route Owner Rename
**Purpose**: Remove active platform-owned Tenant technical owner names from Filament and route ownership.
- [x] T026 [US1] Rename `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php` to `ManagedEnvironmentResource.php` or the narrowest environment-first repo-conventional name.
- [x] T027 [US1] Rename nested TenantResource pages: `ListTenants`, `ViewTenant`, `EditTenant`, and `ManageTenantMemberships` to environment-first equivalents.
- [x] T028 [US1] Rename `TenantMembershipsRelationManager` to `ManagedEnvironmentMembershipsRelationManager` or the chosen environment-first equivalent.
- [x] T029 [US1] Rename `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantDashboard.php` to an environment-first page name.
- [x] T030 [US1] Rename `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantDiagnostics.php` to an environment-first page name.
- [x] T031 [US1] Rename `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php` to an environment-first page name.
- [x] T032 [US1] Rename environment-owned widgets under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Widgets/Tenant` and dashboard widgets that refer to the platform environment object.
- [x] T033 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php` route owner classes and route parameters from `{tenant}` to `{environment}` where feasible, preserving `/environments/...` URL segments.
- [x] T034 [US2] Ensure canonical link helpers use `ManagedEnvironmentLinks` and no runtime dependency on `TenantResource::getUrl(...)`, `TenantDashboard::getUrl(...)`, or `TenantRequiredPermissions::getUrl(...)` remains.
- [x] T035 [US2] Verify every renamed globally searchable Filament resource has a View/Edit page or disables global search.
- [x] T036 [US2] For any touched destructive action, verify it still uses `Action::make(...)->action(...)`, `->requiresConfirmation()`, authorization, notification, and audit behavior.
- [x] T037 [US2] Confirm Laravel 12 panel provider registration remains in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php` and no panel provider is added to `bootstrap/app.php`.
- [x] T038 [US2] If any Filament assets are newly registered unexpectedly, update deployment notes to include `cd apps/platform && php artisan filament:assets`; otherwise document asset strategy unchanged.
**Checkpoint**: Active Filament environment owners are environment-first and route shape is stable.
## Phase 5: Service, Support, Job, Policy, And Helper Rename
**Purpose**: Remove platform-owned Tenant-first technical vocabulary outside Filament.
- [x] T039 [US1] Rename `TenantMembershipManager` to `ManagedEnvironmentMembershipManager` and update DI, tests, and relation managers.
- [ ] T040 [US1] Rename `TenantDiagnosticsService`, `TenantRequiredPermissionsViewModelBuilder`, `TenantPermissionService`, and related platform-owned support classes where classification confirms Managed Environment truth. **Partial 2026-05-13:** renamed diagnostics and required-permissions view-model builder; broader permission/review/onboarding families remain unresolved.
- [ ] T041 [US1] Rename platform-owned support classes under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Tenants` to environment-first equivalents.
- [ ] T042 [US1] Rename platform-owned dashboard, backup health, inventory coverage, portfolio triage, and RBAC support classes that describe Managed Environment behavior.
- [ ] T043 [US1] Rename job constructor properties and named arguments such as `tenantId` only when they refer to platform Managed Environment IDs; preserve provider target-scope tenant IDs.
- [ ] T044 [US2] Preserve RBAC policy behavior and update only class names, method parameter names, PHPDoc, imports, and tests.
- [ ] T045 [US2] Keep workspace membership as role/capability authority and Managed Environment membership as narrowing-only.
- [ ] T046 [US3] Preserve provider-owned Graph, Entra, Azure, and target-scope terminology in Graph clients, provider connections, verification reports, onboarding provider identity fields, and raw payloads.
- [ ] T047 [US1] Rename platform-owned audit event/action names and audit metadata keys from tenant-first to managed-environment-first where classification confirms they refer to the platform object.
- [ ] T048 [US1] Rename platform-owned OperationRun metadata keys plus evidence/report/review references from `tenant_*` to managed-environment names while preserving provider payload keys.
**Checkpoint**: Platform-owned services/helpers/jobs/policies no longer rely on Tenant-first architecture names.
## Phase 6: Tests, Fixtures, Browser Anchors, And Documentation Artifacts
**Purpose**: Align tests and spec-local classification docs with final runtime state.
- [ ] T049 [US1] Rename stale test files, helper functions, fixtures, datasets, and factory helper methods that refer to the platform Managed Environment object as Tenant. **Partial 2026-05-13:** updated class imports, selected helper names, and guard expectations; many historical/stale test file names and schema/model fixture families remain.
- [ ] T050 [US1] Remove compatibility helpers such as `setTenantPanelContext`; keep only the environment/workspace helper style used by Specs 297-299.
- [x] T051 [US2] Update Browser smoke tests only where selectors or visible environment route anchors require it.
- [ ] T052 [US3] Update tests that assert provider-specific copy so they continue to expect Microsoft/Entra tenant terminology where provider-owned.
- [x] T053 [US1] Refresh `specs/300-internal-tenant-model-naming-consolidation/tenant-reference-inventory.md` with final file-level classification and `Fixed?` status.
- [x] T054 [US3] Refresh `specs/300-internal-tenant-model-naming-consolidation/allowed-tenant-references.md` with all final provider-specific, framework-required, historical, and regression-guard references.
- [ ] T055 [US1] Ensure historical specs remain untouched except using them as dependency context.
**Checkpoint**: Tests and classification artifacts match the final implementation.
## Phase 7: Focused Validation
**Purpose**: Prove route, RBAC, provider, Filament, and browser behavior after the rename.
- [x] T056 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/t|admin/tenants|workspaces/.*/environments|operations|provider-connections|required-permissions"` and record route contract outcome.
- [ ] T057 [US1] Run the broad tenant scan and confirm no unclassified active platform-owned tenant references remain. **Failed 2026-05-14:** scan still finds 1585 files with active tenant references; unresolved schema/model/resource families remain.
- [ ] T058 [US3] Run the provider-allowed scan and confirm all remaining provider terms are documented. **Partial 2026-05-14:** provider terms are preserved in 433 files, but final exhaustive classification is blocked by unresolved platform-owned references.
- [ ] T059 [US1] Run the migration/schema scan and confirm all platform-owned DB names are environment-first or explicitly classified. **Failed 2026-05-14:** tenant-named table/model families remain active across 131 files and current PostgreSQL schema.
- [x] T060 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards`.
- [x] T061 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces`.
- [x] T062 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections`.
- [x] T063 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions`.
- [x] T064 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament`.
- [x] T065 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac`.
- [x] T066 [US2] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php tests/Browser/Spec299WorkspaceOverviewCutoverSealSmokeTest.php`.
- [x] T066A [US2] Add and run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec300ManagedEnvironmentNamingConsolidationSmokeTest.php` for the Spec 300 workspace overview, environment dashboard, operations, provider connection, required-permissions, and browser-console proof.
- [x] T067 [US1] Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- [x] T068 [US1] Run `git diff --check`.
**Checkpoint**: Focused validation has passed or a stop decision is documented.
## Phase 8: Final Report
**Purpose**: Produce the required implementation close-out without hiding unresolved references.
- [ ] T069 [US1] Report exact commands run and outcomes.
- [ ] T070 [US1] Report rename summary using the table `Old | New | Type | Files`.
- [ ] T071 [US1] Report DB changes using the table `Old table/column | New table/column | Migration/action`.
- [ ] T072 [US3] Report remaining tenant references using the table `Reference | File | Category | Why allowed`.
- [ ] T073 [US2] Report route contract status for workspace/environment routes, `/admin/t/...`, `/admin/tenants/...`, provider tenantless routes, and workspace operations routes.
- [ ] T074 [US2] Report validation results including test counts, assertions, skipped tests, Browser smoke result, Pint result, and `git diff --check`.
- [ ] T075 [US1] Declare exactly one final decision:
- `merge-ready; internal tenant naming consolidation complete`
- `merge-ready with documented provider/framework tenant references`
- `blocked by unresolved platform-owned tenant references`
- `blocked by migration/schema risk`
- `incomplete; canonical route or RBAC regression found`
## Dependencies And Ordering
- Phase 1 blocks all runtime edits.
- Phase 2 guard tests should precede broad renames.
- Phase 3 schema/model work should precede Filament/resource work where classes depend on model/table names.
- Phase 4 and Phase 5 can be split by disjoint file ownership once route/model names settle.
- Phase 6 must run after runtime renames.
- Phase 7 and Phase 8 are final validation and close-out only.
## Explicit Non-Implementation Boundaries
- Do not add a `Tenant` alias class.
- Do not revive `TenantPanelProvider`.
- Do not restore `/admin/t/...` or `/admin/tenants/...`.
- Do not rename provider-owned `tenantId`, `entra_tenant_id`, or `microsoft_tenant_id`.
- Do not rewrite completed Specs 297-299.
- Do not create a new provider framework.
- Do not change OperationRun status/outcome semantics.
Reference in New Issue View Git Blame Copy Permalink