Initial stage

2026-04-09 19:15:39 +02:00
commit d9f0b21b10
35 changed files with 3318 additions and 0 deletions
@@ -0,0 +1,274 @@
+# Check List Initial Solution Proposal
+
+## 1. Recommended Starting Point
+
+The strongest initial implementation is an offline-first web application with a thin server-backed configuration layer.
+
+This matches the source document's core constraint set:
+- reports must work without permanent internet access,
+- templates must be centrally controlled,
+- final output remains file-based,
+- the architecture must be extendable toward future synchronization.
+
+## 2. Proposed Architecture
+
+### Client application
+
+Build a responsive Progressive Web App using:
+- React
+- TypeScript
+- IndexedDB for offline persistence
+- a service worker for application asset caching
+- browser-based image processing using Canvas or createImageBitmap
+- XLSX generation library
+- ZIP generation library
+
+Main client modules:
+- template cache module
+- dynamic form renderer
+- report draft repository
+- image processing pipeline
+- validation engine
+- Excel export mapper
+- ZIP packaging module
+- sync-ready integration layer placeholder
+
+### Server application
+
+Build a small REST API using:
+- Node.js
+- Express or Fastify
+- MariaDB
+
+Main server responsibilities:
+- template CRUD
+- template versioning
+- lookup management
+- validation rule delivery
+- image rule delivery
+- export configuration delivery
+- optional authentication later
+
+The server should not accept completed reports in phase 1.
+
+## 3. Why This Design Fits
+
+This design solves the main business problems without introducing early complexity:
+- central governance is handled by the backend,
+- offline draft work is handled entirely on the client,
+- images are optimized before storage/export,
+- ZIP export preserves compatibility with the current file-based process,
+- future synchronization can be added without replacing the client-side report model.
+
+## 4. Initial Technical Blueprint
+
+### Frontend structure
+
+Suggested feature-oriented structure:
+
+```text
+src/
+  app/
+  features/templates/
+  features/reports/
+  features/images/
+  features/export/
+  features/validation/
+  features/dashboard/
+  shared/ui/
+  shared/lib/
+  shared/storage/
+  shared/api/
+```
+
+Key implementation decisions:
+- use template-driven rendering instead of hardcoded forms,
+- keep report state normalized by report ID,
+- store attachments separately from answer objects in IndexedDB,
+- version templates immutably once published,
+- separate draft validation from export validation.
+
+### Backend structure
+
+Suggested backend domains:
+- templates
+- templateVersions
+- fields
+- lookups
+- validationRules
+- imageRules
+- exportSettings
+
+Recommended principle:
+the API should deliver a fully materialized template definition for a chosen version so the client can render forms without additional server joins during report editing.
+
+## 5. Minimal Phase 1 Data Model
+
+### Server-side entities
+
+Recommended MariaDB tables:
+- templates
+- template_versions
+- template_sections
+- template_fields
+- field_validation_rules
+- lookup_sets
+- lookup_values
+- image_rules
+- export_profiles
+
+Important rules:
+- only one active version per template for new report creation,
+- old versions remain readable for existing drafts,
+- template JSON snapshots can be generated and cached for fast client download.
+
+### Client-side entities
+
+Recommended IndexedDB stores:
+- templatesCache
+- reports
+- reportAnswers
+- attachments
+- appConfig
+
+Example report aggregate:
+
+```json
+{
+  "id": "local-report-uuid",
+  "reportNumber": "QC-2026-0001",
+  "templateId": "incoming-inspection",
+  "templateVersion": 3,
+  "status": "in_progress",
+  "header": {
+    "supplier": "ACME",
+    "inspectionDate": "2026-04-09"
+  },
+  "createdAt": "2026-04-09T09:00:00Z",
+  "updatedAt": "2026-04-09T10:15:00Z"
+}
+```
+
+Example attachment metadata:
+
+```json
+{
+  "id": "attachment-uuid",
+  "reportId": "local-report-uuid",
+  "fieldId": "damage-photo",
+  "originalFilename": "IMG_0412.jpg",
+  "generatedFilename": "QC-2026-0001_SEC01_001.jpg",
+  "mimeType": "image/jpeg",
+  "width": 1600,
+  "height": 1200,
+  "sizeBytes": 245312
+}
+```
+
+## 6. Recommended API Surface
+
+Initial REST endpoints:
+- `GET /api/templates`
+- `GET /api/templates/:templateId`
+- `GET /api/templates/:templateId/versions/:version`
+- `GET /api/lookups`
+- `GET /api/config/image-rules`
+- `GET /api/config/export`
+- `GET /api/app-config`
+
+Optional later endpoints:
+- `POST /api/auth/login`
+- `POST /api/report-uploads`
+
+API response strategy:
+- return explicit version metadata with every template,
+- include cache timestamps or ETags,
+- support incremental refresh later if template volume grows.
+
+## 7. Core User Flow
+
+Phase 1 flow should be:
+1. User opens the app online.
+2. App downloads active templates and configuration.
+3. Data is cached locally.
+4. User creates or resumes a report.
+5. Report is auto-saved into IndexedDB.
+6. Images are validated, optimized, renamed, and stored locally.
+7. User marks the report ready for export.
+8. Full validation runs.
+9. App generates XLSX.
+10. App packages XLSX and images into a ZIP and downloads it locally.
+
+## 8. Delivery Plan
+
+### Iteration 1
+- define template JSON contract,
+- define MariaDB schema,
+- implement template read API,
+- build application shell and offline cache,
+- build report dashboard and draft persistence.
+
+### Iteration 2
+- implement dynamic checklist renderer,
+- implement draft save and resume,
+- implement report switching and status management,
+- implement export-readiness validation.
+
+### Iteration 3
+- implement image attach, preview, compression, and renaming,
+- implement XLSX mapping,
+- implement ZIP export,
+- run pilot tests on Windows, Android, and iOS.
+
+### Iteration 4
+- harden error handling,
+- tune storage usage,
+- add admin-facing template maintenance workflow,
+- prepare phase 2 synchronization extension points.
+
+## 9. Open Gaps That Still Need Definition
+
+The source document is strong at the concept level, but these items still need explicit specification before implementation starts:
+- exact template JSON schema,
+- exact report numbering strategy,
+- exact Excel layout and formatting rules,
+- rule language for conditional validation,
+- whether PWA installation is required or optional,
+- retention and deletion rules for local drafts,
+- browser support baseline and test matrix,
+- authentication requirements for template administration.
+
+## 10. Main Risks and Mitigations
+
+### Risk: local draft loss
+Mitigation: auto-save, visible save state, export reminders, later import/export backup feature.
+
+### Risk: storage pressure from images
+Mitigation: enforce compression rules, cap attachment count where needed, show storage usage warnings.
+
+### Risk: template drift
+Mitigation: immutable template versions and version-bound drafts.
+
+### Risk: export mismatch with current Excel expectations
+Mitigation: validate the XLSX output format early using sample reports before full UI completion.
+
+## 11. Final Recommendation
+
+Proceed with a phase 1 implementation based on:
+- React + TypeScript PWA frontend,
+- IndexedDB local persistence,
+- Node.js REST backend,
+- MariaDB template repository,
+- local XLSX and ZIP export.
+
+This is the lowest-risk path that still satisfies the documented requirements and preserves a clean path to later server-side synchronization.
+
+## 12. Best Immediate Next Steps
+
+The next concrete deliverables should be:
+1. template JSON schema,
+2. MariaDB schema draft,
+3. API contract draft,
+4. report and attachment IndexedDB schema,
+5. one sample export template in XLSX format,
+6. a first implementation backlog split into frontend and backend work items.