Update project context after composition import

CONTEXT.md

@@ -38,6 +38,7 @@ This project (often referred to as "Nexstar Graphs" or simply "Graphs") is a rea
 *   **Route Code Splitting:** Frontend routes are lazy-loaded with `React.lazy`/`Suspense` so the first JS payload stays smaller. Recharts-heavy page chunks are loaded on demand.
 *   **Analytics Client Cache:** Frontend analytics requests use a small shared cache/deduping layer in `src/dataService.ts`. Navigating between Dashboard, RFV, Products, and Clients should reuse fresh responses instead of refetching every route mount unless query params change or the cache expires.
 *   **Tiny as Current Source, Graphs as Future Operating Layer:** Tiny ERP is the current source for sales, product/order metadata, and stock. Graphs should increasingly become the place where the business manages production intelligence: cut configuration, SKU families, raw material relationships, consumption references, and operational charts. `NECESSIDADE DE CORTE.xlsx` is reference material only and must not become a runtime dependency.
+*   **Tiny/Olist Composition Import:** Product structures from Tiny/Olist V3 are imported into `product_compositions` and `product_composition_components`. Sellable finished-product structures are also promoted into local catalog products/materials and `consumption_references` with source `tiny_structure`, so purchase planning can use real component consumption instead of guessed kg-per-piece rules.
 
 ## 4. Directory Structure
 ```text
@@ -111,16 +112,35 @@ yield: 4.8 units/kg
 *   **Finished SKU catalog:** SKU/id, name, color, size, product family, cut family, active/inactive.
 *   **Raw material catalog:** material SKU/id, name, type (`malha`, `ribana`, `fio`, etc.), color, supplier, unit (`kg`, `metro`, `unidade`), and whether it is raw input instead of finished stock.
 *   **Consumption references:** finished SKU, material product, yield per kg, optional yield by size, optional color/family overrides, and secondary materials when needed.
+*   **Imported product compositions:** Tiny/Olist structures are stored as immutable-ish sync facts: finished SKU/Tiny ID/unit, component SKU/Tiny ID/name, quantity per finished unit, and component unit (`KG`, `UN`, etc.). These records support Product Details composition display and drive `tiny_structure` consumption references.
 *   **Cut family mapping:** rules that say which colors/sizes/products can be planned together for cutting.
 *   **Open production/cutting data:** quantities already in production, expected finish date, linked finished SKU, and linked raw material when available.
 *   **Business rules:** target coverage days, minimum stock, safety stock, purchase lead time, production lead time, and discontinued/ignored SKU rules.
 
 **Current UI/data-flow behavior:**
+*   `Cadastros` has an `Importar composições` JSON upload action for exports like `composicoes_produtos_YYYY-MM-DD.json`. The same import is available to scripts through `POST /api/production-orders/tiny-compositions/import` using `x-api-key`.
+*   Composition imports are idempotent. Re-importing the same Tiny/Olist export updates composition rows/components and refreshes derived `tiny_structure` consumption references instead of duplicating them.
+*   `Product Details > Composição` shows the synced component list for the current product when a composition exists.
 *   `Suprimentos > Necessidade de Compra` derives material pressure from demand and stock, but rows without a consumption reference are marked as missing reference instead of pretending to calculate kg.
+*   Imported `tiny_structure` consumption references now allow `Necessidade de Compra` to calculate mixed-unit material demand from real BOM lines, e.g. malha/ribana in `KG` and etiqueta/ilhós/atacador in `UN`.
 *   Missing-reference rows link into `Cadastros > Referência de Consumo` with SKU context. If the SKU does not exist in the local catalog yet, `Cadastros` opens the product form first.
+*   `Cadastros > Referência de Consumo` labels reference sources as `Manual`, `Tiny OP`, or `Tiny Estrutura`.
 *   `Plano de Corte` SKU edit actions deep-link into the cutting configuration drawer for that SKU.
 *   Product tables and group detail tables are tuned for high-volume values, including large `Total Vendido` quantities above 100k.
 
+**Current composition import status:**
+*   Local import tested with `/home/farelos/Downloads/composicoes_produtos_2026-07-31.json`.
+*   Imported successfully: `437` compositions, `1,552` component rows, and `1,316` `tiny_structure` consumption references.
+*   Known data issues from that export: `4` sellable finished products are missing SKU; `54` structures are raw material/service structures and are stored as compositions but intentionally not promoted into sellable demand-planning references; `236` component/reference lines were skipped because their parent structure was non-sellable or the finished SKU was missing.
+*   Sellable-family detection currently includes `DTF`, `CAMISETA`, `CAMISA`, `MOLETOM`, `CANGURU`, `REGATA`, and `POLO`. Raw/input/service structures are excluded from demand-reference promotion when descriptions contain terms like `MALHA`, `RIBANA`, `FIO`, `TECIDO`, `SERVIÇO`, `TINTURARIA`, `TECELAGEM`, or `FRETE`.
+
+**Recommended next steps now that composition data exists:**
+*   Make `Necessidade de Compra` clearer and more auditable: show `demanda do SKU -> consumo por unidade -> material necessário -> estoque atual -> comprar`.
+*   Add a data-health/review screen for missing finished SKU, missing component stock link, suspicious quantities, products with sales but no composition, and non-sellable structures.
+*   Connect material stock more explicitly to imported component SKUs/Tiny IDs so material purchase needs subtract the right current stock and pending receipts.
+*   Upgrade `Planejamento de Corte` to show material blockers by family/color/size, using imported composition references and current stock.
+*   Add production-plan status flow only after material needs and composition health are reliable.
+
 ## 7. CI/CD & Deployment
 *   **Gitea Actions:** A workflow located in `.gitea/workflows/deploy.yml` triggers on pushes to the `main` branch.
 *   **Docker Registry:** The pipeline builds the `frontend` and `backend` Docker images and pushes them directly to `gitea.blyzer.com.br/blyzer/`.
@@ -168,6 +188,17 @@ docker compose up -d --build
 ```
 The local Docker services use `restart: unless-stopped`, so containers should come back after laptop restart if Docker starts.
 
+**Importing Tiny/Olist Product Compositions:**
+*   From the app: open `Cadastros` and use `Importar composições` with the exported JSON file.
+*   From a script/API client:
+    ```bash
+    curl -X POST http://localhost:3004/api/production-orders/tiny-compositions/import \
+      -H 'Content-Type: application/json' \
+      -H 'x-api-key: nexstar_secret_key_123' \
+      --data-binary @/path/to/composicoes_produtos_YYYY-MM-DD.json
+    ```
+*   Expected response includes `imported`, `failed`, `componentCount`, `referenceCount`, `skippedReferenceCount`, and `issues`.
+
 ## 9. Coding Standards & AI Directives
 *   **Strict Type Safety:** Use explicit TypeScript interfaces (defined in `types.ts`). Avoid `any` where possible. Do not bypass type checks with `// @ts-ignore`.
 *   **Idiomatic React:** Use functional components and hooks (`useState`, `useEffect`, `useMemo`). Complex data transformations (like merging arrays into chart-ready datasets) MUST be wrapped in `useMemo` to prevent unnecessary re-renders.
@@ -203,6 +234,9 @@ Files most relevant to RFV:
 *   `src/displayFormatters.ts` - shared seller/fantasy/client metadata display cleanup.
 
 Recent commits related to supply/cutting/data-flow and chart readability:
+*   `37d4a77 Import Tiny product compositions` - adds the Tiny/Olist composition JSON import flow, derived `tiny_structure` consumption references, app upload button, API-key import endpoint, and import tests.
+*   `800eb97 Derive consumption references from Tiny OP sync` - Tiny OP composition sync now creates catalog products/materials and reusable consumption references from OP component lines.
+*   `c07938c Add Tiny production order detail sync` - stores OP detail rows, components, steps, and observations from Tiny/Olist sync payloads.
 *   `060b4da Connect supplies to project demand` - Suprimentos purchase needs now derive from project/order demand and stock, while missing consumption references are surfaced explicitly.
 *   `bc05fb4 Add SKU edit actions` - product/cutting/replenishment/group tables gained compact SKU view/edit actions.
 *   `63efb47 Route SKU actions to focused editors` - cut-plan edit opens SKU cutting configuration; missing-reference supply rows open the consumption reference flow.
@@ -218,3 +252,6 @@ Files most relevant to supply/cutting/data-flow:
 *   `src/analytics/cutting.ts` - cut-family parsing, cut needs, stock coverage, and product override logic.
 *   `src/pages/Products.tsx` and `src/pages/ProductGroupDetails.tsx` - product/group velocity, stock coverage, and high-volume display.
 *   `src/chartUtils.ts` - shared date bucketing, moving average, unknown-label cleanup, and chart date helpers.
+*   `backend/services/productionOrderService.js` - Tiny OP detail sync, Tiny/Olist structure import, composition storage, sellable structure filtering, and derived consumption-reference creation.
+*   `backend/routes/productionOrderRoutes.js` and `backend/routes/catalogRoutes.js` - API-key script import and authenticated app import endpoints for composition JSON.
+*   `backend/test/productCompositionService.test.js` - coverage for Tiny/Olist structure sync and bulk composition import behavior.