smlynarczyk85/CLProject
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

stage 1

Browse Source
This commit is contained in:
Stan
2026-04-19 21:14:16 +02:00
parent 0c74a75126
commit 28d167f11f
42 changed files with 5681 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+134 -39
View File
@@ -1,34 +1,44 @@
# Check List Proof of Concept
This repository contains a minimal proof-of-concept backend for the Check List hybrid reporting solution described in the project documentation.
This repository contains a proof-of-concept implementation for the Check List hybrid reporting solution described in the project documentation.
## What is included
- Node.js REST API for template and configuration delivery
- MariaDB schema for phase 1 configuration data
- Node.js REST API (v1) for template, configuration, report, and audit delivery
- static frontend PoC served by Express, split into focused ES modules
- MariaDB schema for configuration data, submitted reports, and audit trail
- seed data with one sample inspection checklist template
- lookup values, image policy, and export profile
- Docker Compose and VS Code Dev Container setup for local development
- service worker with bounded LRU cache for offline support
## Scope of this PoC
Included:
- template list endpoint
- active template endpoint
- specific template version endpoint
- lookup endpoints
- image rule endpoint
- export profile endpoint
- generic application config endpoint
- MariaDB schema and seed data
- all endpoints under versioned `/api/v1/` prefix
- batch template endpoint with `?include=definitions` for single-request sync
- template version listing and publishing management
- lookup endpoints with parameter validation
- image rule endpoint with server-side LRU cache and audit trail
- export profile and generic application config endpoints
- report submission endpoint (POST) with UPSERT
- audit log recording for admin mutations
- offline-capable frontend shell split into ES modules
- IndexedDB-based local drafts with multi-store transactions
- dynamic form rendering from template JSON
- local attachment storage with Web Worker image optimization
- report search and status filter
- CSV export for report data
- i18n locale extraction for UI strings
- PWA manifest with SVG icon
- debounced renders and dirty-flag autosave
Not included:
- report upload
- authentication
- admin UI
- report draft storage backend
- XLSX or ZIP generation
- client-side offline application
- authentication and authorization
- file attachment upload to server (binary upload requires multer)
- XLSX or ZIP generation (CSV is provided; advanced formats require library vendoring)
- production-grade frontend bundling
- automated test suite
The PoC keeps template content inside a JSON column to reduce initial complexity and speed up delivery. This is deliberate for phase 1 proof-of-concept work.
@@ -39,6 +49,29 @@ The PoC keeps template content inside a JSON column to reduce initial complexity
├── .devcontainer/
├── docker-compose.yml
├── package.json
├── public/
│ ├── admin.html ← administrator workspace
│ ├── app.js ← thin orchestrator entry point
│ ├── icon.svg ← PWA icon
│ ├── index.html ← legacy combined shell (unused)
│ ├── manifest.webmanifest
│ ├── portal.html
│ ├── styles.css
│ ├── sw.js
│ ├── user.html ← operator workspace
│ └── js/
│ ├── api.js ← API communication (versioned base path)
│ ├── constants.js ← shared constants (DB, API, limits)
│ ├── db.js ← IndexedDB operations, multi-store tx
│ ├── export.js ← CSV export and attachment download
│ ├── forms.js ← dynamic form field creation
│ ├── i18n.js ← English locale, t() translation
│ ├── image-worker.js ← OffscreenCanvas Web Worker
│ ├── images.js ← image optimization with worker fallback
│ ├── renderer.js ← all render functions with search/filter
│ ├── state.js ← centralized state management
│ ├── utils.js ← utility functions
│ └── validation.js ← shared validation (client-side)
├── scripts/
│ └── test-environment.js
├── sql/
@@ -48,13 +81,34 @@ The PoC keeps template content inside a JSON column to reduce initial complexity
├── app.js
├── server.js
├── config/
│ └── env.js
├── db/
│ └── pool.js
├── middleware/
│ ├── errorHandler.js
│ └── validateParams.js ← URL parameter validation
├── routes/
│ ├── configRoutes.js
│ ├── healthRoutes.js
│ ├── lookupRoutes.js
│ ├── reportRoutes.js ← report submission endpoints
│ └── templateRoutes.js
├── services/
│ ├── auditService.js ← audit trail logging
│ ├── cacheService.js ← in-memory LRU cache with TTL
│ ├── configService.js
│ ├── lookupService.js
│ ├── reportService.js ← report CRUD operations
│ └── templateService.js
└── utils/
├── asyncHandler.js
└── json.js
```
## File guide
For a junior-friendly explanation of what each main file does, see [PROJECT_FILES_GUIDE.md](PROJECT_FILES_GUIDE.md).
## Run with Docker and Dev Containers
1. Copy `.env.example` to `.env` if you want custom local credentials.
@@ -87,37 +141,87 @@ npm run test:environment
```
The test verifies:
- the API health endpoint
- seeded template data via `/api/templates`
- the API health endpoint at `/api/v1/health`
- seeded template data via `/api/v1/templates`
- direct MariaDB connectivity
- phpMyAdmin availability
## Frontend PoC
Open `http://localhost:3000` after the stack is running.
Entry points:
- `http://localhost:3000/` opens the chooser portal
- `http://localhost:3000/user` opens the user workspace directly
- `http://localhost:3000/admin` opens the administrator workspace directly
The frontend demonstrates:
- template sync from the API via batch endpoint
- offline cache via IndexedDB and service worker (LRU-bounded)
- local report creation, switching, search, and filtering
- dynamic form rendering based on the seeded template
- local attachment storage and preview with lazy-loading
- Web Worker image optimization (OffscreenCanvas) with main-thread fallback
- debounced re-renders and dirty-flag autosave
- report submission to backend
- CSV export for report data and individual attachment downloads
- administrator mode for editing image requirements with audit trail
- i18n-ready UI strings extracted to locale file
This frontend is intentionally lightweight and framework-free so the proof of concept stays easy to inspect and adapt. The monolithic app.js has been split into focused ES modules under `public/js/`, and the UI is served as two separate HTML shells (`user.html` for operators, `admin.html` for administrators) sharing a single `app.js` orchestrator with null-guarded element access.
## Administrator mode
Open `http://localhost:3000/admin` or use the chooser page at `http://localhost:3000/`.
The current PoC administrator flow supports:
- policy name changes
- allowed MIME types
- maximum file size
- maximum width and height
- JPEG quality
- oversize behavior
- maximum attachments per field
The frontend saves these values to the backend through `PUT /api/v1/config/image-rules` and refreshes the local cache after save. All admin mutations are recorded in the audit log.
## API endpoints
All endpoints are under the `/api/v1/` prefix.
### Service health
`GET /api/health`
`GET /api/v1/health`
### Templates
- `GET /api/templates`
- `GET /api/templates/incoming-inspection`
- `GET /api/templates/incoming-inspection/versions/1`
- `GET /api/v1/templates` — list active templates
- `GET /api/v1/templates?include=definitions` — batch: all templates with definitions in one request
- `GET /api/v1/templates/:code` — single active template with definition
- `GET /api/v1/templates/:code/versions` — list all versions of a template
- `PUT /api/v1/templates/:code/versions/:versionNumber/publish` — publish a specific template version
### Lookups
- `GET /api/lookups`
- `GET /api/lookups/pass-fail`
- `GET /api/v1/lookups` — list all lookup sets
- `GET /api/v1/lookups/:code` — single lookup set with values
### Configuration
- `GET /api/config/image-rules`
- `GET /api/config/export`
- `GET /api/config/app-config`
- `GET /api/v1/config/image-rules` — active image policy
- `PUT /api/v1/config/image-rules` — update image policy (audit-logged)
- `GET /api/v1/config/export` — export profile
- `GET /api/v1/config/app-config` — generic app configuration
### Reports
- `GET /api/v1/reports` — list submitted reports (supports `?status=`, `?templateCode=`, `?limit=`, `?offset=`)
- `GET /api/v1/reports/:reportId` — single submitted report
- `POST /api/v1/reports` — submit or update a report (UPSERT by UUID)
## Example response
`GET /api/templates/incoming-inspection`
`GET /api/v1/templates/incoming-inspection`
```json
{
@@ -134,13 +238,4 @@ The test verifies:
"sections": []
}
}
```
## Recommended next step after this PoC
The next logical implementation layer is the client application that:
- caches templates in IndexedDB,
- renders forms dynamically from `definition`,
- stores local drafts and image metadata,
- applies validation rules before export,
- generates XLSX and ZIP locally.
```