docs(02): create phase plan for planning threads
This commit is contained in:
263
.planning/phases/02-planning-threads/02-01-PLAN.md
Normal file
263
.planning/phases/02-planning-threads/02-01-PLAN.md
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
phase: 02-planning-threads
|
||||
plan: 01
|
||||
type: tdd
|
||||
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/server/index.ts
|
||||
- tests/helpers/db.ts
|
||||
- tests/services/thread.service.test.ts
|
||||
- tests/routes/threads.test.ts
|
||||
autonomous: true
|
||||
requirements: [THRD-01, THRD-02, THRD-03, THRD-04]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "POST /api/threads creates a thread and returns it with 201"
|
||||
- "GET /api/threads returns active threads with candidate count and price range"
|
||||
- "POST /api/threads/:id/candidates adds a candidate to a thread"
|
||||
- "PUT/DELETE /api/threads/:threadId/candidates/:id updates/removes candidates"
|
||||
- "POST /api/threads/:id/resolve atomically creates a collection item from candidate data and archives the thread"
|
||||
- "GET /api/threads?includeResolved=true includes archived threads"
|
||||
- "Resolved thread no longer appears in default active thread list"
|
||||
artifacts:
|
||||
- path: "src/db/schema.ts"
|
||||
provides: "threads and threadCandidates table definitions"
|
||||
contains: "threads"
|
||||
- path: "src/shared/schemas.ts"
|
||||
provides: "Zod schemas for thread and candidate validation"
|
||||
contains: "createThreadSchema"
|
||||
- path: "src/shared/types.ts"
|
||||
provides: "TypeScript types for threads and candidates"
|
||||
contains: "Thread"
|
||||
- path: "src/server/services/thread.service.ts"
|
||||
provides: "Thread and candidate business logic with resolution transaction"
|
||||
exports: ["getAllThreads", "getThreadWithCandidates", "createThread", "resolveThread"]
|
||||
- path: "src/server/routes/threads.ts"
|
||||
provides: "Hono API routes for threads and candidates"
|
||||
exports: ["threadRoutes"]
|
||||
- path: "tests/services/thread.service.test.ts"
|
||||
provides: "Unit tests for thread service"
|
||||
min_lines: 80
|
||||
- path: "tests/routes/threads.test.ts"
|
||||
provides: "Integration tests for thread API"
|
||||
min_lines: 60
|
||||
key_links:
|
||||
- from: "src/server/routes/threads.ts"
|
||||
to: "src/server/services/thread.service.ts"
|
||||
via: "service function calls"
|
||||
pattern: "import.*thread\\.service"
|
||||
- from: "src/server/services/thread.service.ts"
|
||||
to: "src/db/schema.ts"
|
||||
via: "Drizzle queries on threads/threadCandidates tables"
|
||||
pattern: "from.*schema"
|
||||
- from: "src/server/services/thread.service.ts"
|
||||
to: "src/server/services/item.service.ts"
|
||||
via: "resolveThread uses items table to create collection item"
|
||||
pattern: "items"
|
||||
- from: "src/server/index.ts"
|
||||
to: "src/server/routes/threads.ts"
|
||||
via: "app.route mount"
|
||||
pattern: "threadRoutes"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the complete backend API for planning threads: database schema, shared validation schemas, service layer with thread resolution transaction, and Hono API routes. All via TDD.
|
||||
|
||||
Purpose: Establish the data model and API that the frontend (Plan 02) will consume. Thread resolution -- the atomic operation that creates a collection item from a candidate and archives the thread -- is the core business logic of this phase.
|
||||
|
||||
Output: Working API endpoints for thread CRUD, candidate CRUD, and thread resolution, with comprehensive tests.
|
||||
</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/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/02-planning-threads/02-RESEARCH.md
|
||||
|
||||
<interfaces>
|
||||
<!-- Existing code the executor needs to understand -->
|
||||
|
||||
From src/db/schema.ts (existing tables to extend):
|
||||
```typescript
|
||||
export const categories = sqliteTable("categories", {
|
||||
id: integer("id").primaryKey({ autoIncrement: true }),
|
||||
name: text("name").notNull().unique(),
|
||||
emoji: text("emoji").notNull().default("\u{1F4E6}"),
|
||||
createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
|
||||
});
|
||||
|
||||
export const items = sqliteTable("items", {
|
||||
id: integer("id").primaryKey({ autoIncrement: true }),
|
||||
name: text("name").notNull(),
|
||||
weightGrams: real("weight_grams"),
|
||||
priceCents: integer("price_cents"),
|
||||
categoryId: integer("category_id").notNull().references(() => categories.id),
|
||||
notes: text("notes"),
|
||||
productUrl: text("product_url"),
|
||||
imageFilename: text("image_filename"),
|
||||
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 (existing pattern to follow):
|
||||
```typescript
|
||||
export const createItemSchema = z.object({
|
||||
name: z.string().min(1, "Name is required"),
|
||||
weightGrams: z.number().nonnegative().optional(),
|
||||
priceCents: z.number().int().nonnegative().optional(),
|
||||
categoryId: z.number().int().positive(),
|
||||
notes: z.string().optional(),
|
||||
productUrl: z.string().url().optional().or(z.literal("")),
|
||||
});
|
||||
```
|
||||
|
||||
From src/server/services/item.service.ts (DI pattern):
|
||||
```typescript
|
||||
type Db = typeof prodDb;
|
||||
export function createItem(db: Db = prodDb, data: ...) { ... }
|
||||
```
|
||||
|
||||
From src/server/index.ts (route mounting):
|
||||
```typescript
|
||||
app.route("/api/items", itemRoutes);
|
||||
```
|
||||
|
||||
From tests/helpers/db.ts (test DB pattern):
|
||||
```typescript
|
||||
export function createTestDb() {
|
||||
const sqlite = new Database(":memory:");
|
||||
sqlite.run("PRAGMA foreign_keys = ON");
|
||||
// CREATE TABLE statements...
|
||||
const db = drizzle(sqlite, { schema });
|
||||
db.insert(schema.categories).values({ name: "Uncategorized", emoji: "\u{1F4E6}" }).run();
|
||||
return db;
|
||||
}
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Schema, shared schemas, test helper, and service layer with TDD</name>
|
||||
<files>src/db/schema.ts, src/shared/schemas.ts, src/shared/types.ts, tests/helpers/db.ts, src/server/services/thread.service.ts, tests/services/thread.service.test.ts</files>
|
||||
<behavior>
|
||||
- createThread: creates thread with name, returns thread with id/status/timestamps
|
||||
- getAllThreads: returns active threads with candidateCount, minPriceCents, maxPriceCents; excludes resolved by default; includes resolved when includeResolved=true
|
||||
- getThreadWithCandidates: returns thread with nested candidates array including category info; returns null for non-existent thread
|
||||
- createCandidate: adds candidate to thread with all item-compatible fields (name, weightGrams, priceCents, categoryId, notes, productUrl, imageFilename)
|
||||
- updateCandidate: updates candidate fields, returns updated candidate; returns null for non-existent
|
||||
- deleteCandidate: removes candidate, returns deleted candidate; returns null for non-existent
|
||||
- updateThread: updates thread name
|
||||
- deleteThread: removes thread and cascading candidates
|
||||
- resolveThread: atomically creates collection item from candidate data and sets thread status to "resolved" with resolvedCandidateId; fails if thread not active; fails if candidate not in thread; fails if candidate not found
|
||||
</behavior>
|
||||
<action>
|
||||
**RED phase first:**
|
||||
|
||||
1. Add `threads` and `threadCandidates` tables to `src/db/schema.ts` following the existing pattern. Schema per RESEARCH.md Pattern 1: threads has id, name, status (default "active"), resolvedCandidateId, createdAt, updatedAt. threadCandidates has id, threadId (FK to threads with cascade delete), and the same fields as items (name, weightGrams, priceCents, categoryId FK to categories, notes, productUrl, imageFilename, createdAt, updatedAt).
|
||||
|
||||
2. Add Zod schemas to `src/shared/schemas.ts`: createThreadSchema (name required), updateThreadSchema (name optional), createCandidateSchema (same shape as createItemSchema), updateCandidateSchema (partial of create), resolveThreadSchema (candidateId required).
|
||||
|
||||
3. Add types to `src/shared/types.ts`: Thread (inferred from Drizzle threads table), ThreadCandidate (inferred from Drizzle threadCandidates table), CreateThread, UpdateThread, CreateCandidate, UpdateCandidate, ResolveThread (from Zod schemas).
|
||||
|
||||
4. Update `tests/helpers/db.ts`: Add CREATE TABLE statements for `threads` and `thread_candidates` matching the Drizzle schema (use same pattern as existing items/categories tables).
|
||||
|
||||
5. Write `tests/services/thread.service.test.ts` with failing tests covering all behaviors listed above. Follow the pattern from `tests/services/item.service.test.ts`. Each test uses `createTestDb()` for isolation.
|
||||
|
||||
**GREEN phase:**
|
||||
|
||||
6. Implement `src/server/services/thread.service.ts` following the DI pattern from item.service.ts (db as first param with prodDb default). Functions: getAllThreads (with subquery aggregates for candidateCount and price range), getThreadWithCandidates (with candidate+category join), createThread, updateThread, deleteThread (with image cleanup collection), createCandidate, updateCandidate, deleteCandidate, resolveThread (transactional: validate thread is active + candidate belongs to thread, insert into items from candidate data, update thread status to "resolved" and set resolvedCandidateId). On resolution, if candidate's categoryId no longer exists, fall back to categoryId=1 (Uncategorized). On resolution, if candidate has imageFilename, copy the file to a new filename so the item has an independent image copy.
|
||||
|
||||
All tests must pass after implementation.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun test tests/services/thread.service.test.ts --bail</automated>
|
||||
</verify>
|
||||
<done>All thread service unit tests pass. Schema, shared schemas, types, and test helper updated. Service layer implements full thread + candidate CRUD and transactional resolution.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Thread API routes with integration tests</name>
|
||||
<files>src/server/routes/threads.ts, src/server/index.ts, tests/routes/threads.test.ts</files>
|
||||
<behavior>
|
||||
- POST /api/threads with valid body returns 201 + thread object
|
||||
- POST /api/threads with empty name returns 400
|
||||
- GET /api/threads returns array of active threads with metadata
|
||||
- GET /api/threads?includeResolved=true includes archived threads
|
||||
- GET /api/threads/:id returns thread with candidates
|
||||
- GET /api/threads/:id for non-existent returns 404
|
||||
- PUT /api/threads/:id updates thread name
|
||||
- DELETE /api/threads/:id removes thread
|
||||
- POST /api/threads/:id/candidates adds candidate, returns 201
|
||||
- PUT /api/threads/:threadId/candidates/:candidateId updates candidate
|
||||
- DELETE /api/threads/:threadId/candidates/:candidateId removes candidate
|
||||
- POST /api/threads/:id/resolve with valid candidateId returns 200 + created item
|
||||
- POST /api/threads/:id/resolve on already-resolved thread returns 400
|
||||
- POST /api/threads/:id/resolve with wrong candidateId returns 400
|
||||
</behavior>
|
||||
<action>
|
||||
**RED phase first:**
|
||||
|
||||
1. Write `tests/routes/threads.test.ts` following the pattern from `tests/routes/items.test.ts`. Use `createTestDb()`, inject test DB via Hono context middleware (`c.set("db", testDb)`), and use `app.request()` for integration tests. Cover all behaviors above.
|
||||
|
||||
**GREEN phase:**
|
||||
|
||||
2. Create `src/server/routes/threads.ts` as a Hono app. Follow the exact pattern from `src/server/routes/items.ts`:
|
||||
- Use `zValidator("json", schema)` for request body validation
|
||||
- Get DB from `c.get("db") ?? prodDb` for testability
|
||||
- Thread CRUD: GET / (with optional ?includeResolved query param), POST /, GET /:id, PUT /:id, DELETE /:id
|
||||
- Candidate CRUD nested under thread: POST /:id/candidates (with image upload support via formData, same pattern as items), PUT /:threadId/candidates/:candidateId, DELETE /:threadId/candidates/:candidateId (with image file cleanup)
|
||||
- Resolution: POST /:id/resolve with resolveThreadSchema validation
|
||||
- Return appropriate status codes (201 for creation, 200 for success, 400 for validation/business errors, 404 for not found)
|
||||
|
||||
3. Mount routes in `src/server/index.ts`: `app.route("/api/threads", threadRoutes)` alongside existing routes.
|
||||
|
||||
For candidate image upload: follow the same pattern as the items image upload route. Candidates need a POST endpoint that accepts multipart form data with an optional image file. Use the same file validation (type/size) and storage pattern.
|
||||
|
||||
All integration tests must pass.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/jean-luc-makiola/Development/projects/GearBox && bun test tests/routes/threads.test.ts --bail</automated>
|
||||
</verify>
|
||||
<done>All thread API integration tests pass. Routes mounted in server index. Full thread and candidate CRUD available via REST API. Resolution endpoint creates collection item and archives thread.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
```bash
|
||||
# All tests pass (Phase 1 + Phase 2)
|
||||
cd /home/jean-luc-makiola/Development/projects/GearBox && bun test --bail
|
||||
|
||||
# Thread API responds
|
||||
curl -s http://localhost:3000/api/threads | head -1
|
||||
```
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All thread service unit tests pass
|
||||
- All thread API integration tests pass
|
||||
- All existing Phase 1 tests still pass (no regressions)
|
||||
- POST /api/threads creates a thread
|
||||
- POST /api/threads/:id/candidates adds a candidate
|
||||
- POST /api/threads/:id/resolve creates a collection item and archives the thread
|
||||
- Thread resolution is transactional (atomic create item + archive thread)
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/02-planning-threads/02-01-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user