Satyam Rastogi
124 lines
10 KiB
Markdown
124 lines
10 KiB
Markdown
# Plan 2 — Unify Lead↔Project + Routing/Naming
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`). Follow the execution protocol (`2026-05-29-execution-protocol.md`) — parallel only where lanes are disjoint.
|
||
|
||
**Goal:** Make a *won* kanban lead the same entity as a project — one data model, one rich detail page, clean `/…/projects/:id` routes, and unified `PRJ-2026-###` ids.
|
||
|
||
**Architecture:** Migrate `proj_###`→`PRJ-2026-###` (with inbound FKs), convert the 16 won kanban leads (kl_023–kl_038) into full `projects` records (normalizing field names + back-filling missing project fields) linked back to their kanban lead, route all won jobs to the existing rich `OwnerProjectDetail` under owner/admin/field-agent prefixes, and relink the kanban drawer + project list. Pre-sale leads (kl_001–022, 039–044) stay as leads on the lighter `LeadProjectPage`.
|
||
|
||
**Tech stack:** React 18, Vite 7, mock context store, pnpm. No test harness → verify via `npm run build` + grep/reconciliation + dev-run.
|
||
|
||
**Spec/master:** `docs/superpowers/specs/2026-05-29-demo-data-coherence-design.md`, `docs/superpowers/2026-05-29-MASTER-PLAN.md`.
|
||
|
||
---
|
||
|
||
## Lane / ownership map (for safe parallelism)
|
||
|
||
| Task | Lane (exclusive files) | Phase |
|
||
|------|------------------------|-------|
|
||
| T1 Id migration | `src/data/mockStore.jsx` | A (sequential) |
|
||
| T2 Convert won leads → projects | `src/data/mockStore.jsx` | A (sequential, after T1) |
|
||
| T3 Detail page role access | `src/pages/owner/OwnerProjectDetail.jsx` | B (parallel) |
|
||
| T4 Routes | `src/App.jsx` | B (parallel) |
|
||
| T5 Kanban relink | `src/components/kanban/LeadInfoDrawer.jsx`, `src/pages/KanbanPage.jsx` | B (parallel) |
|
||
| T6 Project list relink | `src/pages/owner/OwnerProjectList.jsx` | B (parallel) |
|
||
| T7 Verify | (read-only) | C |
|
||
|
||
**Phase A (T1, T2) is strictly sequential** — both edit `mockStore.jsx`. **Phase B (T3–T6) may run in parallel** — disjoint files, and all depend only on Phase A being committed. **T7** runs last.
|
||
|
||
---
|
||
|
||
## Field normalization map (T2 — kanban project data → project schema)
|
||
|
||
| Kanban (`KANBAN_PROJECT_DATA` / lead) | Project schema |
|
||
|----|----|
|
||
| `estimatedAmount` | `budget` and `approvedBudget` |
|
||
| `completionPct` | `completionPercentage` |
|
||
| `workTimeline[]` | `activityTimeline[]` (same item shape) |
|
||
| milestone `{date}` | milestone `{dueDate}` (keep id/name/status; `assignedTo` = contractor id) |
|
||
| invoice `{description, paidDate}` | invoice `{submittedBy, datePaid}` (keep id/amount/status/dueDate; submittedBy = contractor/sub id) |
|
||
| rfi `{openedDate, closedDate}` | rfi `{dateOpened, dateClosed}` |
|
||
| changeOrder `{requestedBy, date}` | changeOrder `{dateSubmitted}` (keep id/title/amount/status/description) |
|
||
| `contractorName`/`contractorPhone` | `contractorId` (map "Mike Brennan"→`con_001`; keep others if a different contractor) |
|
||
| lead `name`/`address`/`phone`/`email` | becomes the project's customer/`address`; keep a `customer` block |
|
||
|
||
**Back-fill (required so the rich tabs aren't broken/empty):** `ownerId` (assign own_001 or own_002), `phase`, `committedCost` (≈ between actualCost and budget), `spent`=`actualCost`, `variancePercent`=round((actualCost−budget)/budget×100,1), `margin`, `commissionType`/`commissionRate`/`commission`, `teamMembers[]` (≥ sales rep p1/p2 + contractor con_001), `subcontractorIds[]`, `riskLog`/`issueLog` (may be `[]`), `paymentSchedule[]`, `openRFIs`/`changeOrderCount`/`pendingInvoiceCount` (computed from the arrays), `budgetBreakdown[]` (Plan-1 invariants: allocated→budget, committed→committedCost, actual→actualCost, committed≥actual), `startDate`/`endDate`, `healthScore`. **Reuse the existing `KANBAN_PROJECT_DATA` numbers; only fill genuine gaps.**
|
||
|
||
---
|
||
|
||
## Task 1: Migrate project ids `proj_###` → `PRJ-2026-###`
|
||
|
||
**Files:** `src/data/mockStore.jsx` only.
|
||
|
||
- [ ] **Step 1:** `git grep -n "proj_0" -- src/data/mockStore.jsx` to enumerate every `proj_###` — both the `projects[].id` definitions AND inbound FKs (`projectId: 'proj_###'`) in tasks, schedule, `MOCK_SUBCONTRACTOR_TASKS`, and anywhere else.
|
||
- [ ] **Step 2:** Replace each `proj_001`→`PRJ-2026-001`, … `proj_012`→`PRJ-2026-012`, **consistently across the whole file** (definitions + all FKs) so every reference still resolves. Use replace_all per id.
|
||
- [ ] **Step 3 (verify):** `git grep -n "proj_0" -- src/data/mockStore.jsx` → NO matches. Every `projectId` FK now reads `PRJ-2026-###`.
|
||
- [ ] **Step 4:** `npm run build` → `✓ built`, zero errors.
|
||
- [ ] **Step 5 (reconcile FKs):** confirm no subcontractor task / schedule entry references a `projectId` that doesn't exist in `projects` (grep the new ids; each FK must match a project id).
|
||
- [ ] **Step 6:** commit `git commit -m "refactor(data): migrate project ids to PRJ-2026-### (with inbound FKs)"`.
|
||
|
||
## Task 2: Convert the 16 won kanban leads into project records
|
||
|
||
**Files:** `src/data/mockStore.jsx` only. **Runs after T1.**
|
||
|
||
- [ ] **Step 1:** Read `KANBAN_LEADS_INITIAL` for kl_023–kl_038 and their `KANBAN_PROJECT_DATA` entries.
|
||
- [ ] **Step 2:** For each of the 16, append a new object to the `projects` array with id `PRJ-2026-013`…`PRJ-2026-028`, mapping fields per the Normalization Map and back-filling per the Back-fill list. Add `sourceLeadId: '<kl_id>'` to the project, and `projectId: '<PRJ id>'` to the corresponding kanban lead (so the board links to the project). Keep the kanban lead's `columnId` (it still shows in Signed/Progress/Complete).
|
||
- [ ] **Step 3:** Assign realistic `ownerId` (split across own_001/own_002), `teamMembers` (canonical people), and a `contractorId` (con_001 unless the data names another). Vary `phase`/`status` to match the lead's stage (signed→Scope Approved/Contract Signed, progress→Work In Progress, complete→Completed).
|
||
- [ ] **Step 4 (reconcile):** every new project satisfies Plan-1 financial invariants (Σbreakdown columns == totals; committed≥actual; spent==actualCost; variancePercent sign correct). Write a throwaway node check to /tmp if helpful; do NOT commit it.
|
||
- [ ] **Step 5:** `npm run build` → `✓ built`, zero errors.
|
||
- [ ] **Step 6:** commit `git commit -m "feat(data): convert won kanban leads (kl_023-038) into unified project records"`.
|
||
|
||
## Task 3: Let owner/admin/field-agent view a project (relax owner-only lookup)
|
||
|
||
**Files:** `src/pages/owner/OwnerProjectDetail.jsx` only. **Phase B (parallel).**
|
||
|
||
- [ ] **Step 1:** Find the lookup `projects.find(p => p.id === projectId && p.ownerId === user?.id)` (~line 296). Relax it so ADMIN/OWNER/FIELD_AGENT can view: match by id, and only enforce ownerId when `user.role === 'OWNER'` (owners see their own; admin/field-agent see any). Keep the not-found fallback.
|
||
- [ ] **Step 2:** `npm run build` → `✓ built`.
|
||
- [ ] **Step 3:** commit `git commit -m "fix(projects): allow admin/field-agent to open project detail, not just owner"`.
|
||
|
||
## Task 4: Add the unified `/projects/:projectId` route (Option B)
|
||
|
||
**Files:** `src/App.jsx` only. **Phase B (parallel).**
|
||
|
||
We adopt the final Option-B scheme for the projects route now — a single, role-prefix-free URL — so won leads and projects share one page. The **attribute-based access guard arrives in Phase 8**; for the interim, gate with a coarse `allowedRoles`.
|
||
|
||
- [ ] **Step 1:** Add a route `/projects/:projectId` → `OwnerProjectDetail`, gated `allowedRoles={['OWNER','ADMIN','FIELD_AGENT']}` (interim coarse guard — Phase 8 replaces it with the ABAC policy guard). Leave the existing `/owner/projects/:projectId` route in place for now (Phase 8 removes the duplicate). Do NOT add `/admin/projects` / `/emp/fa/projects` role-prefixed copies.
|
||
- [ ] **Step 2:** `npm run build` → `✓ built`.
|
||
- [ ] **Step 3:** commit `git commit -m "feat(routes): add unified /projects/:id route for the shared detail page"`.
|
||
|
||
## Task 5: Relink the kanban drawer so won leads open the project page
|
||
|
||
**Files:** `src/components/kanban/LeadInfoDrawer.jsx`, `src/pages/KanbanPage.jsx`. **Phase B (parallel).**
|
||
|
||
- [ ] **Step 1:** In `LeadInfoDrawer.jsx` (~line 302) the "More Details" button does `navigate(\`${basePath}/leads/${lead.id}\`)`. Change it so: if the lead has a `projectId` (won), navigate to the unified `\`/projects/${lead.projectId}\`` (no basePath); else keep `\`${basePath}/leads/${lead.id}\`` (pre-sale leads stay role-prefixed until Phase 8).
|
||
- [ ] **Step 2:** Check `KanbanPage.jsx` for any other lead→detail navigation and apply the same conditional.
|
||
- [ ] **Step 3:** `npm run build` → `✓ built`.
|
||
- [ ] **Step 4:** commit `git commit -m "feat(kanban): won leads open the unified project page; pre-sale leads stay on lead page"`.
|
||
|
||
## Task 6: Relink the project list's pipeline entries
|
||
|
||
**Files:** `src/pages/owner/OwnerProjectList.jsx` only. **Phase B (parallel).**
|
||
|
||
- [ ] **Step 1:** This page lists both construction projects and pipeline leads (links ~lines 280/366 and 499/565). Point ALL project links AND won pipeline leads (those with a `projectId`) at the unified `/projects/:id`. Pre-sale leads keep `/owner/leads/:id`.
|
||
- [ ] **Step 2:** `npm run build` → `✓ built`.
|
||
- [ ] **Step 3:** commit `git commit -m "feat(projects): project list links won pipeline jobs to the unified project page"`.
|
||
|
||
## Task 7: Verify (read-only)
|
||
|
||
- [ ] `git grep -n "proj_0" -- src` → none (ids fully migrated).
|
||
- [ ] Every kanban lead kl_023–038 has a `projectId` resolving to a real project; every new project has a `sourceLeadId` resolving to a kanban lead.
|
||
- [ ] All projects (old + new) satisfy Plan-1 financial invariants (dispatch a read-only reviewer to re-check sums, as in Plan 1).
|
||
- [ ] `npm run build` clean.
|
||
- [ ] Dev run: from the kanban board, opening a Signed/In-Progress/Complete lead's "More Details" lands on `/…/projects/PRJ-2026-###` showing the full rich detail (10 tabs); opening a pre-sale lead still shows the lighter lead page. Owner, admin, and field-agent can each open a project.
|
||
|
||
---
|
||
|
||
## Self-review checklist
|
||
- [ ] No `proj_###` left anywhere in `src`.
|
||
- [ ] 16 new projects appended; ids `PRJ-2026-013..028`; each linked to its kanban lead both ways.
|
||
- [ ] Financial invariants hold for all ~28 projects.
|
||
- [ ] Build clean; won leads route to project page; pre-sale leads route to lead page; all three roles can view.
|
||
|
||
## Notes for Plan 3
|
||
After this lands, Plan 3 targets the unified model: kanban depth (realistic details on the pre-sale leads), the 10 curated threaded demo-case scenarios (chosen from the ~28 projects), and computed `selectors.js` dashboards. The lighter `LeadProjectPage` is now pre-sale-only; converging it fully into one component is deferred (Phase 4 adds the lead-side extras — stage mover, hail history, progression — onto the unified page).
|