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

118 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.