nextcloud-collabora-nodered/docs/AGENT-MANUAL.md

# Assistentmanual — Nextcloud Office + Collabora Node-RED

**Version 1.0 — 22 augusti 2026**

Gäller sidecaren `nextcloud-collabora-nodered` mot Nextcloud på `cloud.hannesahlin.se` och Collabora CODE 26.04.x (container `code`, `127.0.0.1:9980`). Odds-scraper ignoreras.

Du är en **flödesagent**. Du skapar och modifierar Node-RED-flöden, inte LibreOffice-makron i webbläsaren. All fil-I/O går via Nextcloud WebDAV eller OCS. All dokumentmotor går via CODE REST.

---

## 1. Uppdrag och gränser

1. Använd **app-lösenord** i `nc-collab-config`. Aldrig vanligt kontolösen.
2. Skriv **inte över original**. Standardmål: `/Dokument/OfficeOut/`.
3. `postMessage`-API och `CallPythonScript` är iframe/webbläsare. **Inte Node-RED.**
4. WOPI PutFile är CODE:s jobb mot Nextcloud. Agenten använder **WebDAV PUT**.
5. Exponera inte port 9980 utanför loopback.
6. Rör inte odds-scraper eller Gitea-databaslösen i flöden.

---

## 2. Miljö

| Nyckel | Värde |
|--------|-------|
| Nextcloud | `https://cloud.hannesahlin.se` (host 192.168.1.26) |
| CODE | container `code`, `127.0.0.1:9980`, aliasgroup `https://cloud.hannesahlin.se:443` |
| Befintlig Node-RED | `nextcloud-node-red` `:1880` — **Collabora-noder integreras här** |
| Sidecar :1881 | Endast med `INSTALL_MODE=sidecar` (ej standard) |
| Intern CODE-URL från sidecar | `http://172.17.0.2:9980` (Docker bridge, container `code`) |
| Auth | Basic + Nextcloud app-lösenord, header `OCS-APIRequest: true` |

Se [INFRASTRUCTURE.md](INFRASTRUCTURE.md) för container- och nätverkskartor.

---

## 3. Kartan Nextcloud → Collabora

| Nextcloud | Collabora-yta | Nod |
|-----------|-----------------|-----|
| WebDAV GET fil | input till convert/extract/transform | convert, extract, transform, bridge |
| WebDAV PUT | spara PDF/DOCX/PNG | samma + `destNcPath` |
| files convert OCS | samma motor via richdocuments | nc-office `files:convert` |
| richdocuments mallar | convert-to `template=` eller NC create-from-template | nc-office `templates:*` |
| template fields | content controls | extractFields / fillFields / transform |
| file versions | compare= på convert-to | bridge `compareVersionsPdf` |
| fileId + direct token | WOPISrc + editor iframe | nc-office `document:direct`, wopi `buildEditor` |
| assets API | linking / insert graphic URL | assets:create + klient postMessage |
| shares | public edit URL | document:public |
| preview | convert-to png | ncFileToPng |
| HTML/MD | convert-to office | htmlToOffice |

Talk, Tables, Mail, Collectives ska **konsumera resultatet** (dela PDF, bifoga, lägg i collective) — de ersätter inte WOPI-host.

---

## 4. Noder och msg-kontrakt

### 4.1 nc-collab-config

En instans per miljö. Fält: `nextcloudUrl`, `collaboraUrl`, ev. `collaboraPublicUrl`, `username`, app-lösen, `verifyTls` (false i labb-VM tills certkedjan är ren).

### 4.2 Gemensamma msg-fält

| Fält | Betydelse |
|------|-----------|
| `ncPath` | Sökväg i användarens filrot, t.ex. `/Mallar/avtal.docx` |
| `fileId` | Numeriskt Nextcloud-fileid |
| `payload` | Buffer eller text om källan inte ligger i NC |
| `format` | pdf \| png \| docx \| odt \| html \| txt \| xlsx \| pptx … |
| `destNcPath` / `destFolder` / `destName` | Var resultatet skrivs |
| `transform` / `fields` | JSON för struktur-API eller mallfält |
| `templateNcPath` / `compareNcPath` | Extra filer till convert-to |
| `operation` | Överstyr dropdown |
| `statusCode` / `error` / `filename` / `contentType` | Utdata |

### 4.3 Operationskatalog

| Nod.operation | När |
|---------------|-----|
| bridge.ncFileToPdf/Png/Html | Standardkonvertering NC-fil → NC-fil |
| bridge.htmlToOffice | Agentgenererad HTML/MD → office |
| bridge.fillTemplateSave | Fyll content controls/fält och spara kopia |
| bridge.compareVersionsPdf | Ny + gammal fil → PDF med ändringar |
| bridge.extractToPayload | Struktur-JSON till nästa nod |
| bridge.createAssetLink | Engångs-URL för insert i öppet dokument |
| nc-office.templates:list\|create | Office-mallar i richdocuments |
| nc-office.template:extractFields\|fillFields | Föredra när fileId finns |
| nc-office.document:direct\|public | Engångs redigerings-URL |
| nc-office.files:convert | Konvertera via Nextcloud (CODE bakom) |
| convert + extract + transform | Låg nivå när bridge inte räcker |
| wopi.discovery\|capabilities | Hälsokoll och mime→urlsrc |
| wopi.buildEditor | Bygg editorUrl om token redan finns |
| wopi.checkFileInfo\|getFile | Endast felsökning av WOPI-host |

---

## 5. Recept

### A. NC-fil till PDF

```
inject {ncPath} → collabora-bridge ncFileToPdf → ev. filesharing createShare (OCS :1880)
```

Kontrollera `destNcPath` i svaret.

### B. Avtalsmall

```
extractFields eller extract contentcontrol
  → mappa data till fields/transform
  → fillTemplateSave eller template:fillFields med destination
  → valfritt ncFileToPdf
  → document:direct för mänsklig granskning
```

### C. Versionsdiff

```
{ncPath: ny, compareNcPath: gammal} → compareVersionsPdf
  → skicka PDF via Talk eller Mail-noden i OCS-paketet (:1880)
```

### D. Generera dokument

HTML i `payload` → `htmlToOffice` format docx eller pdf. Använd mall via convert `templateNcPath` om typografi måste följa husmall.

---

## 6. Vad du inte ska bygga

- En Node-RED-nod som postMessage:ar in i Collabora-iframe (kräver webbsida utanför iframen).
- Dynamisk Python mot share/Scripts/python (kräver paket på CODE och omstart).
- Andra CODE-container i compose (`code` körs redan med aliasgroup1).
- Portkrock på 1880 mot nextcloud-node-red.

---

## 7. Felsökning

| Symptom | Orsak | Åtgärd |
|---------|-------|--------|
| ECONNREFUSED :9980 | Sidecar inte på bridge / fel IP | Använd `http://172.17.0.2:9980`, kontrollera `docker network inspect bridge` |
| Tomt convert-svar | CODE storage / fel URL | Anropa intern 9980, inte publik host |
| WebDAV 401 | App-lösen / user | Nytt app-lösen, samma uid som sökvägen |
| WebDAV 404 | Fel sökväg | Leading slash, rätt folder, URL-encode segment |
| extract tomt | Filter / capability | capabilities, prova documentproperties |
| WOPI 401/proof | Sessionstoken | Lämna WOPI. Använd WebDAV. |
| TLS-fel mot NC | Cert i containern | verifyTls=false |

---

## 8. Acceptanskriterier för ett flöde

- `capabilities` mot CODE returnerar JSON.
- En känd testdokumentsökväg konverteras till PDF under `/Dokument/OfficeOut/`.
- Originalfilen är oförändrad.
- Fel hamnar i `msg.error` och nodstatus röd, flödet kraschar inte tyst.
- Inga hemligheter i debug-payload till Talk.

---

## 9. Installation (Ubuntu)

```bash
# /home/ncadmin/nextcloud-collabora-nodered
chmod +x install.sh
./install.sh
# UI: http://192.168.1.26:1881
```

Överföring från Windows:

```bash
./package.sh   # skapar artifacts/nextcloud-collabora-nodered-1.0.0.tar.gz
scp artifacts/*.tar.gz ncadmin@192.168.1.26:/home/ncadmin/
# på servern:
tar -xzf nextcloud-collabora-nodered-1.0.0.tar.gz -C nextcloud-collabora-nodered
cd nextcloud-collabora-nodered && ./install.sh
```

---

## 10. Arkitektur

```
Befintligt (orört):
  nextcloud-ocs 16 noder + nextcloud-config
  container nextcloud-node-red :1880
  CODE "code" :127.0.0.1:9980

Ny yta (det här paketet):
  nc-collab-config
  nc-office          richdocuments OCS
  collabora-convert  /cool/convert-to
  collabora-extract  /cool/extract-document-structure
  collabora-transform /cool/transform-document-structure
  collabora-wopi     discovery, capabilities, editor-URL
  collabora-bridge   agent-pipelines
```

---

*cloud.hannesahlin.se · nextcloud-collabora-nodered v1.0*