287 lines
9.3 KiB
Markdown
287 lines
9.3 KiB
Markdown
# RollCalcPython
|
||
|
||
Flask-based internal roll diameter calculator for Naue roll products. The app is a small authenticated Flask shell around a mostly client-side calculator UI.
|
||
|
||
This README is intended for developers maintaining the project, not for end users.
|
||
|
||
## Runtime Stack
|
||
|
||
- Python 3
|
||
- Flask 2.3.3
|
||
- Flask-HTTPAuth 4.8.0
|
||
- Vanilla HTML, CSS, and JavaScript
|
||
- JSON files for product data and forklift/load rules
|
||
|
||
Pinned Python dependencies are defined in `requirements.txt`.
|
||
|
||
## Local Setup
|
||
|
||
Create and activate a virtual environment:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
Start with the hardcoded settings in `app.py`:
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
By default this attempts to bind to:
|
||
|
||
```text
|
||
http://localhost:5000
|
||
```
|
||
|
||
If port `5000` is already occupied, start through Flask's CLI without changing files:
|
||
|
||
```bash
|
||
flask --app app run --host 127.0.0.1 --port 5001
|
||
```
|
||
|
||
The app uses HTTP Basic Auth. Current credentials are defined in `BETA_USERS` in `app.py`.
|
||
|
||
## Project Layout
|
||
|
||
```text
|
||
.
|
||
├── app.py
|
||
├── requirements.txt
|
||
├── README.md
|
||
├── access_log.json
|
||
├── config.json
|
||
├── article-data_.json
|
||
├── fix_article_data.py
|
||
├── service-worker.js
|
||
├── templates/
|
||
│ └── roll_calculator.html
|
||
├── static/
|
||
│ ├── article-data.json
|
||
│ ├── config.json
|
||
│ ├── service-worker.js
|
||
│ ├── stddev_calculator.js
|
||
│ ├── direct_calc_handler.js
|
||
│ ├── rollcalc_v14.js
|
||
│ ├── rollcalc_improvements.js
|
||
│ ├── rollcalc-improvements.js
|
||
│ ├── rollcalc_stddev_ranges.js
|
||
│ └── rollcalc_stddev_integration.js
|
||
└── docs/
|
||
├── DEPLOYMENT_GUIDE.md
|
||
├── QOL_UPDATE_SUMMARY.md
|
||
├── STDDEV_IMPLEMENTATION_CHECKLIST.md
|
||
└── STDDEV_RANGES_DOCS.md
|
||
```
|
||
|
||
## Backend
|
||
|
||
`app.py` owns the Flask application and authentication.
|
||
|
||
Implemented routes:
|
||
|
||
| Route | Methods | Auth | Purpose |
|
||
| --- | --- | --- | --- |
|
||
| `/` | `GET` | Basic Auth | Renders `templates/roll_calculator.html`. |
|
||
| `/static/<path:filename>` | `GET` | Basic Auth | Intended protected static-file serving from `static/`. |
|
||
| `/api/health` | `GET` | Basic Auth | Returns app health and version. |
|
||
| `/api/user` | `GET` | Basic Auth | Returns current authenticated user info. |
|
||
|
||
Authentication is implemented with `Flask-HTTPAuth`. The current code checks `BETA_USERS` and performs direct plaintext string comparison.
|
||
|
||
Access logging is handled by `log_access()`, which reads `access_log.json`, appends a record, and writes the whole file back.
|
||
|
||
## Frontend Entry Point
|
||
|
||
The active UI is `templates/roll_calculator.html`.
|
||
|
||
The template contains:
|
||
|
||
- Page layout and all main CSS.
|
||
- A disclaimer modal shown after Basic Auth login and before calculator use.
|
||
- Global state:
|
||
- `window.ARTICLE_DATA`
|
||
- `window.APP_CONFIG`
|
||
- Product/article data loading from `/static/article-data.json`.
|
||
- Direct roll calculations.
|
||
- Extrapolation calculations.
|
||
- Forklift/weight warnings.
|
||
- Load optimizer UI and calculations.
|
||
|
||
Most of the currently active JavaScript is inline in this template. Several files under `static/` appear to be older, alternative, or integration-oriented modules and should be checked before assuming they are active.
|
||
|
||
## Main Functional Areas
|
||
|
||
### Disclaimer Gate
|
||
|
||
The calculator page displays a modal disclaimer before use. The modal:
|
||
|
||
- Shows German and English disclaimer text.
|
||
- Requires a checkbox confirmation.
|
||
- Keeps the confirmation button disabled until checked.
|
||
- Hides the overlay after confirmation.
|
||
|
||
This is implemented in `templates/roll_calculator.html` and is client-side only.
|
||
|
||
### Article Data Loading
|
||
|
||
`templates/roll_calculator.html` fetches:
|
||
|
||
```text
|
||
/static/article-data.json
|
||
```
|
||
|
||
The loaded array is assigned to `window.ARTICLE_DATA` and used to populate article datalists for direct calculation and extrapolation.
|
||
|
||
Known article fields used by the UI include:
|
||
|
||
- `nr`
|
||
- `name`
|
||
- `thickness`
|
||
- `thickness_stddev`
|
||
- `area_weight`
|
||
- `area_weight_stddev`
|
||
- `core_type`
|
||
|
||
The active `static/article-data.json` currently contains product records with additional min/max/count statistics.
|
||
|
||
### Direct Calculation
|
||
|
||
The direct calculation tab supports multiple modes via mode buttons:
|
||
|
||
- Roll diameter from core diameter, material thickness, and product length.
|
||
- Product length from core diameter, material thickness, and roll diameter.
|
||
- Product length for a target diameter.
|
||
|
||
The nominal roll diameter formula used in the template is:
|
||
|
||
```text
|
||
D = sqrt(d^2 + (4 * L * 1000 * t) / pi)
|
||
```
|
||
|
||
Where:
|
||
|
||
- `D` is roll diameter in mm.
|
||
- `d` is core diameter in mm.
|
||
- `L` is product length in m.
|
||
- `t` is material thickness in mm.
|
||
|
||
If a tolerance/stddev value is present, the UI also displays a `-2σ` and `+2σ` diameter range.
|
||
|
||
Roll weight is calculated when roll width, area weight, and length are present:
|
||
|
||
```text
|
||
weight_kg = area_weight_g_m2 * length_m * width_m / 1000
|
||
```
|
||
|
||
### Extrapolation
|
||
|
||
The extrapolation tab estimates a new roll diameter from a known roll diameter/length pair and a new target length:
|
||
|
||
```text
|
||
D1 = sqrt(d^2 + (L1 / L0) * (D0^2 - d^2))
|
||
```
|
||
|
||
Where:
|
||
|
||
- `d` is core diameter.
|
||
- `D0` is measured/current diameter.
|
||
- `L0` is measured/current length.
|
||
- `L1` is target length.
|
||
- `D1` is the calculated new diameter.
|
||
|
||
### Forklift Check
|
||
|
||
`checkForklift()` in `templates/roll_calculator.html` evaluates heavy-roll warnings using `window.APP_CONFIG.forklift_rules`.
|
||
|
||
The current inline config targets the `bentofix` category and includes:
|
||
|
||
- Warning threshold: `1700 kg`
|
||
- Hard limit: `2750 kg`
|
||
- Minimum core outer diameter requirement: `170 mm`
|
||
|
||
There is also a richer `static/config.json` with localized messages and more detailed requirements.
|
||
|
||
### Load Optimizer
|
||
|
||
The Load Optimizer is implemented by inline classes in `templates/roll_calculator.html`:
|
||
|
||
- `LoadOptimizer`
|
||
- `LoadOptimizerUI`
|
||
|
||
It uses calculated roll data from the Direct Calculation tab and estimates loading capacity for transport presets or custom dimensions.
|
||
|
||
Preset transport units include:
|
||
|
||
- 20ft Container
|
||
- 40ft Container
|
||
- 40ft High Cube
|
||
- LKW Sattelzug
|
||
- LKW Tandem
|
||
|
||
The optimizer calculates limiting scenarios by:
|
||
|
||
- Weight
|
||
- Volume
|
||
- Geometry
|
||
|
||
It also renders a side-view SVG visualization of the loading arrangement.
|
||
|
||
### Standard Deviation Modules
|
||
|
||
There are standalone/static modules for standard deviation logic:
|
||
|
||
- `static/stddev_calculator.js`
|
||
- `static/rollcalc_stddev_ranges.js`
|
||
- `static/rollcalc_stddev_integration.js`
|
||
|
||
These provide or describe range calculations for material thickness, area weight, roll diameter, and roll weight. Check actual script inclusion before treating them as active in production, because the current template already contains inline stddev/tolerance behavior.
|
||
|
||
### Admin UI
|
||
|
||
RollCalc no longer contains an admin UI or admin API. Login/access logging remains in the backend, but logs are not exposed through a RollCalc admin screen.
|
||
|
||
Administration and maintenance of `article-data.json` is planned for a separate application. RollCalc should continue to consume `static/article-data.json` read-only.
|
||
|
||
## Static Assets and Data Files
|
||
|
||
### `static/article-data.json`
|
||
|
||
Primary product/article dataset used by the active calculator UI.
|
||
|
||
### `static/config.json`
|
||
|
||
JSON configuration for forklift/heavy-roll rules. The active template also contains an inline `window.APP_CONFIG`, so developers should verify which config source is authoritative before changing rule behavior.
|
||
|
||
### `access_log.json`
|
||
|
||
JSON audit log written by `app.py`.
|
||
|
||
Important implementation detail: each logged access reads and rewrites the entire JSON file. This is simple but not concurrency-safe and can become inefficient as the file grows.
|
||
|
||
### `fix_article_data.py`
|
||
|
||
Utility script that updates relative frontend fetch/register paths to Flask-style `/static/...` paths and checks that key static files exist.
|
||
|
||
## Development Notes
|
||
|
||
- The codebase is currently closer to a single-page static calculator wrapped by Flask than to a conventional Flask MVC app.
|
||
- The active calculator logic is concentrated in `templates/roll_calculator.html`.
|
||
- There are duplicated or legacy-looking files with similar names. Before editing JavaScript under `static/`, confirm it is actually referenced by the active template.
|
||
- The documentation under `docs/` contains deployment and feature notes, but some filenames and route assumptions may not match the current app exactly.
|
||
- The Flask dev server is used for local development only. Production should use a WSGI server.
|
||
|
||
## Known Risks and Maintenance Items
|
||
|
||
- Credentials are hardcoded in `app.py` and should be moved to environment variables or a secrets manager.
|
||
- Passwords are stored in plaintext and compared directly.
|
||
- `access_log.json` is not safe for concurrent writes.
|
||
- `access_log.json` grows without rotation or retention limits.
|
||
- The custom `/static/<path:filename>` route is intended to protect static files, but Flask also creates a default static route unless disabled. Verify effective route behavior before relying on static-file protection.
|
||
- RollCalc no longer includes an admin UI/API; article data administration belongs in a separate application.
|
||
- There is no visible automated test suite.
|
||
- The main template is large and mixes layout, styling, data loading, calculations, and UI behavior.
|
||
- The disclaimer confirmation is client-side only and is not persisted or audited server-side.
|