158 lines
7.0 KiB
Markdown
158 lines
7.0 KiB
Markdown
|
# Getting started — operator checklist
|
||
|
|
|
||
|
|
Concise path for a local or staging operator: **login → create/map feed → process → export**.
|
||
|
|
Aligned with current web routes and API mounts (`apps/api/internal/httpapi/server.go`, `v1.go`).
|
||
|
|
|
||
|
|
**First-time machine setup** (Docker / Node / Go / migrate / ports / `/readyz`): [README.md — Local setup (any OS)](../README.md#local-setup-any-os).
|
||
|
|
|
||
|
|
| | |
|
||
|
|
|---|---|
|
||
|
|
| Web | http://localhost:28472 |
|
||
|
|
| API | http://localhost:28471 |
|
||
|
|
| Postgres | `localhost:5433` (`docker compose` → `postgres:16-alpine`) |
|
||
|
|
| Health | `GET /healthz` (liveness), `GET /readyz` (DB + worker heartbeat ≤60s) |
|
||
|
|
| OpenAPI | http://localhost:28471/api/v1/openapi.yaml · UI: `/docs` |
|
||
|
|
|
||
|
|
Credentials and counts: [demo-user.md](demo-user.md). Do not use demo accounts in production. Never commit real `.env` secrets.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 0. Bring the stack up
|
||
|
|
|
||
|
|
Canonical any-OS steps live in the README. Short path (Windows / macOS / Linux):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run setup # .env + Docker Postgres :5433 + goose migrate
|
||
|
|
npm install && npm run dev # API :28471 + web :28472 + worker
|
||
|
|
npm run seed # optional demo login
|
||
|
|
npm run health # /healthz + /readyz
|
||
|
|
```
|
||
|
|
|
||
|
|
Compose runs **Postgres only**. `npm run dev` / `npm run dev:app` include the worker (needed for process jobs and `/readyz` 200). `npm run dev:backend` is api+worker without web. `npm run dev:api` alone → `/readyz` 503.
|
||
|
|
|
||
|
|
**`/readyz` 503 without a worker is expected** (`checks.worker=missing` / `stale`, plus JSON `reason`). `/healthz` stays 200. Details: [README troubleshooting](../README.md#troubleshooting-readyz-returns-503).
|
||
|
|
|
||
|
|
**After login (company admin):** configure AI at `/integrations/ai`, marketing email at `/integrations/email`, stores at `/stores`. Do not rely on env copies or tmp placeholders for those secrets.
|
||
|
|
|
||
|
|
**Seed demo login** (after migrate; lands on **Platform Demo** — not A1):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run seed
|
||
|
|
# or: node scripts/seed-local.mjs
|
||
|
|
# or: pwsh -File .\scripts\seed-local.ps1
|
||
|
|
```
|
||
|
|
|
||
|
|
Optional password bootstrap for an existing user:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
cd apps/api
|
||
|
|
go run ./cmd/migrator -postgres $env:DATABASE_URL -set-password "you@example.com:YourPassword"
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. First login
|
||
|
|
|
||
|
|
- [ ] Open **`/login`** → sign in → land on **`/dashboard`**
|
||
|
|
- [ ] Demo (seeded): `demo@descrybe.local` / `DemoPass123!` (alias `demo@descrybe.test` also works)
|
||
|
|
- [ ] Or **`/register`** for a fresh company (empty catalog)
|
||
|
|
- [ ] Confirm company in the shell (demo default: **Platform Demo**; A1 via `a1-primary@descrybe.local`)
|
||
|
|
- [ ] Optional: start the in-app tutorial from the dashboard ([tutorial.md](tutorial.md))
|
||
|
|
|
||
|
|
Session API: `POST /api/auth/login`, `GET /api/auth/me`, `POST /api/auth/select-company`.
|
||
|
|
CSRF: browser session uses cookie + `X-CSRF-Token` (Vite proxies `/api` → API).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Create (or open) a feed
|
||
|
|
|
||
|
|
UI:
|
||
|
|
|
||
|
|
| Step | Where |
|
||
|
|
|------|--------|
|
||
|
|
| Stores hub | `/stores` (Feed URL / CSV cards) |
|
||
|
|
| Add URL feed | `/feeds?add=1&source=url` |
|
||
|
|
| Add CSV file | `/feeds?add=1&source=file` |
|
||
|
|
| List / open | `/feeds` → Map → `/feeds/{feedId}/mapping` |
|
||
|
|
| Standard fields (recommended first) | `/standard-fields` → enable recommended |
|
||
|
|
|
||
|
|
Checklist:
|
||
|
|
|
||
|
|
- [ ] Enable recommended standard fields on `/standard-fields`
|
||
|
|
- [ ] Create feed (name + public http(s) URL **or** CSV upload) — FTP/FTPS sync is **not** supported yet
|
||
|
|
- [ ] On mapping: Auto-map → Save mappings
|
||
|
|
- [ ] Sync (or **Sync + Process sample** on the mapping page)
|
||
|
|
|
||
|
|
Session API:
|
||
|
|
|
||
|
|
| Action | Method |
|
||
|
|
|--------|--------|
|
||
|
|
| Create | `POST /api/feeds` (JSON or multipart with `file`) |
|
||
|
|
| Sync | `POST /api/feeds/{id}/sync` |
|
||
|
|
| Mappings | `GET` / `PUT /api/feeds/{id}/mappings` |
|
||
|
|
| Extract schema | `POST /api/feeds/{id}/extract-schema` |
|
||
|
|
| Sync + process sample | `POST /api/feeds/{id}/sync-process-sample` |
|
||
|
|
|
||
|
|
Same shapes under **`/api/v1/...`** with `Authorization: Bearer <api_key>` (demo key in [demo-user.md](demo-user.md)).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Process products
|
||
|
|
|
||
|
|
- [ ] Keep the **worker** running (`npm run dev` includes it; or `npm run dev:worker` / `go run ./cmd/worker`). Without it, jobs stall and `/readyz` stays **503**.
|
||
|
|
- [ ] Open **`/products`** — use **Unprocessed** / raw if Processed looks empty
|
||
|
|
- [ ] Select raw products → process, **or** use mapping **Sync + Process sample**
|
||
|
|
- [ ] Watch jobs on **`/processing`**
|
||
|
|
|
||
|
|
| Surface | Endpoint |
|
||
|
|
|---------|----------|
|
||
|
|
| Dashboard | `POST /api/processing/jobs` · `GET /api/processing/jobs` · `GET /api/processing/jobs/{id}` |
|
||
|
|
| Public API (legacy clients) | `POST /api/v1/products/process` (`items[].ean` or `raw_product_ids`) → **200** `{ data: { process_id, … } }` · poll `GET /api/v1/products/process/{id}` until `COMPLETED` + `items` |
|
||
|
|
| Public API (flat jobs) | `POST /api/v1/process` → **202** flat `ProcessingJob` · `GET /api/v1/process/{id}` — **not** the same envelope as legacy |
|
||
|
|
|
||
|
|
On legacy `COMPLETED` poll `items[]`: `id` is **processed_products.id** (legacy). Also returned additively: `processed_product_id` (same as `id`) and `raw_product_id` (`raw_products.id`) so dual-mode clients can correlate with `raw_product_ids` without guessing.
|
||
|
|
|
||
|
|
Cancel / retry: `POST .../cancel` or `.../retry` on dashboard `/api/processing/jobs/{id}` or flat `/api/v1/process/{id}` paths (legacy products/process is start+status only).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Export
|
||
|
|
|
||
|
|
- [ ] Open **`/export-feeds`** → create or open a template (Google Shopping / Meta / custom CSV|XML)
|
||
|
|
- [ ] **Generate / Refresh** the feed
|
||
|
|
- [ ] Copy the public poll URL into Merchant Center / partner importer
|
||
|
|
- [ ] Optional: export selected rows from **`/products`** (export dialog)
|
||
|
|
|
||
|
|
| Surface | Endpoint |
|
||
|
|
|---------|----------|
|
||
|
|
| Create / list | `POST` / `GET /api/export-feeds` (also `/api/v1/export-feeds`) |
|
||
|
|
| Generate | `POST /api/export-feeds/{id}/generate` |
|
||
|
|
| Selected IDs | `POST /api/export-feeds/{id}/export-products` |
|
||
|
|
| Public download | `GET /api/public/export-feeds/{token}.xml` or `.csv` (no auth) |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Minimal API smoke (after seed)
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
$H = @{ Authorization = "Bearer dk_demo_local_descrybe_test_key_v1" }
|
||
|
|
Invoke-RestMethod "http://localhost:28471/api/v1/feeds?limit=5" -Headers $H
|
||
|
|
Invoke-RestMethod "http://localhost:28471/api/v1/products?limit=1" -Headers $H
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Related
|
||
|
|
|
||
|
|
| Doc | Use when |
|
||
|
|
|-----|----------|
|
||
|
|
| [README Local setup](../README.md#local-setup-any-os) | First-time Docker/Node/Go/migrate; `/readyz` 503 without worker |
|
||
|
|
| [demo-user.md](demo-user.md) | Demo email, API key, company IDs |
|
||
|
|
| [tutorial.md](tutorial.md) | In-app guided tour steps |
|
||
|
|
| [store-connectors.md](store-connectors.md) | Woo / Shopify / feed URL / CSV / export |
|
||
|
|
| [e2e-feeds-process-export.md](e2e-feeds-process-export.md) | Historical API E2E notes (prefer Platform Demo + [safe-test-fixtures.md](safe-test-fixtures.md)) |
|
||
|
|
| [process-and-sell-summary.md](process-and-sell-summary.md) | Deeper process / EPREL / sell path |
|
||
|
|
| [safe-test-fixtures.md](safe-test-fixtures.md) | Demo vs A1 isolation (canonical) |
|
||
|
|
| [qa-local-demo.md](qa-local-demo.md) | Historical Local Demo Co QA (outdated naming) |
|
||
|
|
| [ops-runtime.md](ops-runtime.md) | SMTP, sessions, encryption keys |
|