Updated AGENTS.md and KNOWLEDE.MD
This commit is contained in:
@@ -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.
|
||||
|
||||
+203
-17
@@ -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/<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.
|
||||
|
||||
Reference in New Issue
Block a user