74 lines
5.0 KiB
Markdown
74 lines
5.0 KiB
Markdown
# HickLab3D dashboard
|
|
|
|
Laravel 13, Tailwind CSS 4, and MySQL dashboard for the HickLab3D workshop. It includes user accounts, Etsy shop data, BamBuddy printer status, Parcel2Go orders, and filament dryer control.
|
|
|
|
## Setup
|
|
|
|
Requirements: PHP 8.3+, Composer, Node.js, and MySQL. Point the web server document root at `public/`.
|
|
|
|
```sh
|
|
composer install
|
|
npm install
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
```
|
|
|
|
On Windows PowerShell, use `Copy-Item .env.example .env` in place of `cp .env.example .env`.
|
|
|
|
Set `DB_*` in `.env` to your MySQL database, then run:
|
|
|
|
```sh
|
|
php artisan migrate
|
|
php artisan app:create-admin your-username you@example.com
|
|
npm run build
|
|
php artisan serve
|
|
```
|
|
|
|
The admin command prompts for a password. Never pass it on the command line. For local front-end development, use `npm run dev` alongside `php artisan serve`.
|
|
|
|
The migrations use the legacy table and column names. If you point the app at the existing HickLab3D database, back it up first. The migrations skip tables already present and create Laravel's session, cache, and job tables. Existing schema variations have not been verified against a database dump. Do not run `migrate:fresh` on a database with production data.
|
|
|
|
## Integrations
|
|
|
|
- Enter Etsy, Parcel2Go, BamBuddy, and dryer connection details on the admin Settings page. Saved values are encrypted in the database and take precedence over matching `.env` values.
|
|
- Existing `P2G_*`, `BAMBUDDY_*`, `DRYER_*`, and `ETSY_*` environment values remain available as fallbacks. Save each integration on the Settings page to import those values into the database.
|
|
- Connect the Etsy shop with OAuth after saving its app credentials. The browser talks to authenticated Laravel routes for dryer status and controls.
|
|
- Runtime Etsy credentials remain Settings-page rows / `ETSY_*` env (optional aliases: `HL3D_ETSY_KEYSTRING`, `HL3D_ETSY_SECRET`). Never put tokens in MCP config.
|
|
|
|
## Etsy MCP
|
|
|
|
First-party stdio MCP for HL3D agents. It uses the stored HickLab3D shop connection — agents must not start a new OAuth dance.
|
|
|
|
```sh
|
|
php artisan etsy:mcp
|
|
```
|
|
|
|
Register the local `.mcp.json` only where PHP is installed and the working directory is this app. On the Hermes host, use the existing web container instead (after deployment):
|
|
|
|
```sh
|
|
hermes -p hl3d_teamlead mcp add etsy --command ssh --args -T H-NODE-05 'docker exec -i -u www-data -w /var/www/HickLab3D nginx-ui-php php artisan etsy:mcp --no-ansi'
|
|
```
|
|
|
|
This uses the managed live environment without placing credentials in MCP config and does not require host PHP. Configure positive tool allow-lists through supported `hermes config set` commands before exposing tools to agents: teamlead/designer should get read/status tools only; marketing may additionally create drafts. Do not expose publishing, shipment or inventory-write tools without separately authorising those operations. Disable MCP sampling for this server. Start a fresh profile session or reload MCP after configuration.
|
|
|
|
An admin must reconnect Etsy in the dashboard if status reports unknown or missing scopes (`listings_r listings_w transactions_r transactions_w shops_r`). Never request operator passwords or MFA codes. New listings are drafts; `confirm=true` is a technical publish guard, not operator authorisation. Publishing, activating, renewing or repricing live listings, inventory changes and shipping still require explicit approval for the specific action in the current conversation.
|
|
|
|
## Artisan scheduler
|
|
|
|
The Settings page lets admins tune registered jobs or run them immediately. Defaults: `integrations:refresh` and `alerts:scan` every 30 seconds, `etsy:sync` every 15 minutes, and `etsy:refresh-token` checks every five minutes. Etsy is no longer force-refreshed by the bundled integration job. The refresh check rotates only within ten minutes of expiry; database row locking and a fresh read serialise rotating-token use across MCP, HTTP and scheduler processes. Lowering the token-check cadence or disabling it can leave an idle access token expired.
|
|
|
|
Settings are atomically replaced under a shared file lock at `storage/app/dashboard-schedules.json`. Preserve storage and the Infisical-managed `.env` during deployments. Only H-NODE-05 owns the systemd scheduler timer; its container working directory must be `/var/www/HickLab3D`, matching the actual vhost and CI target. Subminute tasks keep `schedule:run` alive until the end of the minute, so do not install a duplicate cron or scheduler elsewhere.
|
|
|
|
For local tests in the existing serviceengineering toolchain image, explicitly set `APP_ENV=testing`: the image exports `APP_ENV=local`, which otherwise wins over PHPUnit XML and correctly activates real CSRF enforcement. Never disable production CSRF to repair that test-environment mismatch.
|
|
|
|
Etsy Open API v3 has no conversation inbox (`conversations_*` scopes do not exist). Receipt notes are exposed; sending a buyer-inbox reply is not.
|
|
|
|
## Verification
|
|
|
|
```sh
|
|
php artisan test --compact
|
|
npm run build
|
|
```
|
|
|
|
The test suite uses an in-memory SQLite database. MySQL and the external services need environment-specific smoke checks with your credentials and devices.
|