From 1a3fed3dda201e04c96e6a67c86f92acac0907d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cau=C3=AA=20Faleiros?= Date: Mon, 3 Aug 2026 09:58:37 -0300 Subject: [PATCH] Update project context after composition import --- CONTEXT.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index d8b4f15..c54b75d 100644 --- a/CONTEXT.md +++ b/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.