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.
2026-08-09 22:47:43 +02:00
commit 8580c996c3
1285 changed files with 325780 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Public API and Postman A1
+
+Base URL (local): http://127.0.0.1:28471  
+Auth: Authorization Bearer api_key or X-API-Key  
+OpenAPI: GET /api/v1/openapi.yaml (no key). Health: GET /api/v1/health or GET /healthz.
+
+## Core /api/v1 groups (API key)
+
+| Group | Examples |
+|-------|----------|
+| Products | GET /products, GET /products/{id}, PATCH /products/{id}, POST /products/process, GET /products/process/{id} |
+| Feeds | GET/POST /feeds, POST /feeds/{id}/sync, mappings, extract-schema |
+| Categories / attributes | CRUD under /categories, /attributes |
+| Export | /export-feeds plus generate / export-products |
+| Process jobs | POST /process, list/get/cancel/retry |
+| Marketing calendar | /marketing/calendar (legacy /campaigns aliases) |
+
+Mounted in apps/api/internal/httpapi/v1.go via mountV1.
+
+## A1 two-EAN Postman flow
+
+Collection: docs/postman/Descrybe-v2-A1-two-EANs.postman_collection.json  
+Prerequisite: npm run seed:a1 (restores processing jobs so poll works).
+
+```mermaid
+sequenceDiagram
+  participant P as Postman
+  participant API as /api/v1
+  participant W as worker
+  P->>API: GET /health
+  P->>API: GET /feeds
+  P->>API: GET /products?feed_id=
+  P->>API: POST /products/process (2 EANs)
+  API-->>P: data.process_id
+  loop until done
+    P->>API: GET /products/process/{processId}
+  end
+  Note over W: Worker claims processing_jobs
+  P->>API: GET /products?search=EAN
+  P->>API: GET /export-feeds
+  P->>API: GET /api/public/export-feeds/{token}.csv
+```
+
+### Steps (collection order)
+
+0. Health (no auth)  
+1. List feeds (find Elkotex)  
+2. List products on feed  
+3. **Process two EANs** — processing_type full — copy data.process_id into processId  
+4. Poll process status  
+5–6. Search results by EAN  
+7. Get product by UUID  
+8. List export feeds  
+9. Public CSV (no API key)
+
+Demo API key and feed/EAN vars live in the Postman collection (local demo only). Full surface: docs/postman/Descrybe-v2-Demo-A1-all-v1.postman_collection.json.
+
+Rate limits: process/sync/export POSTs are capped per company (RateLimitV1Process). Prefer enqueue + worker under load.