Implement modular filament scale and NFC UID management system

[Copilot]

Overview

Builds a Docker-deployable system for tracking 3D printing filament spools using NFC tag UIDs and weight measurements. Replaces legacy Filaman setup while preserving ESP32 scale hardware compatibility.

Core Architecture

Database-centric design: NFC tag UID as primary key, no writes to tags by default. All spool state maintained in local database with optional Spoolman synchronization.

• Models: 7 tables covering devices, tags, spool state/metadata, printer bindings, and weight history
• Dual database support: PostgreSQL for production, SQLite for quick deployment
• Service layer: Encapsulates business logic for weight processing, tare calculation, and external sync

Key Endpoints

POST /api/v1/readings           # Process weight reading, auto-calculate net weight
POST /api/v1/tags/{uid}/tare    # Set tare weight for empty spool
POST /api/v1/tags/{uid}/assign  # Map tag to Spoolman spool ID
POST /api/v1/sync/spoolman/pull # Sync filament metadata
POST /api/v1/sync/spoolman/push/{uid} # Push weight updates

Weight calculation: net_weight = gross_weight - tare_weight with automatic Spoolman sync when enabled.

Integration Points

Spoolman: Bidirectional sync with configurable auto-push (PUSH_REMAINING_TO_SPOOLMAN). Local database wins for weight/UID mapping, Spoolman wins for filament metadata.

OpenSpool: Payload generation only, feature-flagged (WRITE_MODE=false by default). Never auto-writes to NFC tags.

ESP32 scales: Simple JSON POST to /api/v1/readings/ with device_id, uid, and gross_weight_g.

Deployment

• Multi-arch Docker (amd64/arm64) via GitHub Actions
• Production: PostgreSQL with docker-compose.dev.yml
• Quick start: SQLite with docker-compose.yml
• Target platforms: Ugreen NAS 8800DPX, Raspberry Pi

Configuration

Environment-driven with sensible defaults:

• DATABASE_URL - Connection string (defaults to SQLite)
• SPOOLMAN_URL - External Spoolman instance
• WRITE_MODE=false - Block NFC writes unless explicitly enabled
• PUSH_REMAINING_TO_SPOOLMAN=true - Auto-sync weights

Security

Updated dependencies to resolve vulnerabilities:

• fastapi==0.109.1 (ReDoS fix)
• python-multipart==0.0.22 (arbitrary file write, DoS, ReDoS fixes)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.