Updated AGENTS.md and KNOWLEDE.MD

2026-07-03 13:53:12 +02:00
parent 924a18dbc8
commit a6791cb038
2 changed files with 276 additions and 23 deletions
@@ -1,6 +1,73 @@
- Vor größeren Änderungen immer einen Plan erstellen.
+# AGENTS.md
- Keine neuen Python-Pakete ohne Zustimmung.
+
- Bestehende APIs nicht ohne Rückfrage ändern.
+Guidance for coding agents working in this repository.
- Python-Code nach PEP8.
+
- JavaScript möglichst modern (ES6).
+## Scope
- Kommentare sparsam verwenden.
+
 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.
@@ -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:
+## Purpose
 - konstante Materialdicke
 - keine Kompression
 - keine Luftzwischenräume
-Abweichungen:
+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`.
 - 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
-## 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:
+Backend:
 - Artikelnummer
 - Dicke
 - Flächengewicht
 - Standardabweichung
 - Kern
-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/<path:filename>` 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/<path:filename>` 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.