133 lines
6.8 KiB
Markdown
133 lines
6.8 KiB
Markdown
# Catalog Maker Project Notes
|
|
|
|
## Purpose
|
|
|
|
This project replaces the Excel/VBA workflow named `Catalog maker - 20` with a Node.js local web application. The UI is a compact product catalog editor for loading manufacturer products, combinations, source mappings and parsed supplier data.
|
|
|
|
## Non-negotiable rules
|
|
|
|
- Live DB is never written to. Live DB access is read-only through the existing endpoint.
|
|
- Local DB may later allow controlled writes, but writes must remain explicit, logged and protected by transaction/dry-run settings.
|
|
- Never print, commit or share endpoint tokens, usernames or passwords.
|
|
- Never use Live DB as a fallback when Local DB is selected. If Local DB is unavailable, show an error and keep the UI running.
|
|
- Keep the development server on port `3404` unless the user explicitly requests another port.
|
|
- Do not delete or revert user files or unrelated changes.
|
|
|
|
## Git workflow
|
|
|
|
- After every completed implementation step, run the relevant checks, create a focused commit and push it to the configured remote repository.
|
|
- Use short, descriptive commit messages that state the completed change.
|
|
- Never commit `.env`, `config/local.json`, passwords, tokens, the Excel workbook or database dumps.
|
|
- Before the first push, initialize Git if needed, configure the project remote and create an initial baseline commit from safe files only.
|
|
- If a push fails, do not expose credentials in the terminal output or in chat; report the failure without printing secrets.
|
|
|
|
## UI inspection workflow
|
|
|
|
- Use Playwright for browser inspections and visual verification of the local application.
|
|
- Run `npm run test:ui` after frontend or layout changes.
|
|
- Check for page errors, visible controls, modal behavior and important responsive states.
|
|
- Keep screenshots and traces in Playwright's ignored `test-results/` and `playwright-report/` directories; do not commit them.
|
|
- A UI change is not complete until the relevant Playwright checks pass.
|
|
|
|
## Styling workflow
|
|
|
|
- Use Tailwind CSS for new styling and UI changes.
|
|
- Keep shared tokens in `src/tailwind.css` using `@theme` and base/component layers.
|
|
- Run `npm run css:build` after styling changes; `public/styles.css` is generated output.
|
|
- Prefer Tailwind utility classes and Tailwind-style component patterns for buttons, panels, dialogs and responsive layouts.
|
|
- Use Playwright to inspect the rendered result after every visual change at desktop and narrow viewport sizes.
|
|
|
|
## Runtime
|
|
|
|
- Start the web app with `npm run dev`.
|
|
- Open `http://127.0.0.1:3404/`.
|
|
- The current server is `src/server.js`.
|
|
- Configuration is loaded from `config/local.json`, merged over `config/local.example.json`.
|
|
- `.env` exists for local MariaDB notes, but the application does not yet load `.env` automatically. Do not assume `.env` is active until configuration loading is explicitly wired to it.
|
|
|
|
## Database architecture
|
|
|
|
There are two selectable data sources:
|
|
|
|
### Live DB
|
|
|
|
- Uses the existing 9b-plus API endpoint configured in `config/local.json`.
|
|
- Credentials are secret and must stay server-side.
|
|
- Must remain read-only.
|
|
|
|
### Local DB
|
|
|
|
- MariaDB is installed locally as service `MariaDB`.
|
|
- Host: `localhost` / `127.0.0.1`.
|
|
- Port: `3306`.
|
|
- Database: `9bplus`.
|
|
- A full dump from `9bplus (1).sql.gz` was imported locally.
|
|
- Verified local contents: about 266 tables, 74 manufacturers, 8,888 products and 48,206 product combinations.
|
|
- The import was local only and did not contact Live DB.
|
|
- The project currently needs to be switched to `database.driver = "mariadb"` and supplied with local credentials before the UI can read this database.
|
|
|
|
## Database safety behavior
|
|
|
|
- The UI has `Local DB` and `Live DB` settings.
|
|
- The UI sends the selected mode using the `X-Database-Mode` request header.
|
|
- Backend data API routes reject a Local DB request when MariaDB is not configured instead of silently using the endpoint.
|
|
- Backend data API routes reject a Live DB request when the project is configured only for MariaDB.
|
|
- Static HTML/CSS/JS files must remain available even when a database is not configured.
|
|
- The top status shows the selected source, connection state, permissions and execution mode.
|
|
|
|
## Important current files
|
|
|
|
- `src/server.js`: HTTP server, API routes, mode guard and status endpoint.
|
|
- `src/config.js`: configuration loading and database settings.
|
|
- `src/endpoint/endpoint-client.js`: endpoint queries and MariaDB routing.
|
|
- `src/db/mariadb-client.js`: MariaDB pool, read queries, local writes and connection test.
|
|
- `src/services/catalog-products.js`: product, combinations, mapping, source and picture workflow.
|
|
- `public/index.html`: compact catalog UI and settings modal.
|
|
- `public/app.js`: UI state, API calls, Local/Live mode header, local settings and source workflow.
|
|
- `public/styles.css`: compact modern layout.
|
|
- `config/local.example.json`: safe configuration template.
|
|
- `config/local.json`: local secrets and machine-specific configuration; never expose it.
|
|
|
|
## Current UI behavior
|
|
|
|
- Manufacturer and language selects load from the selected database.
|
|
- Product data loads when manufacturer changes or navigation arrows are used.
|
|
- `Get product info` remains a separate action.
|
|
- EAN scan input searches on Enter.
|
|
- `Find sources` searches once and caches candidates for the current product; a second click reopens cached results.
|
|
- Source candidates show how they were found, including EAN/reference/name and color context.
|
|
- Each source row has its own `Get pictures` action.
|
|
- Product source cache is cleared when a new product loads.
|
|
- Hudy picture parsing uses the correct product color variant, checks EANs and extracts large gallery images.
|
|
- Idealo uses the browser adapter and is intended mainly as a picture source.
|
|
- Image preview is square.
|
|
- Settings is at the bottom of the left panel; database status is directly above it.
|
|
|
|
## Settings
|
|
|
|
The settings modal contains:
|
|
|
|
- Local DB / Live DB selection.
|
|
- Local DB connection fields: host, port, database, user and password.
|
|
- `Test connection`, which performs a read-only `SELECT VERSION()` against local MariaDB only.
|
|
- Local insert/update/delete permission switches.
|
|
- Transaction confirmation or dry-run preview mode.
|
|
- Live DB permissions are always read-only.
|
|
|
|
Local UI settings are stored in browser localStorage. They are not yet a replacement for server-side `config/local.json` credentials.
|
|
|
|
## Next safe step
|
|
|
|
Wire the local connection settings into server configuration without exposing Live credentials, then set the active local database driver to MariaDB and test manufacturer loading from the imported `9bplus` database. After that, verify that switching to Live uses only read-only endpoint queries.
|
|
|
|
## Verification commands
|
|
|
|
```powershell
|
|
node --check src/server.js
|
|
node --check src/db/mariadb-client.js
|
|
node --check public/app.js
|
|
npm test
|
|
```
|
|
|
|
For a local MariaDB check, use the installed client against `127.0.0.1:3306` and never the Live endpoint.
|