makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(04): create phase plan

Browse Source
This commit is contained in:
Jean-Luc Makiola
2026-03-15 16:27:47 +01:00
parent 80496b7f50
commit 92afac3eb7
3 changed files with 444 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.planning/ROADMAP.md
View File

@@ -34,10 +34,11 @@
1. Running database schema push creates the threads table (and any other missing tables) without errors 1. Running database schema push creates the threads table (and any other missing tables) without errors
2. User can create a new planning thread from the planning tab and it appears in the thread list 2. User can create a new planning thread from the planning tab and it appears in the thread list
3. User sees a clear, polished empty state with a call-to-action when no planning threads exist 3. User sees a clear, polished empty state with a call-to-action when no planning threads exist
**Plans**: TBD **Plans**: 2 plans
Plans: Plans:
- [ ] 04-01: TBD - [ ] 04-01-PLAN.md — Database schema fix and backend thread API with categoryId
- [ ] 04-02-PLAN.md — Frontend planning tab overhaul (modal, empty state, pill tabs, category filter)
### Phase 5: Image Handling ### Phase 5: Image Handling
**Goal**: Users can see and manage gear images throughout the app **Goal**: Users can see and manage gear images throughout the app
@@ -76,6 +77,6 @@ Phases execute in numeric order: 4 -> 5 -> 6
| 1. Foundation and Collection | v1.0 | 4/4 | Complete | 2026-03-14 | | 1. Foundation and Collection | v1.0 | 4/4 | Complete | 2026-03-14 |
| 2. Planning Threads | v1.0 | 3/3 | Complete | 2026-03-15 | | 2. Planning Threads | v1.0 | 3/3 | Complete | 2026-03-15 |
| 3. Setups and Dashboard | v1.0 | 3/3 | Complete | 2026-03-15 | | 3. Setups and Dashboard | v1.0 | 3/3 | Complete | 2026-03-15 |
| 4. Database & Planning Fixes | v1.1 | 0/? | Not started | - | | 4. Database & Planning Fixes | v1.1 | 0/2 | Not started | - |
| 5. Image Handling | v1.1 | 0/? | Not started | - | | 5. Image Handling | v1.1 | 0/? | Not started | - |
| 6. Category Icons | v1.1 | 0/? | Not started | - | | 6. Category Icons | v1.1 | 0/? | Not started | - |

203
.planning/phases/04-database-planning-fixes/04-01-PLAN.md Normal file
View File

@@ -0,0 +1,203 @@
---
phase: 04-database-planning-fixes
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/db/schema.ts
- src/shared/schemas.ts
- src/shared/types.ts
- src/server/services/thread.service.ts
- src/server/routes/threads.ts
- src/client/hooks/useThreads.ts
- tests/helpers/db.ts
autonomous: true
requirements: [DB-01, PLAN-01]
must_haves:
truths:
- "Database schema push creates threads and thread_candidates tables without errors"
- "Threads table includes category_id column with foreign key to categories"
- "Creating a thread with name and categoryId succeeds via API"
- "getAllThreads returns categoryName and categoryEmoji for each thread"
artifacts:
- path: "src/db/schema.ts"
provides: "threads table with categoryId column"
contains: "categoryId.*references.*categories"
- path: "src/shared/schemas.ts"
provides: "createThreadSchema with categoryId field"
contains: "categoryId.*z.number"
- path: "src/server/services/thread.service.ts"
provides: "Thread CRUD with category join"
exports: ["createThread", "getAllThreads"]
- path: "tests/helpers/db.ts"
provides: "Test DB with category_id on threads"
contains: "category_id.*REFERENCES categories"
key_links:
- from: "src/server/routes/threads.ts"
to: "src/server/services/thread.service.ts"
via: "createThread(db, data) with categoryId"
pattern: "createThread.*data"
- from: "src/server/services/thread.service.ts"
to: "src/db/schema.ts"
via: "Drizzle insert/select on threads with categoryId"
pattern: "threads.*categoryId"
---
<objective>
Fix the missing threads table in the database and add categoryId to threads so thread creation works end-to-end.
Purpose: DB-01 (threads table exists) and the backend half of PLAN-01 (thread creation works with category). Without this, the planning tab crashes on any thread operation.
Output: Working database schema, updated API that accepts categoryId on thread creation, and thread list returns category info.
</objective>
<execution_context>
@/home/jean-luc-makiola/.claude/get-shit-done/workflows/execute-plan.md
@/home/jean-luc-makiola/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/ROADMAP.md
@.planning/phases/04-database-planning-fixes/04-CONTEXT.md
<interfaces>
<!-- Key types and contracts the executor needs -->
From src/db/schema.ts (threads table -- needs categoryId added):
```typescript
export const threads = sqliteTable("threads", {
id: integer("id").primaryKey({ autoIncrement: true }),
name: text("name").notNull(),
status: text("status").notNull().default("active"),
resolvedCandidateId: integer("resolved_candidate_id"),
// MISSING: categoryId column
createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
});
```
From src/shared/schemas.ts (createThreadSchema -- needs categoryId):
```typescript
export const createThreadSchema = z.object({
name: z.string().min(1, "Thread name is required"),
// MISSING: categoryId
});
```
From src/client/hooks/useThreads.ts (ThreadListItem -- needs category fields):
```typescript
interface ThreadListItem {
id: number;
name: string;
status: "active" | "resolved";
resolvedCandidateId: number | null;
createdAt: string;
updatedAt: string;
candidateCount: number;
minPriceCents: number | null;
maxPriceCents: number | null;
// MISSING: categoryId, categoryName, categoryEmoji
}
```
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Add categoryId to threads schema, Zod schemas, types, and test helper</name>
<files>src/db/schema.ts, src/shared/schemas.ts, src/shared/types.ts, tests/helpers/db.ts</files>
<action>
1. In `src/db/schema.ts`, add `categoryId` column to the `threads` table:
```
categoryId: integer("category_id").notNull().references(() => categories.id),
```
Place it after the `resolvedCandidateId` field.
2. In `src/shared/schemas.ts`, update `createThreadSchema` to require categoryId:
```
export const createThreadSchema = z.object({
name: z.string().min(1, "Thread name is required"),
categoryId: z.number().int().positive(),
});
```
Also update `updateThreadSchema` to allow optional categoryId:
```
export const updateThreadSchema = z.object({
name: z.string().min(1).optional(),
categoryId: z.number().int().positive().optional(),
});
```
3. In `tests/helpers/db.ts`, update the threads CREATE TABLE to include `category_id`:
```sql
CREATE TABLE threads (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'active',
resolved_candidate_id INTEGER,
category_id INTEGER NOT NULL REFERENCES categories(id),
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
updated_at INTEGER NOT NULL DEFAULT (unixepoch())
)
```
4. Run `bun run db:generate` to generate the migration for adding category_id to threads.
5. Run `bun run db:push` to apply the migration.
</action>
<verify>
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun run db:push 2>&1 | tail -5</automated>
</verify>
<done>threads table in schema.ts has categoryId with FK to categories, createThreadSchema requires categoryId, test helper CREATE TABLE matches, db:push succeeds</done>
</task>
<task type="auto">
<name>Task 2: Update thread service and routes to handle categoryId, update hook types</name>
<files>src/server/services/thread.service.ts, src/server/routes/threads.ts, src/client/hooks/useThreads.ts</files>
<action>
1. In `src/server/services/thread.service.ts`:
- Update `createThread` to insert `categoryId` from data:
`.values({ name: data.name, categoryId: data.categoryId })`
- Update `getAllThreads` to join with categories table and return `categoryId`, `categoryName`, `categoryEmoji` in the select:
```
categoryId: threads.categoryId,
categoryName: categories.name,
categoryEmoji: categories.emoji,
```
Add `.innerJoin(categories, eq(threads.categoryId, categories.id))` to the query.
- Update `updateThread` data type to include optional `categoryId: number`.
2. In `src/server/routes/threads.ts`:
- The route handlers already pass `data` through from Zod validation, so createThread and updateThread should work with the updated schemas. Verify the PUT handler passes categoryId if present.
3. In `src/client/hooks/useThreads.ts`:
- Add `categoryId: number`, `categoryName: string`, `categoryEmoji: string` to the `ThreadListItem` interface.
- Update `useCreateThread` mutationFn type to `{ name: string; categoryId: number }`.
4. Run existing tests to confirm nothing breaks.
</action>
<verify>
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun test 2>&1 | tail -20</automated>
</verify>
<done>Thread creation accepts categoryId, getAllThreads returns category name and emoji for each thread, existing tests pass, useCreateThread hook sends categoryId</done>
</task>
</tasks>
<verification>
- `bun run db:push` completes without errors
- `bun test` passes all existing tests
- Start dev server (`bun run dev:server`) and confirm `curl http://localhost:3000/api/threads` returns 200 (empty array is fine)
</verification>
<success_criteria>
- threads table exists in database with category_id column
- POST /api/threads requires { name, categoryId } and creates a thread
- GET /api/threads returns threads with categoryName and categoryEmoji
- All existing tests pass
</success_criteria>
<output>
After completion, create `.planning/phases/04-database-planning-fixes/04-01-SUMMARY.md`
</output>

237
.planning/phases/04-database-planning-fixes/04-02-PLAN.md Normal file
View File

@@ -0,0 +1,237 @@
---
phase: 04-database-planning-fixes
plan: 02
type: execute
wave: 2
depends_on: [04-01]
files_modified:
- src/client/stores/uiStore.ts
- src/client/components/CreateThreadModal.tsx
- src/client/components/ThreadCard.tsx
- src/client/routes/collection/index.tsx
autonomous: false
requirements: [PLAN-01, PLAN-02]
must_haves:
truths:
- "User can create a thread via a modal dialog with name and category fields"
- "User sees an inviting empty state explaining the 3-step planning workflow when no threads exist"
- "User can switch between Active and Resolved threads using pill tabs"
- "Thread cards display category icon and name"
artifacts:
- path: "src/client/components/CreateThreadModal.tsx"
provides: "Modal dialog for thread creation with name + category picker"
min_lines: 60
- path: "src/client/routes/collection/index.tsx"
provides: "PlanningView with empty state, pill tabs, category filter, modal trigger"
contains: "CreateThreadModal"
- path: "src/client/components/ThreadCard.tsx"
provides: "Thread card with category display"
contains: "categoryEmoji"
key_links:
- from: "src/client/components/CreateThreadModal.tsx"
to: "src/client/hooks/useThreads.ts"
via: "useCreateThread mutation with { name, categoryId }"
pattern: "useCreateThread"
- from: "src/client/routes/collection/index.tsx"
to: "src/client/components/CreateThreadModal.tsx"
via: "createThreadModalOpen state from uiStore"
pattern: "CreateThreadModal"
- from: "src/client/components/ThreadCard.tsx"
to: "ThreadListItem"
via: "categoryName and categoryEmoji props"
pattern: "categoryEmoji|categoryName"
---
<objective>
Build the frontend for thread creation modal, polished empty state, Active/Resolved pill tabs, category filter, and category display on thread cards.
Purpose: PLAN-01 (user can create threads without errors via modal) and PLAN-02 (polished empty state with CTA). This completes the planning tab UX overhaul.
Output: Working planning tab with modal-based thread creation, educational empty state, pill tab filtering, and category-aware thread cards.
</objective>
<execution_context>
@/home/jean-luc-makiola/.claude/get-shit-done/workflows/execute-plan.md
@/home/jean-luc-makiola/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/ROADMAP.md
@.planning/phases/04-database-planning-fixes/04-CONTEXT.md
@.planning/phases/04-database-planning-fixes/04-01-SUMMARY.md
<interfaces>
<!-- From Plan 01: updated types the executor will consume -->
From src/client/hooks/useThreads.ts (after Plan 01):
```typescript
interface ThreadListItem {
id: number;
name: string;
status: "active" | "resolved";
resolvedCandidateId: number | null;
createdAt: string;
updatedAt: string;
candidateCount: number;
minPriceCents: number | null;
maxPriceCents: number | null;
categoryId: number;
categoryName: string;
categoryEmoji: string;
}
// useCreateThread expects { name: string; categoryId: number }
```
From src/client/hooks/useCategories.ts:
```typescript
export function useCategories(): UseQueryResult<Category[]>;
// Category = { id: number; name: string; emoji: string; createdAt: Date }
```
From src/client/stores/uiStore.ts (needs createThreadModal state added):
```typescript
// Existing pattern for dialogs:
// resolveThreadId: number | null;
// openResolveDialog: (threadId, candidateId) => void;
// closeResolveDialog: () => void;
```
From src/client/routes/collection/index.tsx (CollectionView empty state pattern):
```typescript
// Lines 58-93: empty state with emoji, heading, description, CTA button
// Follow this pattern for planning empty state
```
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Create thread modal and update uiStore</name>
<files>src/client/stores/uiStore.ts, src/client/components/CreateThreadModal.tsx</files>
<action>
1. In `src/client/stores/uiStore.ts`, add create-thread modal state following the existing dialog pattern:
```
createThreadModalOpen: boolean;
openCreateThreadModal: () => void;
closeCreateThreadModal: () => void;
```
Initialize `createThreadModalOpen: false` and wire up the actions.
2. Create `src/client/components/CreateThreadModal.tsx`:
- A modal overlay (fixed inset-0, bg-black/50 backdrop, centered white panel) following the same pattern as the app's existing dialog styling.
- Form fields: Thread name (text input, required, min 1 char) and Category (select dropdown populated from `useCategories()` hook).
- Category select shows emoji + name for each option. Pre-select the first category.
- Submit calls `useCreateThread().mutate({ name, categoryId })`.
- On success: close modal (via `closeCreateThreadModal` from uiStore), reset form.
- On error: show inline error message.
- Cancel button and clicking backdrop closes modal.
- Disable submit button while `isPending`.
- Use Tailwind classes consistent with existing app styling (rounded-xl, text-sm, blue-600 primary buttons, gray-200 borders).
</action>
<verify>
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun run lint 2>&1 | tail -5</automated>
</verify>
<done>CreateThreadModal component renders a modal with name input and category dropdown, submits via useCreateThread, uiStore has createThreadModalOpen state</done>
</task>
<task type="auto">
<name>Task 2: Overhaul PlanningView with empty state, pill tabs, category filter, and thread card category display</name>
<files>src/client/routes/collection/index.tsx, src/client/components/ThreadCard.tsx</files>
<action>
1. In `src/client/components/ThreadCard.tsx`:
- Add `categoryName: string` and `categoryEmoji: string` props to `ThreadCardProps`.
- Display category as a pill badge (emoji + name) in the card's badge row, using a style like `bg-blue-50 text-blue-700` to distinguish from existing badges.
2. In `src/client/routes/collection/index.tsx`, rewrite the `PlanningView` function:
**Remove:** The inline text input + button form for thread creation. Remove the `showResolved` checkbox.
**Add state:**
- `activeTab: "active" | "resolved"` (default "active") for the pill tab selector.
- `categoryFilter: number | null` (default null = all categories) for filtering.
- Import `useCategories` hook, `useUIStore`, and `CreateThreadModal`.
**Layout (top to bottom):**
a. **Header row:** "Planning Threads" heading on the left, "New Thread" button on the right. Button calls `openCreateThreadModal()` from uiStore. Use a plus icon (inline SVG, same pattern as collection empty state button).
b. **Filter row:** Active/Resolved pill tab selector on the left, category filter dropdown on the right.
- Pill tabs: Two buttons styled as a segment control. Active pill gets `bg-blue-600 text-white`, inactive gets `bg-gray-100 text-gray-600 hover:bg-gray-200`. Rounded-full, px-4 py-1.5, text-sm font-medium. Wrap in a `flex bg-gray-100 rounded-full p-0.5 gap-0.5` container.
- Category filter: A `<select>` dropdown with "All categories" as default option, then each category with emoji + name. Filter threads client-side by matching `thread.categoryId === categoryFilter`.
c. **Thread list or empty state:**
- Pass `activeTab === "resolved"` as `includeResolved` to `useThreads`. When `activeTab === "active"`, show only active threads. When `activeTab === "resolved"`, filter the results to show only resolved threads (since `includeResolved=true` returns both).
- Apply `categoryFilter` on the client side if set.
d. **Empty state (when filtered threads array is empty AND activeTab is "active" AND no category filter):**
- Guided + educational tone per user decision.
- Max-width container (max-w-lg mx-auto), centered, py-16.
- Heading: "Plan your next purchase" (text-xl font-semibold).
- Three illustrated steps showing the workflow, each as a row with a step number circle (1, 2, 3), a short title, and a description:
1. "Create a thread" -- "Start a research thread for gear you're considering"
2. "Add candidates" -- "Add products you're comparing with prices and weights"
3. "Pick a winner" -- "Resolve the thread and the winner joins your collection"
- Style each step: flex row, step number in a 8x8 rounded-full bg-blue-100 text-blue-700 font-bold circle, title in font-medium, description in text-sm text-gray-500.
- CTA button below steps: "Create your first thread" -- calls `openCreateThreadModal()`. Blue-600 bg, white text, same style as collection empty state button.
- If empty because of active filter (category or "resolved" tab), show a simpler "No threads found" message instead of the full educational empty state.
e. **Render `<CreateThreadModal />` at the bottom** of PlanningView (it reads its own open/close state from uiStore).
f. **Thread grid:** Keep existing `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4`. Pass `categoryName` and `categoryEmoji` as new props to ThreadCard.
</action>
<verify>
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun run lint 2>&1 | tail -5</automated>
</verify>
<done>PlanningView shows educational empty state with 3-step workflow, pill tabs for Active/Resolved, category filter dropdown, "New Thread" button opens modal, ThreadCard shows category badge, inline form is removed</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<files>src/client/routes/collection/index.tsx</files>
<name>Task 3: Verify planning tab overhaul</name>
<what-built>Complete planning tab overhaul: thread creation modal, educational empty state, Active/Resolved pill tabs, category filter, and category display on thread cards.</what-built>
<how-to-verify>
1. Start both dev servers: `bun run dev:server` and `bun run dev:client`
2. Visit http://localhost:5173/collection?tab=planning
3. Verify the educational empty state appears with 3 illustrated steps and a "Create your first thread" CTA button
4. Click "Create your first thread" -- a modal should open with name input and category dropdown
5. Create a thread (enter a name, select a category, submit)
6. Verify the thread appears as a card with category emoji + name badge
7. Verify the "New Thread" button appears in the header area
8. Create a second thread in a different category
9. Test the category filter dropdown -- filtering should show only matching threads
10. Test the Active/Resolved pill tabs -- should toggle between active and resolved views
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
<action>Human verifies the planning tab UI overhaul by testing the complete flow in browser.</action>
<verify>
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun run lint 2>&1 | tail -5</automated>
</verify>
<done>User confirms: empty state shows 3-step workflow, modal creates threads with category, pill tabs filter Active/Resolved, category filter works, thread cards show category</done>
</task>
</tasks>
<verification>
- `bun run lint` passes with no errors
- Planning tab shows educational empty state when no threads exist
- Thread creation modal opens from both empty state CTA and header button
- Creating a thread with name + category succeeds and thread appears in list
- Thread cards show category emoji and name
- Active/Resolved pill tabs filter correctly
- Category filter narrows the thread list
</verification>
<success_criteria>
- Inline thread creation form is replaced with modal dialog
- Empty state educates users about the 3-step planning workflow
- Active/Resolved pill tabs replace the "Show archived" checkbox
- Category filter allows narrowing thread list by category
- Thread cards display category information
- No lint errors
</success_criteria>
<output>
After completion, create `.planning/phases/04-database-planning-fixes/04-02-SUMMARY.md`
</output>