merca y ch

project_plan.md

@@ -0,0 +1,472 @@
+
+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.