From 2cb6ccc94784d4f22331e6c99e034cf8221c71bf Mon Sep 17 00:00:00 2001 From: Ben Stull Date: Thu, 11 Jun 2026 08:29:04 -0700 Subject: [PATCH] =?UTF-8?q?spec(SD-0002=20=C2=A71):=20business=20context?= =?UTF-8?q?=20=E2=80=94=20products=20bulk=20CSV=20import/export=20(#13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- ...SD-0002-products-bulk-csv-import-export.md | 277 ++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 specs/SD-0002-products-bulk-csv-import-export.md diff --git a/specs/SD-0002-products-bulk-csv-import-export.md b/specs/SD-0002-products-bulk-csv-import-export.md new file mode 100644 index 0000000..81122ca --- /dev/null +++ b/specs/SD-0002-products-bulk-csv-import-export.md @@ -0,0 +1,277 @@ +# Solution Design: Products — bulk CSV import/export + +| | | +| --- | --- | +| **Anchor** | [wiggleverse/wiggleverse-ecomm#13](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/13) (`type/feature`, `priority/P1`) — parent epic [#12](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/12) | +| **Author(s)** | Claude (session ecomm-0030), for Ben Stull | +| **Reviewers / approvers** | Ben Stull | +| **Status** | `draft` | +| **Version** | v0.1.0 | +| **Source artifacts** | BDD corpus: [prototype rfcs 11-05-\* (products import/export)](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/rfcs) · [research/shopify/products](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify/products/products.md) · Prototype: [wiggleverse-ecomm-prototype](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype) · Reference: Shopify product CSV · Builds on: [SD-0001](./SD-0001-mvp-sign-up-and-single-storefront.md) · Supersedes: — | + +**Change log** + +| Date | Version | Change | By | +| --- | --- | --- | --- | +| 2026-06-11 | v0.1.0 | Initial draft — §1 Business Context (session ecomm-0030) | Claude + Ben | + +--- + +## 1. Business Context + +*The business lens — solution-agnostic throughout. No mechanism is proposed until §2.* + +### 1.1 Executive Summary + +A merchant's catalog already exists before they ever meet this platform — in +spreadsheets, in their current platform's export, in the working files they +price and re-price every season. The value at stake is letting that catalog +*become* their storefront without re-entering it, letting catalog-wide changes +(a season's prices, a supplier's new costs) land as one gesture instead of +hundreds, and guaranteeing the catalog can leave whole at any time — so +adopting the platform never means retyping a business in, and never means +locking a business up. The beneficiaries are merchants — most acutely those +migrating from another platform — and the platform itself: every downstream +capability of an ecomm (browsing, orders, checkout) presupposes a real catalog +existing, and today none can. + +### 1.2 Background + +ecomm is Wiggleverse's multi-tenant Shopify alternative. Its first Solution +Design ([SD-0001](./SD-0001-mvp-sign-up-and-single-storefront.md)) shipped +sign-up, identity, and single-storefront creation: a merchant can exist and +their storefront can exist — and that storefront is, by design, an honestly +empty shell ("There's nothing to manage yet"). + +The Products MVP epic ([#12](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/12)) +is the next move: give the storefront a real product catalog. The epic makes a +deliberate boundary decision: the MVP ships **no per-item editing** — bulk +ingestion and extraction is the *only* way product data moves. Its sibling +Features display the catalog +([#14](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/14), +list + read-only detail) and extend it to bundled offerings +([#15](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/15), +kits); **this** Feature is the mechanism they all feed from. + +The backdrop that makes bulk-first the right boundary: real merchant catalogs +are not built one item at a time inside an admin tool. Merchants switching +platforms hold their entire catalog as an export of their current system — +hundreds of products, each with variations, images, and prices. Merchants who +stay maintain their catalogs batch-wise: a seasonal price list, a supplier's +updated cost sheet, a spreadsheet kept as the working source of truth. The +catalog's natural lifecycle is bulk in, bulk update, bulk out. + +### 1.3 Business Actors / Roles + +Real-world roles — they exist whether or not this platform does. + +| Role | Responsible for (in the business) | +| --- | --- | +| **Merchant** | Owns a storefront's catalog: what is sold, at what price, shown how. Keeps it current as seasons, suppliers, and stock change. | +| **Migrating merchant** | A merchant switching platforms. Their catalog already lives, complete, in their current system and its export files; they decide whether switching is worth the cost. | +| **Platform builder** | Builds and validates the capabilities a catalog feeds (browsing, orders, demos). Needs realistic catalogs to exist before those capabilities can be exercised. | + +### 1.4 Problem Statement + +A storefront can exist but cannot hold anything sellable: there is no way to +get product data into the platform at all, and the MVP deliberately offers no +per-item editing to fall back on. For the merchant whose catalog already +exists elsewhere — the common case — hand re-entry of hundreds of products, +each with variations, imagery, and prices, is a switching cost that simply +ends the conversation. The gap recurs after adoption: catalog maintenance is +batch-shaped (whole-catalog price changes, supplier updates), and one-at-a-time +upkeep mismatches how merchants actually work their data. And data that goes +in must come out: a catalog that cannot be extracted whole makes the platform +a trap, which careful merchants correctly treat as a reason not to enter. + +### 1.5 Pain Points + +| # | Pain | Who feels it | Cost / frequency today | +| --- | --- | --- | --- | +| PP-1 | A created storefront is a dead end — nothing to sell, nothing to manage, nothing to show | Merchant | Total: blocks any real use of the platform; felt by every merchant immediately after sign-up | +| PP-2 | An existing catalog would have to be re-keyed item by item to move over | Migrating merchant | Hundreds of products × dozens of fields each — a prohibitive switching cost; prospective merchants don't switch | +| PP-3 | Catalog-wide changes (season prices, supplier costs) have no whole-catalog gesture | Merchant | Recurring — every season, supplier change, or repricing event; effort scales with catalog size | +| PP-4 | No realistic catalog can be stood up to build, demo, or validate against | Platform builder | Continuous — every product-dependent capability (#14, #15, future orders) is blocked or faked | +| PP-5 | Whatever goes in cannot be gotten back out — the catalog would be trapped | Merchant | Felt at the adoption decision (a reason to say no) and at every backup/audit/leave moment after | + +### 1.6 Targeted Business Outcomes + +| # | Outcome | Success metric | Baseline → Target | Guardrail (must not regress) | How / when measured | +| --- | --- | --- | --- | --- | --- | +| BO-1 | Merchants with existing catalogs adopt — populating a storefront is hours, not weeks | # storefronts holding a real catalog; effort to first full catalog | 0 storefronts can hold a catalog → a several-hundred-product catalog lands in under an hour of merchant effort | Sign-up → storefront flow (SD-0001) stays intact | Platform records (operationalized §8.1); reviewed monthly | +| BO-2 | Catalog upkeep happens *in* the platform — merchants refresh in bulk rather than letting data go stale or leaving | # storefronts performing repeat bulk updates | No upkeep possible → catalog-holding storefronts update in bulk as their prices/data change | Existing catalog data never corrupted by an update | Platform records; reviewed monthly | +| BO-3 | "My data would be trapped" is a non-objection — the catalog is extractable whole, always | Full-catalog extraction available and exercised | No extraction exists → every storefront's complete catalog can be taken out on demand, at any time | Extraction completeness: nothing the merchant supplied is unrecoverable | Platform records; reviewed quarterly | +| BO-4 | Product-dependent work is unblocked — sibling and downstream capabilities build against real catalogs | #14 / #15 / future order work proceeding against realistic data | Nothing to build against → realistic catalogs standable in minutes | — | Delivery record of #14/#15; per Feature | + +### 1.7 Scope (business) + +- **In scope:** populating a storefront's catalog in bulk from records the + merchant already holds; updating the catalog in bulk; extracting the + complete catalog at any time. "Catalog" here means products in full + commercial reality: variations (size/color and the like), imagery, + organization (vendor, type, tags, category), pricing/cost, stock levels, + and publication state. +- **Out of scope:** per-item create/edit (a later epic — the MVP's deliberate + boundary); removing products in bulk (nothing is deleted by this mechanism — + see §2); automated or scheduled synchronization with other platforms; + movement of non-catalog data (customers, orders — other epics); the meaning + and behavior of bundled offerings (kits — Feature #15, which rides this + mechanism but defines its own semantics). +- **Non-goals:** real-time integration with other commerce systems (the + supplied file is the boundary, deliberately); making the MVP a catalog + *editing* tool of any kind. + +### 1.8 Assumptions · Constraints · Dependencies + +- **Assumptions:** merchants hold, or can readily produce, their catalog as a + structured file (a spreadsheet, their current platform's export). *Risk if + wrong:* a merchant with no digital catalog at all has no entry path in this + MVP. Catalogs at MVP scale run to a few thousand items. *Risk if wrong:* + larger catalogs need heavier machinery (a named seam, §2). +- **Constraints:** bulk-only is Epic #12's deliberate MVP boundary — this + design must not quietly grow per-item editing. One storefront per account + (SD-0001 INV-4) — a merchant's catalog context is unambiguous. +- **Dependencies:** SD-0001's shipped surfaces (identity, storefront, admin + shell) — live as of v0.4.0. Sibling #14 displays what this ingests; sibling + #15 extends what the records can express — both sequence after this + mechanism exists. + +### 1.9 Business Use Cases + +**BUC-1 — As a migrating merchant, I can bring my existing catalog into my storefront in one bulk gesture, so that switching platforms doesn't mean re-keying my business.** + +```gherkin +Scenario: BUC-1 — An existing catalog comes over whole + Given a merchant whose catalog of several hundred products lives in an + export from their current platform + When they supply that catalog to their storefront in one gesture + Then the storefront holds the full catalog — every product with its + variations, imagery, organization, and prices + And nothing had to be re-entered by hand +``` + +- **BUC-1 acceptance criteria:** the catalog the storefront holds matches the + records the merchant supplied, completely; the merchant's effort is one + supply-and-review gesture, not per-product work. + +**BUC-1a — unhappy path: unusable records are reported, not silently dropped.** + +```gherkin +Scenario: BUC-1a — Unusable records come back with actionable feedback + Given a merchant supplies catalog records of which some are incomplete, + contradictory, or unreadable + When the storefront cannot accept some of the records + Then the merchant is told exactly which records failed and why, in terms + they can act on + And they can correct and re-supply the problem records + And nothing is silently dropped, guessed at, or invented +``` + +- **BUC-1a acceptance criteria:** every rejected record is identified with an + actionable reason; accepted vs. rejected is fully accounted for — the + merchant is never left wondering what made it in. + +**BUC-2 — As a merchant, I can see exactly what a bulk change will do to my catalog before it happens, so that I never damage my own data by accident.** + +```gherkin +Scenario: BUC-2 — A bulk change is reviewed before it takes effect + Given a merchant about to apply a bulk change to a catalog their business + depends on + When they supply the new records + Then they see what will be added, what will change (and to what), and what + is in error — before anything takes effect + And the change happens only when they say so +``` + +- **BUC-2 acceptance criteria:** the preview is complete and faithful (what it + shows is exactly what applying does); declining costs nothing; nothing + changes without the merchant's explicit go-ahead. *(OHM: consent & agency — + the merchant authorizes the change knowing what it is.)* + +**BUC-3 — As a merchant, I can update my whole catalog at once, so that batch-shaped changes (seasonal prices, supplier costs) cost one gesture instead of hundreds.** + +```gherkin +Scenario: BUC-3 — A catalog-wide change lands as one gesture + Given a storefront holding a catalog, and a season's repricing touching + most of it + When the merchant supplies the updated records + Then the affected products are updated to the new values + And the unaffected products are untouched + And no duplicates are created +``` + +- **BUC-3 acceptance criteria:** updates land on the products they target; + re-supplying unchanged records changes nothing (supplying the same catalog + twice never doubles it); the merchant's effort does not scale with catalog + size. + +**BUC-4 — As a merchant, I can take my complete catalog out at any time, so that my business data is never trapped in the platform.** + +```gherkin +Scenario: BUC-4 — The catalog leaves whole, on demand + Given a storefront holding a catalog the merchant built up over time + When the merchant asks for their catalog + Then they receive the complete catalog — every product, variation, image, + and price — in a form they can use elsewhere + And what they receive could rebuild the same catalog faithfully +``` + +- **BUC-4 acceptance criteria:** extraction is always available, complete + (nothing the merchant supplied is unrecoverable), and round-trips — what + comes out can go back in and reproduce the same catalog. *(OHM: agency — + leaving is always possible; the platform earns retention, never extorts + it.)* + +--- + +## 2. Solution Proposal + +*(not yet authored — next in the section-at-a-time loop)* + +## 3. Product Personas + +*(not yet authored)* + +## 4. Product Use Cases + +*(not yet authored)* + +## 5. UX Layout + +*(not yet authored)* + +## 6. Technical Design + +*(not yet authored)* + +## 7. Delivery Plan + +*(not yet authored)* + +## 8. Success Metrics & Measurement + +*(not yet authored)* + +## 9. Telemetry, Observability & Monitoring + +*(not yet authored)* + +## 10. Operations + +*(not yet authored)* + +## 11. Documentation plan + +*(not yet authored)* + +## 12. Traceability matrix + +*(not yet authored)* + +## 13. Open Questions & Decisions log + +*(not yet authored)* + +## 14. Glossary & References + +*(not yet authored)*