# Plussys — API, MCP i proizvodna sljedivost

CNC obrada kamena (Zagreb / Dugo Selo). Dimenzije u **milimetrima**, cijene u **EUR**.
Maksimalna dimenzija ploče: **3200 mm**.

- HTML: https://plussys.qtech.hr/docs
- Markdown: https://plussys.qtech.hr/docs.md
- MCP: POST https://plussys.qtech.hr/mcp
- OpenAPI 3.1: https://plussys.qtech.hr/openapi.json
- Auth: https://plussys.qtech.hr/auth.md

## Tri sloja

| Sloj | Tko | Endpoint | Stanje |
|------|-----|----------|--------|
| MCP | AI agenti (Cursor, Claude, ChatGPT) | `POST /mcp` | U produkciji — katalog, narudžbe, QR koraci, lager, čitanje strojeva |
| REST | Web, telefon radnika, OAuth agenti | `/api/*` | U produkciji — CAM, MES, lager, foto, trag |
| Stroj (Raspberry) | Agent na pili / waterjetu | `/api/machine/*` | **Plan** — token po stroju, G-kod, heartbeat, kamera |

MCP je uredski/AI sloj. Raspberry **ne** razgovara MCP-om. Na hali se koristi REST (sesija radnika ili token stroja).

## Tok proizvodnje

```
Kupac / agent
  konfigurator  |  MCP create_order  |  POST /api/narudzbe
        │
        ▼
Narudžba + geometrija (mm) + QR  https://plussys.qtech.hr/t/{broj}
        │
        ▼
Admin CAM
  POST /api/cam/{id}/generate  { stroj_id? }
  → R2  narudzbe/{id}/{broj}.nc  i  .dxf
  → stroj_poslovi (red na pili)
  → trag: CAM · broj → stroj (m reza, min)
        │
        ▼
Radnik skenira QR na naljepnici
  POST /api/narudzbe/{id}/koraci
  MES: rezanje zabranjeno bez gcode_key
  QA NCR pali ANDON; pakiranje treba prošlu QA
        │
        ▼
[PLAN] Raspberry na stroju
  GET  /api/machine/job      sljedeći posao + URL G-koda
  POST /api/machine/job/{id}/start | finish
  POST /api/machine/heartbeat
  POST /api/machine/camera     video vezan na narudzba_id
        │
        ▼
Sljedivost: trag + koraci + lager + foto (+ plan: G-kod na pili, sati, video)
MCP track_order / get_machines čitaju iste podatke
```

## Što je pokriveno danas

- Nacrt (geometrija mm) → CAM G-kod/DXF (G54, kerf, lead-in) → red na stroju
- QR na radnom listu / naljepnici → javno `/t/{broj}`
- Koraci: zaprimljeno → materijal_rezerviran → rezanje → obrada_rubova → busenje_otvora → qa_kontrola → pakiranje → isporuceno
- Lager: zaprimi / rezerviraj / premjesti / potroši (ostatak)
- Foto na narudžbi (`narudzba_foto`, stills)
- Timeline (`trag`) — status, CAM, ANDON, lager

## Što još nije

- Raspberry agent, token stroja, DNC / drip G-koda na CNC
- Live kamera i snimka vezana na narudžbu (`strojevi.kamera_url` postoji; UI: Uskoro)
- MCP alati za generiranje CAM-a ili slanje .nc na pilu
- Heartbeat stroja, sati rada po poslu, „program stvarno učitan”

---

## MCP

Transport: streamable HTTP, stateless, JSON-RPC 2.0, protokol **2025-06-18**.
Beta: MCP je otvoren bez autentikacije. REST zahtijeva sesiju ili Bearer token.

```
POST https://plussys.qtech.hr/mcp
GET  https://plussys.qtech.hr/mcp     → popis alata
```

### Alati

| Alat | Argumenti | Opis |
|------|-----------|------|
| list_materials | kategorija? | Katalog + slobodan lager |
| list_orders | status? | Zadnje narudžbe |
| get_order | broj | Detalj + geometrija |
| track_order | broj | Koraci, lager, track_url |
| create_order | proizvod_tip, materijal_id, sirina_mm, dubina_mm, debljina_mm?, napomena? | Pravokutna ploča |
| add_production_step | broj, korak, lokacija?, napomena?, ploca_id? | Kao sken QR-a (MCP Agent) |
| get_inventory | status? | Ploče na lageru |
| receive_slab | materijal_id, mm, lokacija? | Zaprimi ploču |
| reserve_slab | ploca_id, broj | Rezervacija |
| release_slab | ploca_id | Vrati na lager |
| move_slab | ploca_id, lokacija | Premještaj |
| consume_slab | ploca_id, ostatak_mm? | Potroši; opcionalni ostatak |
| get_machines | — | Strojevi + poslovi (samo čitanje) |

Koraci za `add_production_step`: zaprimljeno, materijal_rezerviran, rezanje, obrada_rubova, busenje_otvora, qa_kontrola, pakiranje, isporuceno.

MCP **ne** generira G-kod i **ne** pokreće stroj. Za to je REST (admin CAM) i planirani machine API.

### Povezivanje

Cursor `.cursor/mcp.json`:

```json
{ "mcpServers": { "plussys": { "url": "https://plussys.qtech.hr/mcp" } } }
```

Claude Code: `claude mcp add --transport http plussys https://plussys.qtech.hr/mcp`

---

## REST API

Baza: `https://plussys.qtech.hr`. Cookie `plussys_session` (web) ili `Authorization: Bearer <token>` (OAuth).
Uloge: **admin ≥ radnik ≥ kupac**.

Token:

```
POST https://plussys.qtech.hr/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=<email>&password=<lozinka>
```

Odgovor: `{ access_token, token_type: Bearer, expires_in: 1209600, scope: cam }`.

### Javno (bez prijave)

| Metoda | Put | Opis |
|--------|-----|------|
| GET | /api/health | Health |
| GET | /api/katalog | Materijali €/m² |
| GET | /api/katalog/{id} | Jedan materijal |
| GET | /api/track/{broj} | QR praćenje |
| GET | /api/foto/{fotoId} | Javna slika s narudžbe |
| POST | /api/auth/register | Registracija |
| POST | /api/auth/login | Email/lozinka |
| POST | /api/auth/sms/start \| verify \| complete | SMS prijava |
| POST | /api/oauth/token | Bearer za agente |

### Prijavljeni (kupac+)

| Metoda | Put | Opis |
|--------|-----|------|
| GET/PATCH | /api/auth/me | Profil |
| GET/POST | /api/narudzbe | Moje narudžbe |
| GET/PATCH | /api/narudzbe/{id} | Detalj; PATCH geometrije briše zastarjeli CAM |
| GET | /api/narudzbe/{id}/trag | Timeline |
| GET | /api/narudzbe/{id}/koraci | Koraci proizvodnje |
| GET/POST/DELETE | /api/narudzbe/{id}/foto | Stills na narudžbi |
| GET | /api/racuni | Računi |
| POST | /api/ai/geometrija \| skica \| render | Pomoć za nacrt |
| GET/POST | /api/live | Chat (Durable Object) |
| POST | /api/live/file | Privitak chata |

### Radnik (MES + lager)

| Metoda | Put | Opis |
|--------|-----|------|
| POST | /api/narudzbe/{id}/koraci | Log koraka (QR). Body: korak, lokacija?, napomena?, ishod?, ploca_id(s)? |
| GET | /api/admin/stanice | Kanban stanica |
| GET | /api/admin/lager | Lager |
| POST | /api/admin/lager | Zaprimi ploču |
| POST | /api/lager/{id}/rezerviraj \| oslobodi \| u-obradi \| potrosi \| premjesti | Stanje ploče |
| GET | /api/lager/lokacije | Lokacije |
| GET | /api/narudzbe/{id}/lager-kandidati | Ploče koje odgovaraju narudžbi |

MES pravila: **rezanje** zahtijeva `gcode_key`; **pakiranje/isporučeno** zahtijeva QA bez NCR; ANDON blokira liniju.

### Admin (CAM, strojevi, ured)

| Metoda | Put | Opis |
|--------|-----|------|
| POST | /api/cam/{id}/generate | G-kod + DXF u R2, red na stroju. Body: `{ stroj_id? }`. Odgovor: stats (cut_m, min_proc, F, kerf, dialect), queued |
| GET | /api/cam/{id}/gcode | Preuzmi .nc |
| GET | /api/cam/{id}/dxf | Preuzmi .dxf (lazy generate ako fali) |
| GET | /api/admin/strojevi | Strojevi + stroj_poslovi |
| GET | /api/admin/narudzbe | Sve narudžbe |
| GET/PUT | /api/admin/post-procesor | Kerf, feed, dijalekt |
| POST | /api/admin/narudzbe/{id}/potvrdi-nacrt | Zaključaj nacrt |
| POST | /api/admin/narudzbe/{id}/racun \| uplata | Financije |
| POST | /api/admin/narudzbe/{id}/andon | ANDON |
| GET/PATCH | /api/admin/users | Korisnici |
| GET | /api/admin/financije | Pregled |

CAM: G54 origin na min XY crteža; kerf inset vanjski obris, outset rupe; lead-in 8 mm. Dijalekti: iso, waterjet (bez vretena), bridge. Promjena geometrije/materijala/debljine briše `gcode_key`/`dxf_key` — treba ponovno generirati.

---

## Plan — Raspberry / stroj API

Nije implementirano. Ciljni ugovor (token po `stroj_id`, ne MCP):

| Metoda | Put | Opis |
|--------|-----|------|
| POST | /api/machine/heartbeat | status, sati_rada |
| GET | /api/machine/job | sljedeći ceka/u_tijeku posao + signed URL .nc |
| POST | /api/machine/job/{id}/start | veže ciklus, stroj u_radu |
| POST | /api/machine/job/{id}/finish | gotovo + optional consume_slab |
| POST | /api/machine/camera | video/chunk → R2 `narudzbe/{id}/cam/` + foto/trag |

Tok na hali: radnik skenira QR → korak + lokacija = taj stroj → Pi vuče G-kod → start → kamera snima na tu narudžbu → finish.

---

## Discovery

- https://plussys.qtech.hr/llms.txt
- https://plussys.qtech.hr/openapi.json
- https://plussys.qtech.hr/auth.md
- https://plussys.qtech.hr/.well-known/api-catalog
- https://plussys.qtech.hr/.well-known/mcp/server-card.json
- https://plussys.qtech.hr/.well-known/agent-skills/plussys-cam/SKILL.md
- https://plussys.qtech.hr/.well-known/ai-catalog.json
- https://plussys.qtech.hr/.well-known/oauth-authorization-server

Naslovnica: `Accept: text/markdown`. WebMCP: `navigator.modelContext`.

Kontakt: plussys@qtech.hr