docs(03-agent-portal-shell): create phase 3 plan — 4 plans in 4 waves
This commit is contained in:
Chandler Copeland
274
.planning/phases/03-agent-portal-shell/03-04-PLAN.md
Normal file
274
.planning/phases/03-agent-portal-shell/03-04-PLAN.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
phase: 03-agent-portal-shell
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on: [03-03]
|
||||
files_modified:
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx
|
||||
- teressa-copeland-homes/src/app/portal/_components/ConfirmDialog.tsx
|
||||
autonomous: false
|
||||
requirements: [CLIENT-03]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Agent clicks a client card and lands on /portal/clients/{id} — sees the client's name, email, and an Edit button"
|
||||
- "Agent clicks Edit on the client profile — a modal opens pre-filled with the client's current name and email"
|
||||
- "Agent submits the edit modal — the profile page updates with the new values"
|
||||
- "Agent clicks Delete Client — a confirmation dialog appears; confirming deletes the client and redirects to /portal/clients"
|
||||
- "Documents section on the profile page shows the same table style as the dashboard (status badge, date sent)"
|
||||
- "Agent can verify the full portal flow end-to-end in the browser: login → dashboard → clients → profile → edit → delete"
|
||||
artifacts:
|
||||
- path: "teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx"
|
||||
provides: "Client profile page: client header + edit/delete actions + documents table"
|
||||
- path: "teressa-copeland-homes/src/app/portal/_components/ConfirmDialog.tsx"
|
||||
provides: "Reusable confirmation dialog for destructive actions"
|
||||
key_links:
|
||||
- from: "clients/[id]/page.tsx"
|
||||
to: "updateClient (bound with id)"
|
||||
via: "ClientModal with mode='edit' + clientId prop"
|
||||
pattern: "ClientModal.*mode.*edit"
|
||||
- from: "ConfirmDialog confirm button"
|
||||
to: "deleteClient server action"
|
||||
via: "form action calling deleteClient(id) then redirect to /portal/clients"
|
||||
pattern: "deleteClient"
|
||||
- from: "clients/[id]/page.tsx"
|
||||
to: "DocumentsTable"
|
||||
via: "documents query filtered by clientId"
|
||||
pattern: "DocumentsTable.*showClientColumn.*false"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the client profile page with edit and delete capabilities, then run a human verification checkpoint covering the complete Phase 3 portal flow.
|
||||
|
||||
Purpose: CLIENT-03 requires the agent to view a client's profile and associated documents. Edit + delete round out the client management feature set. The checkpoint verifies all 4 Phase 3 success criteria in a real browser.
|
||||
Output: Working /portal/clients/[id] page with edit modal, delete confirmation, and documents table; human approval of complete Phase 3 portal.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/Users/ccopeland/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/03-agent-portal-shell/03-CONTEXT.md
|
||||
@.planning/phases/03-agent-portal-shell/03-03-SUMMARY.md
|
||||
|
||||
<interfaces>
|
||||
<!-- From Plans 02 and 03 — use these exactly -->
|
||||
|
||||
From src/app/portal/_components/DocumentsTable.tsx:
|
||||
```typescript
|
||||
type DocumentRow = {
|
||||
id: string;
|
||||
name: string;
|
||||
clientName: string | null;
|
||||
status: "Draft" | "Sent" | "Viewed" | "Signed";
|
||||
sentAt: Date | null;
|
||||
clientId: string;
|
||||
};
|
||||
export function DocumentsTable({ rows, showClientColumn }: Props): JSX.Element
|
||||
// Pass showClientColumn={false} on the profile page — client is implied
|
||||
```
|
||||
|
||||
From src/app/portal/_components/ClientModal.tsx:
|
||||
```typescript
|
||||
// Already supports edit mode:
|
||||
type Props = {
|
||||
isOpen: boolean;
|
||||
onClose: () => void;
|
||||
mode?: "create" | "edit";
|
||||
clientId?: string;
|
||||
defaultName?: string;
|
||||
defaultEmail?: string;
|
||||
};
|
||||
export function ClientModal(props: Props): JSX.Element | null
|
||||
```
|
||||
|
||||
From src/lib/actions/clients.ts:
|
||||
```typescript
|
||||
// updateClient uses bind pattern — in profile page:
|
||||
// const boundUpdate = updateClient.bind(null, client.id);
|
||||
export async function updateClient(
|
||||
id: string,
|
||||
_prevState: { error?: string } | null,
|
||||
formData: FormData
|
||||
): Promise<{ error?: string; success?: boolean }>
|
||||
|
||||
export async function deleteClient(id: string): Promise<{ error?: string; success?: boolean }>
|
||||
```
|
||||
|
||||
Next.js 16 dynamic params (MUST await):
|
||||
```typescript
|
||||
export default async function ClientProfilePage({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ id: string }>;
|
||||
}) {
|
||||
const { id } = await params; // CRITICAL — sync access throws at build time
|
||||
}
|
||||
```
|
||||
|
||||
Drizzle query for client profile:
|
||||
```typescript
|
||||
import { eq, desc, sql } from "drizzle-orm";
|
||||
|
||||
// Fetch client
|
||||
const [client] = await db.select().from(clients).where(eq(clients.id, id));
|
||||
if (!client) notFound(); // import from next/navigation
|
||||
|
||||
// Fetch documents for this client
|
||||
const docs = await db
|
||||
.select({
|
||||
id: documents.id,
|
||||
name: documents.name,
|
||||
status: documents.status,
|
||||
sentAt: documents.sentAt,
|
||||
clientId: documents.clientId,
|
||||
clientName: sql<string>`${clients.name}`,
|
||||
})
|
||||
.from(documents)
|
||||
.leftJoin(clients, eq(documents.clientId, clients.id))
|
||||
.where(eq(documents.clientId, id))
|
||||
.orderBy(desc(documents.createdAt));
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Client profile page with edit/delete and documents table</name>
|
||||
<files>
|
||||
teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx
|
||||
teressa-copeland-homes/src/app/portal/_components/ConfirmDialog.tsx
|
||||
</files>
|
||||
<action>
|
||||
**`src/app/portal/_components/ConfirmDialog.tsx`** ("use client"):
|
||||
Props: `{ isOpen: boolean; title: string; message: string; onConfirm: () => void; onCancel: () => void; confirmLabel?: string }`
|
||||
|
||||
- Overlay + centered dialog box (same overlay pattern as ClientModal: `fixed inset-0 z-50 bg-black/40`)
|
||||
- Title, message text, Cancel button + Confirm button
|
||||
- Confirm button: red/destructive styling (`bg-red-600 text-white hover:bg-red-700`)
|
||||
- `confirmLabel` defaults to "Delete"
|
||||
|
||||
**`src/app/portal/(protected)/clients/[id]/page.tsx`**:
|
||||
|
||||
This page needs both server data AND client modal/dialog state. Use the same pattern as clients/page.tsx: server component fetches data, renders a "use client" inner component with the interactive parts.
|
||||
|
||||
Server component (`default export`):
|
||||
1. `const { id } = await params` — CRITICAL: params is a Promise in Next.js 16
|
||||
2. Fetch client by id (use `notFound()` if not found)
|
||||
3. Fetch documents for this client with LEFT JOIN
|
||||
4. Render `<ClientProfileClient client={client} docs={docs} />`
|
||||
|
||||
Inline "use client" component (`ClientProfileClient`) in the same file OR in `_components/ClientProfileClient.tsx`:
|
||||
Props: `{ client: { id: string; name: string; email: string }; docs: DocumentRow[] }`
|
||||
|
||||
State: `const [isEditOpen, setIsEditOpen] = useState(false)` and `const [isDeleteOpen, setIsDeleteOpen] = useState(false)`
|
||||
|
||||
Layout (two-section layout per CONTEXT.md decision):
|
||||
- **Header section**: white card (`bg-white rounded-xl shadow-sm p-6 mb-6`)
|
||||
- Back link: arrow + "Back to Clients" as a Next.js `<Link href="/portal/clients">` with `text-[var(--gold)] text-sm`
|
||||
- Client name as `<h1>` (`text-[var(--navy)] text-2xl font-semibold`)
|
||||
- Email below the name (gray text)
|
||||
- Two buttons on the right: "Edit" button (opens edit modal) + "Delete Client" button (opens confirm dialog)
|
||||
- Edit button: outlined style (`border border-[var(--navy)] text-[var(--navy)] px-4 py-2 rounded-lg text-sm`)
|
||||
- Delete button: red outlined style (`border border-red-300 text-red-600 px-4 py-2 rounded-lg text-sm`)
|
||||
- **Documents section**: white card (`bg-white rounded-xl shadow-sm p-6`)
|
||||
- `<h2>Documents</h2>` heading
|
||||
- If `docs.length === 0`: "No documents yet." gray text
|
||||
- If `docs.length > 0`: `<DocumentsTable rows={docs} showClientColumn={false} />`
|
||||
|
||||
**Edit modal**: `<ClientModal isOpen={isEditOpen} onClose={() => setIsEditOpen(false)} mode="edit" clientId={client.id} defaultName={client.name} defaultEmail={client.email} />`
|
||||
|
||||
**Delete flow**:
|
||||
- `<ConfirmDialog isOpen={isDeleteOpen} title="Delete client?" message={"Delete " + client.name + "? This will also delete all associated documents. This cannot be undone."} onConfirm={handleDelete} onCancel={() => setIsDeleteOpen(false)} />`
|
||||
- `handleDelete`: call `await deleteClient(client.id)` then `router.push("/portal/clients")` — import `useRouter` from `next/navigation`
|
||||
|
||||
PITFALL: `deleteClient` is a server action. To call it from a client component, import it and call it directly in an async event handler (Next.js 15+ allows this). The action runs server-side; the client awaits the promise.
|
||||
|
||||
PITFALL: `await params` before any usage of `id` — synchronous access causes build failure in Next.js 16.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx tsc --noEmit 2>&1</automated>
|
||||
</verify>
|
||||
<done>Client profile page renders with client details header, edit/delete buttons, and documents table. ConfirmDialog component exported. TypeScript compiles cleanly.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 2: Full Phase 3 portal verification in browser</name>
|
||||
<action>Start the dev server and walk through the complete portal verification checklist below.</action>
|
||||
<files>none</files>
|
||||
<verify>Human approval of all 5 checklist sections below.</verify>
|
||||
<done>Agent approves all 5 portal sections: authentication, dashboard, clients list, client profile, navigation.</done>
|
||||
<what-built>
|
||||
Complete Phase 3 Agent Portal Shell:
|
||||
- /portal/dashboard — documents table with status filter dropdown; 4 seeded placeholder documents visible
|
||||
- /portal/clients — card grid with 2 seeded clients; "+ Add Client" button opens modal
|
||||
- /portal/clients/[id] — client profile with edit button (opens pre-filled modal), delete button (confirmation dialog), documents table for that client
|
||||
- Top nav on all portal pages with Dashboard and Clients links + sign-out button
|
||||
- Middleware protects all /portal/* routes
|
||||
</what-built>
|
||||
<how-to-verify>
|
||||
Start the dev server: `cd teressa-copeland-homes && npm run dev`
|
||||
|
||||
**1. Authentication and routing (Phase 1 preserved)**
|
||||
- Visit http://localhost:3000/portal/dashboard while logged out → should redirect to /agent/login
|
||||
- Log in with the seeded agent account → should land on /portal/dashboard (not /agent/dashboard)
|
||||
|
||||
**2. Dashboard (DASH-01 + DASH-02)**
|
||||
- Verify you see a table with 4 documents: "Purchase Agreement - 842 Maple Dr", "Seller Disclosure - 842 Maple Dr", "Buyer Rep Agreement", "Purchase Agreement - 1205 Oak Ave"
|
||||
- Verify status badges: two "Signed" (green), one "Sent" (blue), one "Draft" (gray)
|
||||
- Verify Client column shows "Sarah Johnson" and "Mike Torres"
|
||||
- Select "Signed" in the filter dropdown → URL changes to ?status=Signed → table shows only 2 rows
|
||||
- Select "All statuses" → table returns to 4 rows
|
||||
|
||||
**3. Clients list (CLIENT-01 + CLIENT-02)**
|
||||
- Visit http://localhost:3000/portal/clients
|
||||
- Verify card grid shows 2 client cards: Sarah Johnson and Mike Torres
|
||||
- Each card shows name, email, document count, and last activity date
|
||||
- Click "+ Add Client" → modal opens with name + email fields
|
||||
- Fill in a test client (e.g., "Test User" + "test@example.com") → click "Add Client" → modal closes → new card appears in grid
|
||||
|
||||
**4. Client profile (CLIENT-03)**
|
||||
- Click on "Sarah Johnson" card → lands on /portal/clients/[sarah's id]
|
||||
- Verify header shows "Sarah Johnson", her email, Edit and Delete Client buttons
|
||||
- Verify documents section shows Sarah's 2 documents with status badges
|
||||
- Click "Edit" → modal opens pre-filled with "Sarah Johnson" and her email → change name → save → header updates
|
||||
- Click "Delete Client" → confirmation dialog appears → click Cancel → client is NOT deleted
|
||||
- (Optional) Delete the test client you created in step 3 → confirm → redirected to /portal/clients
|
||||
|
||||
**5. Navigation**
|
||||
- Verify top nav is visible on all three portal pages
|
||||
- Click "Dashboard" nav link → navigates to /portal/dashboard
|
||||
- Click "Clients" nav link → navigates to /portal/clients
|
||||
- Current page should be highlighted in nav (gold underline or similar)
|
||||
- Sign out → redirects to /agent/login
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" if all checklist items pass. Describe any issues found and I will fix them before you approve.</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
1. `npx tsc --noEmit` produces zero TypeScript errors
|
||||
2. Client profile page uses `await params` (not synchronous params.id)
|
||||
3. ConfirmDialog shows title, message, Cancel + Delete buttons
|
||||
4. Edit modal opens pre-filled with client's current name and email
|
||||
5. Human verifier approves all 5 portal sections in the browser
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Agent can see client profile with name, email, and associated documents (CLIENT-03)
|
||||
- Agent can edit client name/email via modal — profile updates immediately
|
||||
- Agent can delete a client via confirmation dialog — redirected to clients list after
|
||||
- All four Phase 3 success criteria confirmed in real browser by agent
|
||||
- TypeScript compiles cleanly with zero errors
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/03-agent-portal-shell/03-04-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user