Benell/project_plan.md

Plan

project_plan.md — Projects Navigation V1.2 (Dedicated Pages + Weekly Calendar + Capture)
Summary
We will replace the current Projects “single long page + scroll-to-section” behavior with true page-based navigation and a Projects-specific information architecture.

V1.2 will deliver:

A coherent Projects sidebar with dedicated routes.
A real Meetings page with weekly calendar view.
Auto-populated calendar meetings with attendee confirmation (pending/accepted/declined).
A new Capture page for evidence (links + local file uploads on server).
Backward-compatible redirects from old alias routes.
This keeps the existing Projects operational backend and removes the current marketing-style navigation confusion.

Current-State Findings (what we are fixing)
/departments/projects/initiatives and /departments/projects/meetings are aliases to the same page.
Projects page uses scrollIntoView based on pathname instead of real page navigation.
Sidebar/mobile nav currently repurposes generic “initiatives/meetings” keys and points to alias routes.
Meetings UI is embedded as a section (MeetingsWidget) instead of a dedicated planning surface.
Capture currently exists only as generic /data-entry placeholder, not Projects-specific evidence operations.
V1.2 Information Architecture (locked)
Projects Sidebar (for department=proyectos)
Overview → /departments/projects
Projects → /departments/projects/projects
Meetings → /departments/projects/meetings
Capture → /departments/projects/capture
Team → /departments/projects/team
Behavior rules
No sidebar item may trigger section scrolling.
Each sidebar item maps to its own page route and URL state.
Active nav state is based on pathname prefix, not hash/scroll.
Mobile nav uses identical route map and active logic.
Compatibility routes
/departments/projects/initiatives redirects to /departments/projects/projects.
Existing /departments/projects/meetings alias is replaced with a real page (no re-export).
Old intra-page anchor behavior is removed.
Page Specifications
1) Overview Page (/departments/projects)
Purpose: operational snapshot.

Header: title, date/location filters, Nuevo proyecto.
KPI strip: active projects, milestones on-time, blocked tasks, overdue tasks, cost variance, profit/margin.
Alerts: blocked tasks, overdue milestones, cost variance risk.
Top portfolio summary table (read-only quick scan, row opens project drawer).
“My workload” panel for assigned tasks and upcoming commitments.
No meetings form here; only compact “next meetings” preview with link to Meetings page.
2) Projects Page (/departments/projects/projects)
Purpose: project execution workspace.

Full portfolio table and filters.
Project detail drawer for definition, stages, financials, milestones, tasks.
Milestone board + task board with execution updates.
Leaders/owners can create/edit/delete project objects.
Employees see execution-only controls as currently enforced.
3) Meetings Page (/departments/projects/meetings)
Purpose: weekly planning and scheduling.

Weekly calendar view (Mon-Sun), 30-min slots, default 07:00-21:00.
Hybrid feed:
My personal events.
Team meetings where user is organizer/participant.
Meeting cards display status + attendee response summary.
Create event modal:
Tipo: meeting or personal_event
title, agenda/notes, start/end, participants.
Meetings created from Projects are auto-added to calendar.
Confirmation flow:
Invitees start as pending.
Invitee can accept or decline.
Organizer sees response counts and unresolved attendees.
Filters: All, Mine, Team, Pending response.
4) Capture Page (/departments/projects/capture)
Purpose: evidence intake and traceability.

Tabs:
Task Evidence
Project Evidence
My Uploads
Capture form:
association: project/task
evidence type: photo, document, link
title, note
link URL OR local file upload
Evidence list:
preview thumbnail (images), file badge, link badge
uploader, timestamp, associated project/task
Search/filter by project, task, uploader, date range.
Deletion permissions:
uploader can delete own evidence
leaders/owners can delete any project evidence.
5) Team Page (/departments/projects/team)
Purpose: project people visibility.

Team members list, role, current assigned tasks, blocked items.
Quick links to person detail (/people/:id) and assigned projects.
Read-only in V1.2 (management actions remain in People module).
Data Model / Persistence Changes
Prisma additions
MarketingMeetingParticipant (new table):
id
meetingId
userId (nullable for external participants if needed)
displayName
responseStatus enum: pending | accepted | declined
respondedAt
unique composite (meetingId, userId) when userId is present
ProjectCalendarEvent (new table):
id, department (default proyectos)
ownerUserId
title, notes
startAt, endAt
visibility (personal|team)
createdAt, updatedAt
ProjectCaptureEvidence (new table):
id, department
initiativeId nullable
taskId nullable
uploadedById
kind (photo|document|link)
title, note
url nullable
storagePath nullable
mimeType nullable
sizeBytes nullable
createdAt, updatedAt
Local upload storage defaults (locked)
Storage mode: server local uploads.
Base directory: PROJECT_UPLOAD_DIR (default /home/mdares03/benell/uploads/projects).
Max file size: 10 MB.
Allowed mime/extensions: image/jpeg, image/png, image/webp, application/pdf.
Files served through authenticated API route, not direct public static path.
Filenames replaced with generated IDs (no user filename trust).
Public API / Interface / Type Changes
Navigation/access
Update nav mapping so Projects gets dedicated route set and labels.
Keep shared nav for other departments unchanged.
Update active-state logic in Sidebar and MobileNav for new subroutes.
Meetings + calendar APIs
GET /api/projects/meetings
include participants with responseStatus and counts.
POST /api/projects/meetings
creates meeting + participant rows (pending).
calendar inclusion metadata returned.
PATCH /api/projects/meetings/:id
schedule/complete/cancel as today, plus participant updates when needed.
PATCH /api/projects/meetings/:id/respond (new)
attendee sets accepted|declined.
GET /api/projects/calendar/events (new)
POST /api/projects/calendar/events (new)
PATCH /api/projects/calendar/events/:id (new)
DELETE /api/projects/calendar/events/:id (new)
Capture APIs
GET /api/projects/capture (new, filterable list)
POST /api/projects/capture/link (new)
POST /api/projects/capture/upload (new, multipart/form-data)
DELETE /api/projects/capture/:id (new)
GET /api/projects/capture/assets/:id (new, secure file stream)
Type updates
Add Projects nav type map for page keys/labels/routes.
Add MeetingParticipant, MeetingResponseStatus.
Add ProjectCalendarEvent.
Add ProjectCaptureEvidence + upload response payloads.
RBAC Rules (explicit)
Owner:
full access across Projects pages/APIs.
Projects leader:
full management in Projects module.
Projects employee:
can view all Projects pages.
can update assigned tasks.
can respond to meeting invitations involving them.
can create personal calendar events.
can upload evidence tied to own tasks/assigned projects.
Non-project departments:
cannot access /departments/projects/* pages or Projects APIs.
Implementation Sequence (decision complete)
Foundation refactor:
extract Projects page sections into reusable components.
remove scrollIntoView route behavior.
Route scaffolding:
add real pages for projects, meetings, capture, team.
add redirect from /departments/projects/initiatives.
Nav/access updates:
route maps, labels, active-state logic for desktop/mobile.
Meetings participant model:
Prisma migration + API updates + response endpoint.
Calendar events model:
Prisma migration + CRUD APIs + weekly calendar UI.
Capture model + local uploads:
Prisma migration + upload/link endpoints + secure asset serving.
Capture UI:
forms, association selectors, evidence feed, filters.
Regression pass:
ensure marketing routes remain unaffected and no broken links.
Production readiness:
upload dir creation/permissions + env vars + service restart checklist.
File Touchpoints (expected)
src/components/layout/nav-items.ts
src/components/layout/Sidebar.tsx
src/components/layout/MobileNav.tsx
src/lib/access-control.ts
src/app/(app)/departments/projects/page.tsx (overview only)
src/app/(app)/departments/projects/initiatives/page.tsx (redirect)
src/app/(app)/departments/projects/projects/page.tsx (new)
src/app/(app)/departments/projects/meetings/page.tsx (real calendar page)
src/app/(app)/departments/projects/capture/page.tsx (new)
src/app/(app)/departments/projects/team/page.tsx (new)
src/app/api/projects/meetings/route.ts
src/app/api/projects/meetings/[id]/route.ts
src/app/api/projects/meetings/[id]/respond/route.ts (new)
src/app/api/projects/calendar/events/route.ts (new)
src/app/api/projects/calendar/events/[id]/route.ts (new)
src/app/api/projects/capture/* (new route group)
src/lib/projects/types.ts
src/lib/projects/persistence.ts
prisma/schema.prisma
Prisma migration files for new models/enums.
Test Cases and Scenarios
Navigation correctness
Sidebar Overview/Projects/Meetings/Capture/Team each open distinct page.
No route causes in-page scroll jumps.
/departments/projects/initiatives redirects to /departments/projects/projects.
Mobile nav mirrors desktop routes and active states.
Meetings/calendar flow
Create Projects meeting from UI appears on weekly calendar.
Invitee sees meeting as pending.
Invitee accepts; organizer sees updated counts and status badge.
Invitee declines; event remains visible with declined marker.
Personal event creation appears only in owner’s view unless visibility is team.
Capture flow
Upload image/pdf successfully and metadata persists.
Add link evidence successfully and renders in feed.
Evidence can be tied to project and/or task.
Unauthorized user cannot fetch another department’s capture asset.
Delete permissions enforce uploader-or-manager rule.
RBAC
Employee cannot alter project definition/stage/targets.
Employee can update assigned tasks and submit evidence.
Non-project user gets 403 on projects APIs and pages.
Owner retains full access.
Regression
Marketing and other departments still navigate correctly.
Existing Projects financial logic remains intact.
Build/lint/typecheck pass.
No broken internal links in sidebar/mobile and page CTAs.
Acceptance Criteria
Projects navigation is page-based, not section-scroll based.
Meetings has a weekly calendar and confirmation workflow.
Meetings auto-populate calendar on creation.
Capture page supports links and local file uploads with evidence traceability.
Sidebar labels and routes are coherent for Projects operations.
No broken links and no cross-department permission leakage.
Assumptions and Defaults Chosen
Storage for Capture in V1.2 is local server filesystem (as selected).
Timezone display defaults to app/user locale; stored timestamps remain UTC.
Existing meeting statuses remain (requested/scheduled/completed/cancelled); attendee response is separate participant state.
Marketing module behavior and routes are not redesigned in this phase.
Team page is read-only in V1.2; People module remains source of truth for personnel edits.

Execution Checklist (Projects Lead Runbook)
Objective
Ship V1.2 with stable navigation, calendar + attendee confirmations, and evidence capture without regressions in other departments.

Operating cadence
Monday planning:
- review Overview KPIs and alerts.
- lock weekly priorities and milestone owners.
- publish all team meetings for the week in Meetings page.
Daily control loop:
- triage blocked and overdue items in Overview.
- unblock/escalate anything aging >24h.
- enforce project/task updates in Projects page only.
Friday close:
- verify evidence completeness in Capture.
- close unresolved meeting responses.
- publish weekly delivery summary and carry-over risks.

Definition of done (workflow)
- A task cannot be marked complete without evidence (link or upload) tied to task or project.
- Every milestone has owner, due date, status, and risk flag.
- Every meeting has agenda, participants, and decision notes.
- Every blocker has escalation owner and next action date.

Phase-based implementation checklist
Phase 0 - preflight (0.5 day)
- confirm V1.2 scope lock with engineering + design.
- confirm env var defaults for uploads and filesystem permissions.
- capture baseline behavior videos/screenshots for regression comparison.
- define feature flags if rollout will be staged.
Exit criteria:
- scope is frozen, rollout owner assigned, baseline captured.

Phase 1 - navigation foundation (1 day)
- remove in-page scroll navigation behavior from Projects.
- implement dedicated Projects route map in desktop and mobile nav.
- add compatibility redirect `/departments/projects/initiatives -> /departments/projects/projects`.
- validate active-state logic by pathname prefix.
Exit criteria:
- each sidebar item opens a distinct page; no scroll jump behavior remains.

Phase 2 - route scaffolding and page split (1 to 1.5 days)
- keep Overview at `/departments/projects`.
- create real pages: `/projects`, `/meetings`, `/capture`, `/team`.
- move existing reusable sections/components out of monolithic page.
- ensure role-based access gates on new routes.
Exit criteria:
- all five pages render and route correctly for allowed roles.

Phase 3 - meetings participants model (1 day)
- Prisma migration for `MarketingMeetingParticipant`.
- update meetings list/create/update APIs to include participant rows and counts.
- add response endpoint `PATCH /api/projects/meetings/:id/respond`.
- display pending/accepted/declined summaries in meetings UI.
Exit criteria:
- invitation lifecycle works end-to-end with correct counts.

Phase 4 - calendar events model + weekly UI (1.5 to 2 days)
- Prisma migration for `ProjectCalendarEvent`.
- CRUD APIs for calendar events.
- weekly calendar UI (Mon-Sun, 30-min slots, 07:00-21:00 default).
- auto-create calendar event when Projects meeting is created.
- filters: All, Mine, Team, Pending response.
Exit criteria:
- new meetings appear in calendar; personal and team events behave as expected.

Phase 5 - capture model + secure local uploads (2 days)
- Prisma migration for `ProjectCaptureEvidence`.
- implement link create/list/delete APIs.
- implement upload endpoint with MIME/size validation (10 MB max).
- implement secure asset stream endpoint (authenticated, RBAC checked).
- implement capture UI tabs and filterable evidence feed.
Exit criteria:
- links and files are persisted, visible, downloadable, and permission-protected.

Phase 6 - regression + hardening (1 day)
- run navigation, RBAC, meetings/calendar, and capture scenarios.
- run typecheck/lint/build and fix all blocking defects.
- verify non-project departments unchanged.
- verify no broken internal links.
Exit criteria:
- acceptance criteria pass and release notes are ready.

Implementation Tickets (V1.2 Backlog)
PJT-1201 - Projects nav route map refactor
Scope:
- update `nav-items.ts`, `Sidebar.tsx`, `MobileNav.tsx` for dedicated Projects IA.
- remove alias/section-scroll assumptions.
Depends on:
- none
Acceptance:
- Projects shows Overview, Projects, Meetings, Capture, Team routes with correct active state.

PJT-1202 - Redirect compatibility for legacy initiatives route
Scope:
- implement redirect from `/departments/projects/initiatives` to `/departments/projects/projects`.
Depends on:
- PJT-1201
Acceptance:
- direct visits and in-app links always land on `/projects`.

PJT-1203 - Split Projects monolith into dedicated pages
Scope:
- scaffold and render page-specific components for overview/projects/meetings/capture/team.
Depends on:
- PJT-1201
Acceptance:
- each page has unique URL and no in-page scroll coupling.

PJT-1204 - Meeting participant persistence model
Scope:
- add `MarketingMeetingParticipant` model and migration.
- wire participants into meetings APIs.
Depends on:
- PJT-1203
Acceptance:
- meetings return participant response states and summary counts.

PJT-1205 - Meeting invite response endpoint
Scope:
- add `PATCH /api/projects/meetings/:id/respond`.
- enforce participant-only response updates.
Depends on:
- PJT-1204
Acceptance:
- invitees can accept/decline; organizer sees live status changes.

PJT-1206 - Calendar events persistence + APIs
Scope:
- add `ProjectCalendarEvent` model + CRUD routes.
- enforce personal/team visibility rules.
Depends on:
- PJT-1203
Acceptance:
- create/edit/delete works with role constraints and list filters.

PJT-1207 - Weekly calendar UI
Scope:
- render weekly grid in Meetings page with 30-min slots and default hours.
- add create event modal.
Depends on:
- PJT-1206
Acceptance:
- events show in correct slots and respect filter mode.

PJT-1208 - Auto-populate calendar from meetings
Scope:
- create/maintain linked calendar records for project meetings.
Depends on:
- PJT-1204, PJT-1206
Acceptance:
- meeting creation always appears in calendar without manual duplication.

PJT-1209 - Capture evidence persistence model
Scope:
- add `ProjectCaptureEvidence` model + migration.
Depends on:
- PJT-1203
Acceptance:
- evidence rows support project/task relation, metadata, and ownership.

PJT-1210 - Capture link and upload APIs
Scope:
- implement list/create/delete routes for link and file evidence.
- enforce 10 MB and MIME allowlist.
Depends on:
- PJT-1209
Acceptance:
- valid uploads succeed, invalid files are rejected with clear errors.

PJT-1211 - Secure capture asset streaming
Scope:
- authenticated download route by evidence id.
- prevent cross-department and unauthorized access.
Depends on:
- PJT-1210
Acceptance:
- authorized users can fetch assets; unauthorized users receive 403.

PJT-1212 - Capture UI tabs and evidence feed
Scope:
- implement Task Evidence / Project Evidence / My Uploads tabs.
- implement preview badges and filters.
Depends on:
- PJT-1210, PJT-1211
Acceptance:
- users can upload, filter, preview, and delete per permission rules.

PJT-1213 - Projects RBAC enforcement sweep
Scope:
- verify page/API protections for owner, leader, employee, non-project users.
Depends on:
- PJT-1203 through PJT-1212
Acceptance:
- RBAC matrix in plan passes all listed scenarios.

PJT-1214 - Regression, QA, and release checklist
Scope:
- execute test scenarios and fix defects.
- finalize deployment steps: upload directory, env vars, service restart checks.
Depends on:
- PJT-1201 through PJT-1213
Acceptance:
- all acceptance criteria pass; no navigation regressions outside Projects.

KPIs to track during rollout
- Navigation defects: target 0 critical.
- Meeting invite response within 24h: target >=90%.
- Evidence completeness on completed tasks: target >=95%.
- Blocker aging >48h: target 0 without escalation owner.
- Milestones delivered on time: upward trend week-over-week.