docs(25): capture phase context
This commit is contained in:
120
.planning/phases/25-catalog-enrichment-agent-tools/25-CONTEXT.md
Normal file
120
.planning/phases/25-catalog-enrichment-agent-tools/25-CONTEXT.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Phase 25: Catalog Enrichment & Agent Tools - Context
|
||||
|
||||
**Gathered:** 2026-04-10
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Add attribution metadata fields to global items, enforce uniqueness on (brand, model) to prevent duplicates, create a bulk import API endpoint with upsert semantics, and add MCP tools (`upsert_catalog_item`, `bulk_upsert_catalog`) for agent-powered catalog seeding. Display attribution info on catalog detail pages.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Attribution Data Model
|
||||
- **D-01:** Add three new columns to `globalItems`: `sourceUrl` (text, nullable — product page URL), `imageCredit` (text, nullable — photographer or source name), `imageSourceUrl` (text, nullable — original image URL). These align with the existing `imageSourceUrl` pattern on `items` and `threadCandidates` tables.
|
||||
- **D-02:** No separate `manufacturer` column — the existing `brand` field already serves this purpose. Requirements reference to "manufacturer" maps to `brand`.
|
||||
- **D-03:** Attribution display on catalog detail page: image credit and source link shown inline below the image, not in a collapsible section. Simple and transparent.
|
||||
|
||||
### Uniqueness Constraint
|
||||
- **D-04:** Add a unique constraint on `(brand, model)` to `globalItems`. Same physical product shouldn't exist twice regardless of category. Category is a classification, not identity.
|
||||
- **D-05:** Upsert semantics on conflict: `ON CONFLICT (brand, model) DO UPDATE` — update all non-key fields (category, weight, price, image, description, attribution fields).
|
||||
|
||||
### Bulk Import API
|
||||
- **D-06:** `POST /api/global-items/bulk` — accepts an array of items, upserts all in a single transaction. Requires API key auth (existing auth model).
|
||||
- **D-07:** All-or-nothing transaction — if any item fails validation, reject the entire batch with detailed error response listing which items failed and why.
|
||||
- **D-08:** Maximum 100 items per request. Return count of created vs updated items in the response.
|
||||
- **D-09:** Request body shape: `{ items: [{ brand, model, category?, weightGrams?, priceCents?, imageUrl?, description?, sourceUrl?, imageCredit?, imageSourceUrl?, tags?: string[] }] }`.
|
||||
|
||||
### Single Item Upsert API
|
||||
- **D-10:** `POST /api/global-items` — upsert a single catalog item with the same conflict handling as bulk. Also requires auth.
|
||||
|
||||
### MCP Tools
|
||||
- **D-11:** Add `upsert_catalog_item` MCP tool — writes directly to `globalItems` (not user-scoped). Parameters include all `globalItem` fields plus attribution fields plus optional `tags` array.
|
||||
- **D-12:** Add `bulk_upsert_catalog` MCP tool — accepts an array of items, calls the bulk import service. Same field set as single upsert.
|
||||
- **D-13:** MCP catalog tools require authenticated session (API key or OAuth bearer), same as all existing MCP tools. No special admin role.
|
||||
- **D-14:** Register new MCP tools in `src/server/mcp/index.ts` following the existing pattern (definitions array + handler registration).
|
||||
|
||||
### Claude's Discretion
|
||||
- Drizzle migration approach for new columns and unique constraint
|
||||
- Exact Zod validation schemas for bulk import payload
|
||||
- MCP tool descriptions and parameter documentation
|
||||
- Tag handling in upsert (create-if-not-exists vs require existing tags)
|
||||
- Response shape details for bulk import (created/updated counts, item IDs)
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Schema & Database
|
||||
- `src/db/schema.ts` — Current `globalItems` table definition (lines 136-146), `globalItemTags` junction (lines 158-169), and `items`/`threadCandidates` tables with existing `imageSourceUrl` column pattern
|
||||
|
||||
### Services
|
||||
- `src/server/services/global-item.service.ts` — Current read-only service (searchGlobalItems, getGlobalItemWithOwnerCount). Needs create/upsert functions.
|
||||
|
||||
### Routes
|
||||
- `src/server/routes/global-items.ts` — Current read-only routes (GET search, GET by ID). Needs POST endpoints.
|
||||
|
||||
### MCP
|
||||
- `src/server/mcp/index.ts` — MCP server setup and tool registration pattern
|
||||
- `src/server/mcp/tools/items.ts` — Example of existing tool definitions + handler pattern to follow
|
||||
- `src/server/mcp/tools/` — All existing tool files for reference on naming and structure
|
||||
|
||||
### Client
|
||||
- Catalog detail page component (wherever `globalItems/:id` route renders) — needs attribution display additions
|
||||
|
||||
### Requirements
|
||||
- `.planning/REQUIREMENTS.md` — CATL-01 through CATL-05, SEED-01 through SEED-03
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `global-item.service.ts` — existing search and getById pattern to extend with create/upsert
|
||||
- `imageSourceUrl` column pattern on `items` (line 56) and `threadCandidates` (line 98) — same pattern for globalItems attribution
|
||||
- MCP tool registration pattern — definitions array + register function per domain (see `tools/items.ts`)
|
||||
- Zod validation schemas in `src/shared/schemas.ts` — extend with globalItem create/upsert schemas
|
||||
- Tag service (`tag.service.ts`) — likely has create-if-not-exists logic for tag handling
|
||||
|
||||
### Established Patterns
|
||||
- Service DI: functions take `(db, ...)` — global item services don't need userId (catalog is shared)
|
||||
- Drizzle ORM migrations via `bun run db:generate` and `bun run db:push`
|
||||
- Hono route handlers with `@hono/zod-validator` for request validation
|
||||
- Prices as cents (integer), weights as grams (doublePrecision)
|
||||
|
||||
### Integration Points
|
||||
- `src/db/schema.ts` — add columns to globalItems, add unique constraint
|
||||
- `src/server/index.ts` — no new route group needed (global-items route already registered)
|
||||
- `src/server/mcp/index.ts` — register new catalog tool group
|
||||
- Catalog detail page — add attribution display below image
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- Manufacturer images with attribution and source link — honor takedown requests (from PROJECT.md decisions)
|
||||
- Agent seeding uses manufacturer-provided images — no scraping (from Out of Scope in REQUIREMENTS.md)
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- SEED-04 (actual seeding run with 100+ items) — tracked in future requirements, not part of this phase's infrastructure work
|
||||
- Admin role for catalog management — current auth model sufficient for v2.1
|
||||
- Catalog item edit UI — this phase focuses on API/MCP tools, not a web editor
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 25-catalog-enrichment-agent-tools*
|
||||
*Context gathered: 2026-04-10*
|
||||
@@ -0,0 +1,98 @@
|
||||
# Phase 25: Catalog Enrichment & Agent Tools - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-04-10
|
||||
**Phase:** 25-catalog-enrichment-agent-tools
|
||||
**Areas discussed:** Attribution data model, Uniqueness constraint design, Bulk import API design, MCP tool scope
|
||||
**Mode:** --batch --auto (all decisions auto-selected)
|
||||
|
||||
---
|
||||
|
||||
## Attribution Data Model
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| manufacturer is alias for brand | No new column — existing `brand` field serves as manufacturer | ✓ |
|
||||
| Separate manufacturer column | Add `manufacturer` alongside `brand` for cases where they differ | |
|
||||
|
||||
**User's choice:** [auto] manufacturer is alias for brand (recommended default)
|
||||
**Notes:** The `brand` field already captures manufacturer identity. Adding a separate column would create confusion about which to use. Three new columns added: `sourceUrl`, `imageCredit`, `imageSourceUrl`.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Inline below image | Show attribution directly below the product image | ✓ |
|
||||
| Collapsible section | Hide attribution in an expandable panel | |
|
||||
| Footer area | Show attribution at bottom of detail page | |
|
||||
|
||||
**User's choice:** [auto] Inline below image (recommended default)
|
||||
**Notes:** Transparency is a project value — attribution should be visible, not hidden.
|
||||
|
||||
---
|
||||
|
||||
## Uniqueness Constraint Design
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Unique on (brand, model) only | Category is classification, not identity | ✓ |
|
||||
| Unique on (brand, model, category) | Allow same product in different categories | |
|
||||
|
||||
**User's choice:** [auto] Unique on (brand, model) only (recommended default)
|
||||
**Notes:** A physical product is one thing regardless of how it's categorized. Prevents duplicates when agents might categorize differently.
|
||||
|
||||
---
|
||||
|
||||
## Bulk Import API Design
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| API key auth (existing) | Same auth as other write endpoints | ✓ |
|
||||
| Special admin token | Separate credential for bulk operations | |
|
||||
|
||||
**User's choice:** [auto] API key auth (recommended default)
|
||||
**Notes:** No admin role system exists. API key is sufficient for single-admin setup.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| All-or-nothing transaction | Reject entire batch on any validation failure | ✓ |
|
||||
| Partial success | Import valid items, skip invalid ones | |
|
||||
|
||||
**User's choice:** [auto] All-or-nothing transaction (recommended default)
|
||||
**Notes:** Upsert handles conflicts. Validation failures are data quality issues — better to fix and retry than have partial imports.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| 100 items per request | Reasonable batch for agents | ✓ |
|
||||
| 50 items per request | Conservative limit | |
|
||||
| 500 items per request | Large batch for bulk seeding | |
|
||||
|
||||
**User's choice:** [auto] 100 items per request (recommended default)
|
||||
|
||||
---
|
||||
|
||||
## MCP Tool Scope
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Standard auth (API key/OAuth) | Same as existing MCP tools | ✓ |
|
||||
| Unauthenticated catalog writes | Allow any MCP client to write catalog | |
|
||||
|
||||
**User's choice:** [auto] Standard auth (recommended default)
|
||||
**Notes:** Catalog tools follow the same auth pattern as all other MCP tools.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Drizzle migration approach for new columns and unique constraint
|
||||
- Zod validation schemas for bulk import payload
|
||||
- MCP tool descriptions and parameter documentation
|
||||
- Tag handling in upsert (create-if-not-exists vs require existing)
|
||||
- Response shape for bulk import
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- SEED-04: actual seeding run (future requirement)
|
||||
- Admin role for catalog management
|
||||
- Catalog item edit UI (web editor)
|
||||
Reference in New Issue
Block a user