99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
# 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)
|