Initial commit of Descrybe v2 without local scratch artifacts.
Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
This commit is contained in:
@@ -0,0 +1,108 @@
|
||||
# Store connectors — any store in, channel feeds out
|
||||
|
||||
Last updated: 2026-08-09
|
||||
UI hub: **`/stores`** (Stores & sources)
|
||||
|
||||
Descrybe v2 treats store platforms and supplier files as **input sources**, and Google Shopping / Meta / custom CSV/XML / REST as **outputs**. This page is the connector contract and backlog.
|
||||
|
||||
## Unified entry points
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `/stores` | Hub cards: Woo, Shopify, Feed URL, CSV upload, Export/REST |
|
||||
| `/woocommerce` | Native WooCommerce REST sync (products, orders, reviews) |
|
||||
| `/stores/shopify` | Shopify sibling guidance (feed URL / CSV today) |
|
||||
| `/feeds` | Input feed list; deep-link `?add=1&source=url\|file` |
|
||||
| `/export-feeds` | Outbound Google Shopping, Meta, custom CSV/XML public URLs |
|
||||
| `/api/v1/*` | API-key REST catalog (generic “any system” pull) |
|
||||
| `/api/public/export-feeds/{token}.{csv\|xml}` | Unauthenticated poll URL for Merchant Center / partners |
|
||||
|
||||
Primary sidebar: **Stores**, **Export** (plus Dashboard / Products / Billing). WooCommerce and input feeds are reached from the Stores hub. Reviews stay under More → Marketing. AI provider / email stay under More → Settings integrations. `/integrations` redirects to `/stores`.
|
||||
|
||||
## Inputs (sources)
|
||||
|
||||
### WooCommerce — ready (local live-proven)
|
||||
|
||||
- Config + encrypted credentials, connection test, queued product sync, orders/reviews for campaigns.
|
||||
- UI: `/woocommerce`
|
||||
- Ops: `docs/woocommerce-demo.md` (seed), **`docs/live-woo-test.md`** (`cmd/mock-woo` REST fixtures), `CREDENTIALS_ENCRYPTION_KEY`
|
||||
|
||||
### Shopify — ready (dry-run proven)
|
||||
|
||||
- Config + encrypted Admin API token, SSRF-safe shop domain, connection test, queued product push and orders pull.
|
||||
- UI: /stores/shopify (also /shopify redirect). Hub card on /stores.
|
||||
- Ops: docs/shopify-connector.md, docs/live-shopify-test.md, env SHOPIFY_*, dry-run via UI or token `dry-run`.
|
||||
- Native product reviews are not supported (no first-party Admin API).
|
||||
|
||||
### Feed URL — ready
|
||||
|
||||
- Scheduled pull of public CSV/XML into `raw_products`, then mapping + sync.
|
||||
- UI: `/feeds?add=1&source=url`
|
||||
|
||||
### CSV upload — ready
|
||||
|
||||
- One-shot file as an input feed (`source_path` in feed options).
|
||||
- UI: `/feeds?add=1&source=file`
|
||||
|
||||
## Outputs (exports)
|
||||
|
||||
### Google Shopping / Merchant Center
|
||||
|
||||
- Presets in Export Feeds UI (`google_shopping_csv`, `google_shopping_xml`) — fields align with Go `marketing.DefaultCampaignMappings()` plus `g:` XML keys for XML.
|
||||
- After create → **Refresh Feed** → copy public URL into Merchant Center → Products → Feeds → scheduled fetch.
|
||||
- Seasonal prep (Black Friday) reuses the same mapping set via Content Calendar.
|
||||
|
||||
### Meta catalog
|
||||
|
||||
- Preset `meta_csv` for Commerce Manager data sources (id, title, availability, price, image_link, …).
|
||||
|
||||
### Custom CSV / XML
|
||||
|
||||
- Arbitrary field keys + Descrybe sources; XML root/item names configurable.
|
||||
- Public URL is the integration surface for affiliates, comparison sites, and custom importers.
|
||||
|
||||
### Generic REST / webhook-style poll
|
||||
|
||||
Descrybe does **not** push arbitrary outbound webhooks yet. “Any store / any ERP” export is thin and intentional:
|
||||
|
||||
1. **Poll public feed URL** — `GET /api/public/export-feeds/{token}.csv|.xml` (no login).
|
||||
2. **Pull catalog with API key** — `Authorization: Bearer dk_…` against `/api/v1/products` (and related catalog routes). OpenAPI: `GET /api/v1/openapi.yaml`.
|
||||
|
||||
Inbound Stripe webhooks are billing-only (`/api/webhooks/stripe`), not product sync.
|
||||
|
||||
### Inbound store webhooks (Shopify / Woo) — not shipped
|
||||
|
||||
Descrybe does **not** receive Shopify or WooCommerce webhooks. Product push and orders/reviews use **queued jobs + schedule/polling** only (UI: `StoreSyncDeliveryBanner` — “Store webhooks: not available”).
|
||||
|
||||
**Do not stub** `POST /api/webhooks/shopify|woocommerce` (or any CSRF-exempt half-HMAC receive path):
|
||||
|
||||
- `/api/webhooks/*` is CSRF-exempt and unauthenticated at the edge; auth must be full HMAC (and topic routing) or the route must not exist.
|
||||
- A 501/“coming soon” after weak or missing verify trains shops to register a dead URL and looks like a live trust boundary.
|
||||
- Real receive needs per-company secrets, shop/domain routing, idempotency, topic handlers, and platform registration — ship that as one complete feature, not a placeholder.
|
||||
|
||||
Only `/api/webhooks/stripe` is mounted today (signature-verified). See `docs/security-notes.md` and `docs/production-readiness.md`.
|
||||
|
||||
## Competitor must-haves → backlog
|
||||
|
||||
Brief scan of PIM / feed managers (Koongo, WISEPIM-style): channel templates, real-time sync, pre-export validation, advanced filters, bulk edit.
|
||||
|
||||
| Gap | Priority | Notes |
|
||||
|-----|----------|--------|
|
||||
| Google Shopping + Meta templates in UI | **Shipped** | Export presets + on-page how-to |
|
||||
| Unified Stores hub / fewer nav duplicates | **Shipped** | `/stores`; Woo/Feeds off primary list |
|
||||
| Pre-export validation (missing GTIN/price/title) | Backlog | High value; reuse quality score signals |
|
||||
| Amazon channel preset | Backlog | Clone Google/Meta pattern |
|
||||
| Advanced export filters (stock, tag, collection) | Backlog | Beyond status + source feed |
|
||||
| Shopify Admin API (poll/queue sync) | **Shipped** (MVP) | Config/test/orders + product push; client-credentials OAuth checklist; App Store one-click backlog |
|
||||
| Inbound store webhooks (Shopify/Woo receive + register) | Deferred | **Do not stub**; poll/queue only until full HMAC receive ships |
|
||||
| Outbound product webhooks (push) | Backlog | Poll URL covers most partners; push only if asked |
|
||||
| Two-way inventory sync | Backlog | Woo one-way MVP today |
|
||||
|
||||
Do **not** expand into 500-channel marketplaces until core Woo + feed + Google Shopping paths are battle-tested.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/web && npm run check
|
||||
cd apps/api && go build ./...
|
||||
```
|
||||
Reference in New Issue
Block a user