Lab8DATAPROCESSOR/context.md

# Project Context

This file captures the current integration state without storing API tokens, passwords, or private credentials.

## Repository

- Remote repository: `https://git.tcom.space/tcom/Lab8DATAPROCESSOR.git`
- Server checkout path: `C:\Users\tcom\Lab8DATAPROCESSOR`
- Service container: `bambuddy-inventree-sync`
- Host port: `8088`
- Container port: `8080`

## Systems

- Bambuddy API base: `http://192.168.1.5:8000/api/v1`
- InvenTree base: `http://192.168.0.3:1337`
- Real API keys and tokens are stored only in `.env`, which is ignored by git.

## Printed Parts Sync

Printed parts sync is already implemented and tested.

- Bambuddy successful Archives create/reuse InvenTree `Part` records.
- Each successful archive creates one InvenTree `StockItem`.
- Duplicate protection uses SQLite and `StockItem.batch = bambuddy-<archive_id>`.
- Printed parts category: `3D_PRINT/BAMBUDY`, ID `26`.
- Printed parts stock location: `PRODUCTION/PRINTED-PART`, ID `98`.
- Part parameters synced:
  - `Weight`
  - `PrintTime`
- Bambuddy archive thumbnails sync to InvenTree `Part.image`.
- Bambuddy archive external link points to the InvenTree Part page.
- Failed, stopped, running, or still-printing archives are skipped when `SYNC_SUCCESS_ONLY=true`.

## Filament Tracking

InvenTree is the source of truth for spool identity, spool location, and remaining stock.

Core rule:

```text
InvenTree StockItem.batch == Bambuddy Spool.tag_uid
```

Configured InvenTree IDs:

| Purpose | ID |
| --- | --- |
| Filament part category | `19` |
| Filament storage root | `85` |
| Loaded-in-printers root | `72` |
| B1 stock location | `93` |
| B2 stock location | `94` |
| B3 stock location | `95` |
| B4 stock location | `96` |

Current Bambuddy printer IDs discovered from API:

| Printer | Bambuddy printer ID |
| --- | --- |
| B1 | `5` |
| B2 | `2` |
| B3 | `3` |
| B4 | `4` |

Printer IDs are auto-detected from Bambuddy printer names unless `FILAMENT_PRINTER_ID_MAP` is set.

## Current Filament State

As of the last tested state:

- InvenTree filament stock items: `28`
- Bambuddy spools: `28`
- Matched batch codes: `28`
- Bambuddy assignments: `3`
- Assigned batches:
  - B1 tray `0`: batch `1010`
  - B1 tray `1`: batch `1060`
  - B1 tray `2`: batch `1061`
- B2 and B3 assignments were removed after their spools were moved back to InvenTree `Filament_Storage`.
- `stale_assignments` was empty after cleanup.
- Bambuddy usage records were still `0` at the last check.

## Filament Behavior

When a stock item is moved in InvenTree:

- Move a spool into location `93`, `94`, `95`, or `96`: the service creates a Bambuddy assignment for B1, B2, B3, or B4.
- Move a spool from a printer location back to storage: the service removes the matching Bambuddy assignment.
- If Bambuddy has an assignment that does not match InvenTree printer locations, it appears in `stale_assignments` and `/sync/filament/assignments?dry_run=true` shows it in `would_delete`.
- `FILAMENT_UNASSIGN_MISSING_ASSIGNMENTS=true` enables this cleanup.
- `FILAMENT_RETURN_UNASSIGNED_TO_STORAGE=false` is intentionally kept off; InvenTree location changes are the source of truth.

The service does not infer physical spool presence from the Bambuddy dashboard. The dashboard can show generic filament loaded by the printer firmware. The integration uses InvenTree location and Bambuddy API assignments.

## Key Endpoints

Health and validation:

```powershell
curl.exe http://localhost:8088/health
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/validate
```

Status:

```powershell
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/sync/status
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/filament/status
```

Archive sync:

```powershell
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/backfill?max_archives=1"
curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/backfill
curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/archive/ARCHIVE_ID
```

Filament sync:

```powershell
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/spools?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/assignments?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/locations?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/usage?dry_run=true"
```

Use `dry_run=false` only after the dry-run output has been checked.

## After Testing

Keep `FILAMENT_DRY_RUN=true` until:

- `/filament/status` has no unexpected `missing_in_bambuddy`, `missing_in_inventree`, or `stale_assignments`.
- `/sync/filament/assignments?dry_run=true` shows expected `would_create` and `would_delete`.
- After a real successful print, `/sync/filament/usage?dry_run=true` shows the expected `would_remove` batch and grams.

Then production mode can be enabled:

```env
FILAMENT_TRACKING_ENABLED=true
FILAMENT_DRY_RUN=false
FILAMENT_SYNC_SPOOLS=true
FILAMENT_SYNC_ASSIGNMENTS=true
FILAMENT_UNASSIGN_MISSING_ASSIGNMENTS=true
FILAMENT_SYNC_LOCATIONS=true
FILAMENT_SYNC_USAGE=true
FILAMENT_RETURN_UNASSIGNED_TO_STORAGE=false
POLL_INTERVAL_SECONDS=300
SYNC_ON_STARTUP=false
```

Restart after `.env` changes:

```powershell
docker compose up -d
```

## Docker Operations

Update deployed service:

```powershell
cd C:\Users\tcom\Lab8DATAPROCESSOR
git pull
docker compose up -d --build
```

Logs:

```powershell
docker compose logs --tail=100
```

Backup:

- Back up `.env` separately.
- Back up `data/sync.sqlite3`.
- Do not commit `.env`, tokens, passwords, or database files.