Stan
146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
## What is included
|
|
|
|
- Node.js REST API for template and configuration delivery
|
|
- MariaDB schema for phase 1 configuration data
|
|
- 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
|
|
|
|
## 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
|
|
|
|
Not included:
|
|
- report upload
|
|
- authentication
|
|
- admin UI
|
|
- report draft storage backend
|
|
- XLSX or ZIP generation
|
|
- client-side offline application
|
|
|
|
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.
|
|
|
|
## Project structure
|
|
|
|
```text
|
|
.
|
|
├── .devcontainer/
|
|
├── docker-compose.yml
|
|
├── package.json
|
|
├── scripts/
|
|
│ └── test-environment.js
|
|
├── sql/
|
|
│ ├── schema.sql
|
|
│ └── seed.sql
|
|
└── src/
|
|
├── app.js
|
|
├── server.js
|
|
├── config/
|
|
├── db/
|
|
├── middleware/
|
|
├── routes/
|
|
├── services/
|
|
└── utils/
|
|
```
|
|
|
|
## Run with Docker and Dev Containers
|
|
|
|
1. Copy `.env.example` to `.env` if you want custom local credentials.
|
|
2. In VS Code, run `Dev Containers: Reopen in Container`.
|
|
3. Or start the stack directly with `docker compose up -d --build`.
|
|
|
|
Services:
|
|
- API: `http://localhost:3000`
|
|
- phpMyAdmin: `http://localhost:8080`
|
|
- MariaDB: `localhost:3306`
|
|
|
|
The workspace is bind-mounted into the `app` container, so project files remain editable from VS Code.
|
|
|
|
## Database bootstrap
|
|
|
|
On a fresh MariaDB volume, Docker loads `sql/schema.sql` and `sql/seed.sql` automatically.
|
|
|
|
If you already have an older local database volume, either recreate it with `docker compose down -v` or import the SQL files manually:
|
|
|
|
```bash
|
|
docker compose exec -T db sh -lc 'mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" < /docker-entrypoint-initdb.d/schema.sql && mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" < /docker-entrypoint-initdb.d/seed.sql'
|
|
```
|
|
|
|
## Validate the environment
|
|
|
|
Run the smoke test after the containers are up:
|
|
|
|
```bash
|
|
npm run test:environment
|
|
```
|
|
|
|
The test verifies:
|
|
- the API health endpoint
|
|
- seeded template data via `/api/templates`
|
|
- direct MariaDB connectivity
|
|
- phpMyAdmin availability
|
|
|
|
## API endpoints
|
|
|
|
### Service health
|
|
|
|
`GET /api/health`
|
|
|
|
### Templates
|
|
|
|
- `GET /api/templates`
|
|
- `GET /api/templates/incoming-inspection`
|
|
- `GET /api/templates/incoming-inspection/versions/1`
|
|
|
|
### Lookups
|
|
|
|
- `GET /api/lookups`
|
|
- `GET /api/lookups/pass-fail`
|
|
|
|
### Configuration
|
|
|
|
- `GET /api/config/image-rules`
|
|
- `GET /api/config/export`
|
|
- `GET /api/config/app-config`
|
|
|
|
## Example response
|
|
|
|
`GET /api/templates/incoming-inspection`
|
|
|
|
```json
|
|
{
|
|
"code": "incoming-inspection",
|
|
"name": "Incoming Inspection Checklist",
|
|
"description": "PoC template for supplier or incoming goods quality inspection.",
|
|
"version": 1,
|
|
"status": "active",
|
|
"publishedAt": "2026-04-09T10:00:00.000Z",
|
|
"definition": {
|
|
"templateId": "incoming-inspection",
|
|
"templateName": "Incoming Inspection Checklist",
|
|
"version": 1,
|
|
"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. |