Files
mytodos/phases.md
T
2026-11-04 11:10:05 -08:00

6.6 KiB
Raw Blame History

Multi-User Access — Implementation Phases

Plan of record for adding multi-user access (workspaces, folder sharing, invitations) to mytodos. Tech: Laravel 13 / PHP 8.4 / MySQL / Livewire 4 SFC pages / Pest / Flux UI (free).

Status: Phases 1–3 complete and green (303 tests, 714 assertions). Phase 4 pending.


Access model (settled decisions)

  • Roles: admin > editor > marker > viewer (additive).
  • Effective folder role = max of:
    • creator → admin,
    • explicit folder_user share,
    • inherited ancestor shares,
    • workspace default: owner/admin → admin, member → viewer.
  • Folder visibility: private / workspace. Defaults: personal → private, family/org → workspace.
  • Explicit shares cascade down the subtree. A private folder drops out of inherited workspace access (workspace-wide grants flow only through workspace-visibility folders).
  • No deny semantics.
  • Todos have no ACL — they inherit their folder's access and organization_id. todos.user_id stays "created by".
  • Page scope: folders in the user's active workspace (users.current_organization_id) the user can access, plus folders explicitly shared with them from any workspace. Workspace-membership folders in non-active workspaces are NOT shown on pages.
  • Folder::scopeVisibleTo(Builder, User|int $user, ?int $workspaceId = null) and Todo::scopeVisibleTo(...). null workspaceId keeps broad behavior (model tests rely on it); pages pass activeWorkspaceId(): int.
  • organization_id is NOT NULL on folders and todos.

Phase 1 — Foundations ✅

  • Migrations 2026_10_10_214840–214847: workspaces (organizations), organization_user pivot (role), folder_user pivot (role, invited_by), invitations, plus organization_id on folders/todos, current_organization_id on users.
  • Models: Organization, Invitation; relations on User, Folder, Todo.
  • Enums: OrganizationRole, FolderRole, FolderVisibility (each with label()).
  • Policies: FolderPolicy (manageShares), OrganizationPolicy (manageMembers), InvitationPolicy (create/delete), TodoPolicy (auto-discovered).
  • Model scopes/helpers: Folder::scopeVisibleTo / treeForVisibleTo / flattenTree / creating hook; Todo::scopeVisibleTo / nextPositionFor.
  • Factories: OrganizationFactory (personal/family/withMember), FolderFactory (inOrganization/sharedWithWorkspace/private/childOf), InvitationFactory (forFolder/forOrganization/accepted/expired), UserFactory (unsubscribed).
  • Seeders pass organization_id explicitly.

Phase 2 — Access scoping in pages ✅

  • All three pages (folders, todo list, dashboard) use visibleFolder / folderForAction / activeWorkspaceId() and authorize with can() / @can.
  • Folder workspace label in the UI.
  • Tests: tests/Feature/SharedAccessPagesTest.php plus model-level coverage.

Phase 3 — Sharing & invitations ✅

  • Invitation model: EXPIRY_DAYS = 14; booted() creating hook (token Str::random(64), expires_at = Carbon::now()->addDays(14)); scopePending; isForFolder/isForWorkspace; folderRole/organizationRole; roleLabel; inviterName/inviteableName; accept(User).
  • Folder::invitations() MorphMany; treeForVisibleTo adds withCount('shares') (shares_count).
  • Mail: InvitationMail + resources/views/mail/invitation.blade.php. Sent synchronously (Mail::to($email)->send(...)); mail default driver log, QUEUE_CONNECTION=database. Invitations upserted on (inviteable_type, inviteable_id, email) with fresh token/expiry.
  • Accept page resources/views/pages/invitations/⚡accept.blade.php, route invitations/{invitation:token} name invitations.accept (auth-only). Seat-limit check; redirects to dashboard.
  • Folders page share modal (gated manageShares): visibility select (hidden + server-guarded for personal workspaces), collaborator list with role select + remove, invite-by-email + role, pending invitations + revoke.
  • Members page resources/views/pages/workspace/⚡members.blade.php, route members name members (subscribed). Seat usage, role change, remove (blocks self + owner; reassigns removed user to a personal workspace), invite (seat-limit aware), revoke.
  • Nav: "Members" item in resources/views/layouts/app/sidebar.blade.php and header.blade.php.
  • Tests: InvitationTest, InvitationAcceptPageTest, FolderSharingTest, WorkspaceMembersTest (helpers familyWorkspaceFor, membersWorkspaceFor).

Phase 4 — Workspace creation & switching + billing polish ⏳

Planned, not started. Candidate work:

  • Workspace creation flow (create personal/family/organization workspace; ownership).
  • Active-workspace switching UI (updates users.current_organization_id) in sidebar/header.
  • Workspace settings (rename, members already on the members page).
  • Billing polish: ensure plan/seat limits and upgrade prompts align with workspace type (config/workspaces.php seat limits: personal=1, family=6, organization=null; config/plans.php: subscription_type='default', trial_days=14, plan pro).
  • Additional migrations are allowed in Phase 4; Phases 1–3 migrations are frozen.

Verification

  • php artisan test → 303 passed, 714 assertions.
  • vendor/bin/pint --dirty --format agent (Pint formats .blade.php too).
  • vendor/bin/phpstan analyse --memory-limit=1G (Larastan, level 7). Note: the default composer types:check crashes at the 128M memory limit — pass --memory-limit=1G. 17 pre-existing errors remain in unrelated files (console seeders, Todo, legacy Folder helpers, policies). All Phase 1–3 feature files are clean.

Conventions & gotchas

  • #[Fillable]/#[Hidden] attributes; scopeXxx() naming; enums with label().
  • Create files via php artisan make:* --no-interaction.
  • Livewire Component base has no AuthorizesRequests; pages use abort_unless(auth()->user()->can(...), 403); blade uses @can.
  • Blaze compiler bug: Blade directives as attributes on a Flux component tag (@selected()/@checked() on <flux:select.option>) are mangled into a ParseError. Use wire:model (array dot paths) instead. Native <input @checked> is fine.
  • Livewire test harness renders HttpException/AuthorizationException into responses (assertStatus(403)); ModelNotFoundException propagates. #[Locked] props can't be set().
  • Livewire ->set() fires updated<Prop> hooks (used with memberRoles.{id}, collaboratorRoles.{id}).
  • Guest invites: accept page behind auth; unsubscribed users bounce to pricing via subscribed/EnsureSubscribed.