update plans; assign lifetime;kanban; column sort;
tests / ci (push) Canceled after 0s

This commit is contained in:
2026-11-04 11:10:05 -08:00
parent 177f122c10
commit 31a80ec4d1
26 changed files with 2984 additions and 672 deletions
+117
View File
@@ -0,0 +1,117 @@
# 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`.