This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user