From a6791cb0384af31866def8ade78a1a0c90540974 Mon Sep 17 00:00:00 2001 From: Martin Tazl Date: Fri, 3 Jul 2026 13:53:12 +0200 Subject: [PATCH] Updated AGENTS.md and KNOWLEDE.MD --- AGENTS.md | 79 ++++++++++++++-- PROJECT_KNOWLEDGE.md | 220 +++++++++++++++++++++++++++++++++++++++---- 2 files changed, 276 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 42c8381..3c038d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,73 @@ -- Vor größeren Änderungen immer einen Plan erstellen. -- Keine neuen Python-Pakete ohne Zustimmung. -- Bestehende APIs nicht ohne Rückfrage ändern. -- Python-Code nach PEP8. -- JavaScript möglichst modern (ES6). -- Kommentare sparsam verwenden. +# AGENTS.md + +Guidance for coding agents working in this repository. + +## Scope + +This project is a small Flask application with a mostly client-side calculator UI. Treat it as an internal tool with sensitive access and product data assumptions. + +Primary files: + +- `app.py`: Flask app, HTTP Basic Auth, routes, access logging. +- `templates/roll_calculator.html`: active calculator UI, inline CSS, inline JavaScript, disclaimer gate, roll calculations, forklift check, load optimizer. +- `static/article-data.json`: active product/article data loaded by the UI. +- `static/config.json`: richer forklift/heavy-roll configuration, although the active template also contains inline config. +- `README.md`: developer-facing project overview. +- `PROJECT_KNOWLEDGE.md`: project-specific domain and implementation knowledge. + +## Working Rules + +- Before larger changes, present a concise plan. +- Do not change functional logic unless explicitly requested. +- Keep edits narrowly scoped to the requested task. +- Do not remove existing features or routes without explicit approval. +- Do not add Python packages without approval. +- Do not change existing APIs, route paths, data formats, or authentication behavior without approval. +- Do not manually edit generated product data unless the user explicitly asks for data maintenance. +- Preserve the current Flask/vanilla JavaScript architecture unless the task is specifically a refactor. +- Prefer documenting observed behavior over assuming intended behavior. + +## Code Style + +- Python should follow PEP 8. +- JavaScript should use modern ES6 style where it fits the existing code. +- Keep comments sparse and useful. +- Use clear names over explanatory comments where possible. +- Avoid broad refactors in `templates/roll_calculator.html`; it is large and risk-prone. + +## Validation Expectations + +For backend or template changes: + +- Start the app locally when practical. +- If port `5000` is occupied, use: + +```bash +flask --app app run --host 127.0.0.1 --port 5001 +``` + +- Check authenticated endpoints with Basic Auth when practical. +- For pure documentation changes, no runtime validation is required. + +Known local credential currently present in `app.py`: + +```text +mtazl / rollcalc +``` + +These credentials are hardcoded and are a known risk; do not introduce more secrets. + +## Important Technical Constraints + +- `app.py` currently hardcodes users and passwords. +- Access logging writes to `access_log.json` by reading and rewriting the whole file. +- The active UI logic is largely inline in `templates/roll_calculator.html`. +- Several `static/*.js` files appear to be older, alternative, or integration modules. Confirm script inclusion before modifying them. +- The admin template and backend admin routes are inconsistent at the moment. +- The disclaimer confirmation is client-side only. + +## Safety Notes + +- Treat `static/article-data.json` as generated ERP-derived data. +- The project contains product/material assumptions. Do not adjust formulas, thresholds, or category rules without a specific request. +- The calculator output is advisory and requires plausibility checks before use. diff --git a/PROJECT_KNOWLEDGE.md b/PROJECT_KNOWLEDGE.md index a3e5b28..e812080 100644 --- a/PROJECT_KNOWLEDGE.md +++ b/PROJECT_KNOWLEDGE.md @@ -1,26 +1,212 @@ -## Rollengeometrie +# PROJECT_KNOWLEDGE.md -Die Berechnungen basieren auf einer ideal zylindrischen Wicklung. +Project-specific technical and domain knowledge for RollCalcPython. -Annahmen: -- konstante Materialdicke -- keine Kompression -- keine Luftzwischenräume +## Purpose -Abweichungen: -- Bei Artikeln der Gruppe Secugrid, Combigrid, Carbofol MF/MF, Carbofol F/F, Carbofol s/F, Carbofol BF/s darf die Dicke aus der articel-data.json nicht verwendet werden +RollCalcPython is an internal roll calculator for Naue roll products. The backend is a minimal Flask application that provides authentication, routing, static file delivery, and access logs. Most domain behavior runs in the browser inside `templates/roll_calculator.html`. -## Artikeldaten +The tool is not intended as an unchecked source of truth. Inputs and outputs must be checked for plausibility before operational use. -Die JSON-Datei wird automatisch aus dem ERP erzeugt. +## Current Architecture -Felder: -- Artikelnummer -- Dicke -- Flächengewicht -- Standardabweichung -- Kern +Backend: -Diese Werte dürfen niemals manuell verändert werden. +- `app.py` creates the Flask app. +- HTTP Basic Auth is implemented with `Flask-HTTPAuth`. +- Users are currently hardcoded in `BETA_USERS` and `ADMIN_USERS`. +- `/` renders the active calculator template. +- `/static/` is intended to serve static files behind Basic Auth. +- `/api/health` returns health/version information. +- `/api/user` returns the authenticated user and admin flag. +- `/admin/logs` returns access logs for admin users. +- Access events are appended to `access_log.json`. +Frontend: +- `templates/roll_calculator.html` is the active application page. +- The page contains most CSS and JavaScript inline. +- `window.ARTICLE_DATA` is loaded from `/static/article-data.json`. +- `window.APP_CONFIG` is currently defined inline for forklift rules. +- A disclaimer modal blocks use until the user checks the confirmation checkbox. + +## Roll Geometry + +Calculations assume an ideal cylindrical winding. + +Assumptions: + +- Constant material thickness. +- No compression. +- No air gaps. +- Roll geometry is derived mathematically, not physically measured in the app. + +Nominal diameter formula used by the Direct Calculation tab: + +```text +D = sqrt(d^2 + (4 * L * 1000 * t) / pi) +``` + +Variables: + +- `D`: roll diameter in mm. +- `d`: core diameter in mm. +- `L`: product length in m. +- `t`: material thickness in mm. + +When a tolerance/stddev value is present, the UI also displays a `-2σ` and `+2σ` diameter range. + +## Product Length and Extrapolation + +Product length from a known diameter is calculated by rearranging the diameter formula: + +```text +L = (pi / (4 * t)) * (D^2 - d^2) / 1000 +``` + +The extrapolation tab estimates a new diameter from a known roll diameter/length pair: + +```text +D1 = sqrt(d^2 + (L1 / L0) * (D0^2 - d^2)) +``` + +Variables: + +- `D0`: known/measured roll diameter. +- `L0`: known/measured roll length. +- `L1`: target length. +- `D1`: extrapolated roll diameter. + +## Roll Weight + +Roll weight is calculated client-side when width, area weight, and length are available: + +```text +weight_kg = area_weight_g_m2 * length_m * width_m / 1000 +``` + +Material thickness and area weight values are loaded from article data and are generated automatically. They are not guaranteed to be complete or reviewed. + +## Article Data + +Active data source: + +```text +static/article-data.json +``` + +The UI expects article records with fields such as: + +- `nr` +- `name` +- `thickness` +- `thickness_stddev` +- `area_weight` +- `area_weight_stddev` +- `core_type` + +Observed additional fields include min/max/count values for material thickness and area weight. + +Important data rule: + +- Article data is generated from ERP-derived sources. +- These values should not be manually changed unless the task is explicitly data maintenance. + +Known domain caveat from existing project notes: + +- For articles in the groups Secugrid, Combigrid, Carbofol MF/MF, Carbofol F/F, Carbofol s/F, and Carbofol BF/s, the thickness from `article-data.json` must not be used without domain validation. + +## Forklift and Heavy-Roll Rules + +The active template currently evaluates forklift warnings through `checkForklift()` and inline `window.APP_CONFIG`. + +Current inline rule behavior: + +- Applies to category `bentofix`. +- Warning threshold: `1700 kg`. +- Hard limit: `2750 kg`. +- Minimum core outer diameter: `170 mm`. + +There is also a richer JSON configuration in: + +```text +static/config.json +``` + +That file includes localized messages and additional equipment requirements. Before changing forklift behavior, verify whether the active inline config or the static JSON should be authoritative. + +## Load Optimizer + +The Load Optimizer is implemented inline in `templates/roll_calculator.html`. + +Classes: + +- `LoadOptimizer` +- `LoadOptimizerUI` + +It uses calculated roll data from the Direct Calculation tab: + +- Roll diameter. +- Core diameter. +- Roll width. +- Roll weight. +- Product length. +- Square meters per roll. + +It supports transport presets: + +- 20ft Container. +- 40ft Container. +- 40ft High Cube. +- LKW Sattelzug. +- LKW Tandem. + +It calculates limiting scenarios by: + +- Weight. +- Volume. +- Geometry. + +It also draws a side-view SVG visualization. + +## Disclaimer Gate + +The active calculator page includes a disclaimer modal shown after Basic Auth login and before calculator use. + +The modal: + +- Contains German and English disclaimer text. +- Requires checkbox confirmation. +- Enables the confirmation button only after the checkbox is selected. +- Hides the overlay after confirmation. + +This is client-side only. It is not persisted, logged, or enforced server-side. + +## Admin Area State + +Current backend route: + +```text +/admin/logs +``` + +Current `templates/admin.html` expects: + +```text +/api/admin/stats +/api/admin/logs +``` + +Those `/api/admin/*` endpoints are not currently implemented in `app.py`, and there is no route rendering `templates/admin.html`. + +## Known Technical Risks + +- Hardcoded plaintext credentials in `app.py`. +- Basic Auth only; no sessions or role framework beyond user dictionaries. +- `access_log.json` is rewritten on every logged request and is not concurrency-safe. +- No log rotation or retention policy is implemented. +- Flask's default static route may conflict with the intended authenticated `/static/` behavior; verify effective routing before relying on protected static files. +- Most active logic is concentrated in one large HTML template. +- Multiple similar static JavaScript files exist; not all are necessarily active. +- No automated test suite is visible. +- Some docs and filenames in `docs/` may reflect earlier package/archive versions.