From 5e81a8f2c3c119f6a378f32db6c649fa8455a19c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cau=C3=AA=20Faleiros?= Date: Wed, 15 Jul 2026 10:01:54 -0300 Subject: [PATCH] Update project data flow context --- CONTEXT.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 5 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index fb84093..d8b4f15 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -37,6 +37,7 @@ This project (often referred to as "Nexstar Graphs" or simply "Graphs") is a rea * **Backend Analytics Foundation:** Raw `/api/data` still exists for legacy pages, but dashboard/product/client aggregate endpoints now exist under `/api/analytics/*`. Dashboard already uses the backend dashboard aggregation endpoint so it does not wait on the full raw order download. * **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. ## 4. Directory Structure ```text @@ -83,15 +84,50 @@ This project (often referred to as "Nexstar Graphs" or simply "Graphs") is a rea * **RFV Display Rule:** The RFV table's `Última Compra` date is the purchase date inside the selected period. Date-only strings must be parsed as local dates in the frontend to avoid UTC shifting (`2026-06-15` must render as `15/06/2026`, not `14/06/2026`). The small recency text below it displays `Hoje`, `Ontem`, or `X dias` relative to the selected range end. * **Client Page Filters:** The main Clients page has one filter button plus client search. The filter panel contains date shortcuts/custom dates, sorting, marketplace, sales channel, seller, and client type. Marketplace/channel/seller options come from distinct non-empty order metadata across all orders so options remain visible regardless of the current date window. * **Seller Metadata Display:** Seller labels are cleaned for UI display. All-caps seller names are title-cased, trailing Tiny IDs like `#977226210` are stripped from labels, and leading fantasy-name prefixes like `[3]` are removed for display. IDs may still be used internally as stable filter values. -* **Seller Dashboard Charts:** The main Dashboard includes seller performance charts above the existing charts, using backend aggregates for revenue and order count by seller. +* **Seller Dashboard Charts:** The main Dashboard includes seller performance charts above the existing charts, using backend aggregates for revenue and order count by seller. Long date ranges are bucketed into week/month views for readability. Seller labels like `0`/empty values are displayed as `Sem vendedor`. The seller moving-average line is optional behind the `Tendência` toggle because it can be confused with another seller series. +* **Product Chart Readability:** Product detail charts use automatic date bucketing, cleaner x-axis labels, clickable point drill-downs, and a moving average on the single-product view. Product detail KPIs include daily average sold and estimated stock coverage based on the selected date range. -## 6. CI/CD & Deployment +## 6. Supply, Cutting, and Data Flow Requirements +Tiny provides sales and stock facts, but it does not fully describe how a finished SKU consumes raw material. For Suprimentos and Corte to work reliably, Graphs needs internal domain data that complements Tiny. + +**Current operating assumption:** +* Tiny sends orders, product IDs/names, seller/order metadata, and current stock. +* Graphs derives demand, sales velocity, replenishment pressure, and cut/material needs from Tiny data plus local configuration. +* Excel files are examples of current manual management only. They should guide UX/data modeling but not be imported as the long-term source of truth. + +**Core missing relationship:** +```text +Finished SKU -> raw material -> consumption/yield +``` + +Example: +```text +BASE LISA CAMISETA PRETA G +uses: MALHA 100% ALGODAO PRETA +yield: 4.8 units/kg +``` + +**Data Graphs must own or enrich locally:** +* **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. +* **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:** +* `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. +* 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. +* `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. + +## 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/`. * **Production Deployment:** Updates are deployed manually via Portainer by pulling the `latest` image tags from the Gitea registry and redeploying the stack. * **Environment Variables:** Security secrets (`API_KEY`, `JWT_SECRET`, `POSTGRES_PASSWORD`, `N8N_WHATSAPP_TRIGGER_URL`) are injected via the Portainer stack configuration and passed into containers via `docker-compose.yml`. -## 7. Environment Setup & Scripts +## 8. Environment Setup & Scripts **Running Locally:** 1. Start the database: @@ -132,7 +168,7 @@ docker compose up -d --build ``` The local Docker services use `restart: unless-stopped`, so containers should come back after laptop restart if Docker starts. -## 8. Coding Standards & AI Directives +## 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. * **Tailwind Architecture:** All styling must be handled via Tailwind CSS utility classes. Avoid custom CSS files unless defining global font families or root variables in `index.css`. @@ -141,7 +177,7 @@ The local Docker services use `restart: unless-stopped`, so containers should co * **API Security:** All backend modifications exposing or altering data MUST use the `verifyToken` middleware for frontend requests or `authenticateAPIKey` for external n8n webhooks. * **Build Discipline:** After frontend/backend behavior changes, run `npm run lint`, `npm run build`, and relevant backend tests. The user prefers builds after changes to catch issues before deployment. -## 9. Recent RFV Work +## 10. Recent Work Recent commits related to RFV/date and client metadata behavior: * `4131bf9 Update RFV lifecycle to monthly windows` - RFV recency/lost thresholds changed to `0-7`, `8-15`, `16-29`, and `30+` lost. * `ef27cff Add seller performance dashboard charts` - dashboard now includes seller revenue/order charts. @@ -165,3 +201,20 @@ Files most relevant to RFV: * `src/components/DateRangePicker.tsx` and `src/dateRanges.ts` - local calendar date ranges and ISO query param formatting. * `src/dataService.ts` - analytics fetch/cache helpers and client filter option requests. * `src/displayFormatters.ts` - shared seller/fantasy/client metadata display cleanup. + +Recent commits related to supply/cutting/data-flow and chart readability: +* `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. +* `9489318 Improve chart readability and drilldowns` - dashboard/product charts gained date bucketing, cleaner unknown labels, click drill-downs, and product stock coverage context. +* `ba9cc3a Fix large sold quantity icon layout` - product/group sold quantity cells handle large values without icon compression. +* `f923489 Make dashboard trend line optional` - dashboard moving-average trend line is hidden by default and available through `Tendência`. + +Files most relevant to supply/cutting/data-flow: +* `src/pages/Supplies.tsx` - supply dashboard, receipts, inventory, movements, and purchase-need UI. +* `src/pages/Cutting.tsx` - cut plan, cut settings drawer, SKU correction/deep-link flow. +* `src/pages/Registrations.tsx` - local catalog, raw materials, finished products, and consumption references. +* `src/catalogLinks.ts` - shared deep-link builders for SKU edit, cutting config, and consumption references. +* `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.