237 lines
9.2 KiB
Markdown
237 lines
9.2 KiB
Markdown
# Plast Track MVP - Codex Prompt & UI Instructions
|
|
|
|
## 1. Codex Task Prompt
|
|
|
|
Use this as the top-level prompt when opening a Codex session on this repository.
|
|
|
|
```text
|
|
You are working on Plast Track MVP - a lightweight MES/IoT dashboard for
|
|
supervising multi-brand injection molding machines. The stack is:
|
|
|
|
Backend FastAPI + PostgreSQL + Mosquitto MQTT (Python)
|
|
Frontend React + TypeScript (Vite, port 5173)
|
|
Infra Docker Compose
|
|
|
|
Repository layout:
|
|
/backend FastAPI app, MQTT consumer, OEE logic, WebSocket
|
|
/frontend React + TypeScript operator dashboard
|
|
/edge-simulator Publishes simulated MQTT machine events
|
|
/database init.sql + seed.sql
|
|
/mqtt mosquitto.conf
|
|
docker-compose.yml
|
|
|
|
Key rules:
|
|
- Never send commands back to the machines. Acquisition is read-only / passive.
|
|
- All timestamps are UTC ISO-8601.
|
|
- OEE = Availability x Performance x Quality (see README for exact formulas).
|
|
- The WebSocket at /ws/dashboard pushes refresh notifications; the UI then
|
|
refetches via REST. Do not push full payloads over the socket.
|
|
- Machine status values: production | arret_non_qualifie | arret_qualifie |
|
|
reglage | hors_planning
|
|
|
|
Before writing code:
|
|
1. Read the relevant backend route or model file first.
|
|
2. Confirm the PostgreSQL schema in /database/init.sql for any DB changes.
|
|
3. Run `pytest` in /backend and `npm run build` in /frontend to verify changes.
|
|
4. Keep backend business logic inside service modules, not route handlers.
|
|
5. For frontend changes, follow the UI instructions below.
|
|
```
|
|
|
|
## 2. UI Instructions for Codex
|
|
|
|
Paste these instructions into any Codex task that touches the frontend.
|
|
|
|
### 2.1 Design System - Non-Negotiable Tokens
|
|
|
|
All visual decisions must derive from these tokens. Do not introduce new color
|
|
hex values, font families, or border-radius values without updating this table.
|
|
|
|
#### Colors
|
|
|
|
| Token name | Hex | Role |
|
|
|------------------------|-----------|-----------------------------------------|
|
|
| `--bg-base` | `#F5F7FA` | Page background |
|
|
| `--bg-panel` | `#FFFFFF` | Panel and card surface |
|
|
| `--bg-panel-alt` | derived | Alternate very light gray surface |
|
|
| `--border` | derived | Anthracite tint border |
|
|
| `--teal-900` | `#0A2F5A` | Primary industrial blue structure |
|
|
| `--teal-700` | derived | Darker industrial blue |
|
|
| `--teal-100` | derived | Industrial blue tint |
|
|
| `--accent` | `#F28C28` | Technical orange accent and CTA |
|
|
| `--accent-light` | derived | Technical orange tint |
|
|
| `--text-primary` | `#2B2B2B` | Anthracite body text |
|
|
| `--text-secondary` | derived | Anthracite metadata tint |
|
|
| `--text-on-dark` | `#FFFFFF` | Text on dark surfaces |
|
|
| `--status-production` | `#0A2F5A` | Industrial blue, machine running |
|
|
| `--status-unqualified` | `#F28C28` | Technical orange, unqualified stop |
|
|
| `--status-qualified` | `#2B2B2B` | Anthracite, qualified stop |
|
|
| `--status-setup` | derived | Blue/orange mix, setup / reglage |
|
|
| `--status-off-plan` | derived | Anthracite tint, outside planning |
|
|
|
|
#### Typography
|
|
|
|
| Role | Font family | Weight | Usage |
|
|
|----------------|-------------------|--------|----------------------------------------|
|
|
| Display / KPI | `Space Grotesk` | 600 | Headings, large numbers, machine codes |
|
|
| Body / UI | `Instrument Sans` | 400 | Labels, descriptions, form fields |
|
|
| Body emphasis | `Instrument Sans` | 600 | Sub-headings, table headers |
|
|
| Caption / meta | `Instrument Sans` | 400 | Small labels, timestamps, hints |
|
|
|
|
Type scale:
|
|
|
|
```css
|
|
--text-xs: 0.75rem;
|
|
--text-sm: 0.875rem;
|
|
--text-base: 1rem;
|
|
--text-lg: 1.125rem;
|
|
--text-xl: 1.25rem;
|
|
--text-2xl: 1.5rem;
|
|
--text-3xl: 2rem;
|
|
```
|
|
|
|
#### Surfaces
|
|
|
|
```css
|
|
border-radius: 12px;
|
|
box-shadow: 0 1px 3px rgba(10, 47, 90, 0.06), 0 4px 12px rgba(10, 47, 90, 0.04);
|
|
```
|
|
|
|
Selected card:
|
|
|
|
```css
|
|
box-shadow: 0 4px 16px rgba(10, 47, 90, 0.12), 0 0 0 2px var(--accent);
|
|
```
|
|
|
|
Inset surfaces:
|
|
|
|
```css
|
|
background: var(--bg-panel-alt);
|
|
border: 1px solid var(--border);
|
|
border-radius: 6px;
|
|
```
|
|
|
|
### 2.2 Layout Rules
|
|
|
|
The current UI uses a tabbed module workspace, not a fixed action sidebar.
|
|
|
|
```text
|
|
Hero Header
|
|
Summary Ribbon
|
|
Module Tabs
|
|
Current Module Panel
|
|
```
|
|
|
|
Current modules:
|
|
|
|
- `Atelier`: machine cards, filters, sorting, quick actions, fullscreen workshop mode
|
|
- `Machine`: selected machine detail, cycle trend, events, downtime history
|
|
- `TRS`: daily OEE/TRS
|
|
- `OF`: production order creation and management
|
|
- `Arrets`: downtime qualification
|
|
- `Rebuts`: scrap declaration and scrap log
|
|
- `Config`: passive signal and timing configuration
|
|
|
|
Responsive rules:
|
|
|
|
- Desktop: centered workspace, full tab row, split form/list modules where useful.
|
|
- Tablet: tabs wrap, form/list modules stack.
|
|
- Mobile: single column, no horizontal page scroll.
|
|
|
|
### 2.3 Component Conventions
|
|
|
|
#### Machine Card
|
|
|
|
- Card uses `min-height: 180px`.
|
|
- Machine code uses `Space Grotesk 600`, `--text-xl`.
|
|
- Status badge uses tokenized status color and text label.
|
|
- State duration badge shows elapsed time since `status_since`.
|
|
- No active order state must be visually distinct.
|
|
- Quick actions route to OF, Rebuts, or Arrets modules.
|
|
- Selected state uses the elevated `box-shadow`; do not use outline for the selected ring.
|
|
|
|
#### Status Badge
|
|
|
|
Use `<StatusBadge status="production" />`. Always include a text label; color is never the only state indicator.
|
|
|
|
#### KPI Block
|
|
|
|
Use for summary and machine detail metrics:
|
|
|
|
- label: `--text-xs`, uppercase, `--text-secondary`
|
|
- value: `--text-2xl`, `Space Grotesk 600`
|
|
- optional sub-label: `--text-xs`, `--text-secondary`
|
|
|
|
#### Forms
|
|
|
|
- Fields use full width, `border-radius: 6px`, `border: 1px solid var(--border)`, `padding: 8px 12px`.
|
|
- Primary action button uses `var(--accent)`, `border-radius: 8px`, `Space Grotesk 600`.
|
|
- Inline validation appears below the field in `--status-qualified`.
|
|
- API errors appear inside the active module, not as global alerts.
|
|
- Success toasts appear inline and auto-dismiss after 3 seconds.
|
|
|
|
#### Cycle Bar Mini-Chart
|
|
|
|
- Use SVG directly; no third-party charting library.
|
|
- Newest cycle appears on the right.
|
|
- Theoretical cycle is a dashed `--teal-100` reference line.
|
|
- Bars at or below theoretical are green.
|
|
- Bars above theoretical by more than 10% are orange.
|
|
- Tooltip shows exact cycle time in seconds.
|
|
|
|
### 2.4 Interaction Rules
|
|
|
|
| Trigger | Expected behavior |
|
|
|-------------------------|-------------------------------------------------------|
|
|
| Click machine card body | Selects machine and opens Machine module |
|
|
| Click quick OF action | Selects machine and opens OF module |
|
|
| Click quick Rebut | Selects machine and opens Rebuts module |
|
|
| Click quick Arret | Selects machine and opens Arrets module |
|
|
| WebSocket refresh event | Re-fetch dashboard data without unmount flash |
|
|
| Submit downtime qualify | Validate inline, send REST request, refresh on success |
|
|
| Submit scrap | Validate inline, clear form on success |
|
|
| Create production order | Add order; do not auto-start unless user starts it |
|
|
|
|
Data fetching:
|
|
|
|
- REST calls go to `http://localhost:8000/api/...`.
|
|
- WebSocket connects to `ws://localhost:8000/ws/dashboard`.
|
|
- On WS disconnect, show a small reconnecting banner and retry with exponential backoff up to 30 seconds.
|
|
- Do not poll. Refresh is WebSocket-driven.
|
|
|
|
### 2.5 Accessibility Minimums
|
|
|
|
- Interactive elements must be reachable by keyboard.
|
|
- Status colors must have text labels.
|
|
- Touch targets should be at least 44px high.
|
|
- Respect `prefers-reduced-motion`.
|
|
- Body text on panel backgrounds must pass WCAG AA contrast.
|
|
|
|
### 2.6 File Conventions
|
|
|
|
| What | Where |
|
|
|-------------------------------|-----------------------------------------------|
|
|
| Global CSS variables / resets | `frontend/src/styles.css` |
|
|
| Root app layout | `frontend/src/App.tsx` |
|
|
| Machine card component | `frontend/src/components/MachineCard.tsx` |
|
|
| Reusable panel wrapper | `frontend/src/components/Panel.tsx` |
|
|
| New components | `frontend/src/components/<ComponentName>.tsx` |
|
|
| Types | `frontend/src/lib/types.ts` |
|
|
|
|
Rules:
|
|
|
|
- One component per file.
|
|
- No inline styles in TSX.
|
|
- No Tailwind.
|
|
- No UI component library.
|
|
- No charting library for cycle bars.
|
|
- No machine command/control path.
|
|
- No `localStorage` for production state.
|
|
|
|
### 2.7 Suggested Next Tasks
|
|
|
|
1. Add historian-style OEE and scrap reporting endpoints.
|
|
2. Add edge gateway buffering for MQTT outage periods.
|
|
3. Add a real passive gateway adapter specification with example payload mappings.
|
|
4. Add operator and supervisor views when role needs are defined.
|
|
5. Add richer downtime timelines and duration buckets.
|