diff --git a/README.md b/README.md index 2d08bfe..c667856 100644 --- a/README.md +++ b/README.md @@ -436,6 +436,64 @@ Then rebuild/restart: docker compose up -d --build ``` +## After Testing / Production Cutover + +Keep filament sync in dry-run until all three checks are clean: + +```powershell +curl.exe -H "X-Service-Token: change-me" http://localhost:8088/filament/status +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/usage?dry_run=true" +``` + +Expected assignment check: + +```text +would_create: [] +would_delete: [] +skipped: 0 +failed: 0 +``` + +Expected usage check before any print has finished: + +```text +seen: 0 +would_remove: [] +failed: 0 +``` + +After a successful print, run usage dry-run again. Only switch to real automatic filament sync when `would_remove` contains the expected batch code and grams. + +Recommended final production settings: + +```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 +``` + +Apply the config: + +```powershell +docker compose up -d +``` + +Production operating rule: + +- Move a spool to InvenTree location `93`, `94`, `95`, or `96` to mark it loaded in B1, B2, B3, or B4. +- Move a spool back to InvenTree `Filament_Storage` to mark it unloaded. +- The sync service creates or removes Bambuddy assignments from those InvenTree locations. +- InvenTree remains the source of truth for spool location and remaining grams. +- Bambuddy usage history is used only for subtracting printed grams after successful prints. + For near-real-time syncing, also configure a Bambuddy webhook: ```text diff --git a/context.md b/context.md new file mode 100644 index 0000000..ddd8b52 --- /dev/null +++ b/context.md @@ -0,0 +1,180 @@ +# 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-`. +- 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.