Debug and inventory

README.md

@@ -1,6 +1,6 @@
 # Dereth Tracker
 
-Dereth Tracker is a real-time telemetry service for the world of Dereth. It collects player data, stores it in a PostgreSQL (TimescaleDB) database for efficient time-series storage, and provides a live map interface along with a sample data generator for testing.
+Dereth Tracker is a real-time telemetry service for the world of Dereth. It collects player data, stores it in a PostgreSQL (TimescaleDB) database for efficient time-series storage, provides a live map interface, and includes a comprehensive inventory management system for tracking and searching character equipment.
 
 ## Table of Contents
 - [Overview](#overview)
@@ -16,20 +16,27 @@ Dereth Tracker is a real-time telemetry service for the world of Dereth. It coll
 
 ## Overview
 
-- This project provides:
+This project provides:
 - A FastAPI backend with endpoints for receiving and querying telemetry data.
 - PostgreSQL/TimescaleDB-based storage for time-series telemetry and per-character stats.
 - A live, interactive map using static HTML, CSS, and JavaScript.
-- A sample data generator script (`generate_data.py`) for simulating telemetry snapshots.
+- A comprehensive inventory management system with search capabilities.
+- Real-time inventory updates via WebSocket when characters log in/out.
 - A sample data generator script (`generate_data.py`) for simulating telemetry snapshots.
 
 ## Features
 
-- **WebSocket /ws/position**: Stream telemetry snapshots (protected by a shared secret).
+- **WebSocket /ws/position**: Stream telemetry snapshots and inventory updates (protected by a shared secret).
 - **GET /live**: Fetch active players seen in the last 30 seconds.
 - **GET /history**: Retrieve historical telemetry data with optional time filtering.
 - **GET /debug**: Health check endpoint.
 - **Live Map**: Interactive map interface with panning, zooming, and sorting.
+- **Inventory Management**: 
+  - Real-time inventory updates via WebSocket on character login/logout
+  - Advanced search across all character inventories
+  - Filter by character, equipment type, material, stats, and more
+  - Sort by any column with live results
+  - Track item properties including spells, armor level, damage ratings
 - **Sample Data Generator**: `generate_data.py` sends telemetry snapshots over WebSocket for testing.
 
 ## Requirements
@@ -218,11 +225,13 @@ For a complete reference of JSON payloads accepted by the backend (over `/ws/pos
   - **Spawn events** (`type`: "spawn")
   - **Chat events** (`type`: "chat")
   - **Rare events** (`type`: "rare")
+  - **Inventory events** (`type`: "inventory")
 
 Notes on payload changes:
   - Spawn events no longer require the `z` coordinate; if omitted, the server defaults it to 0.0.
     Coordinates (`ew`, `ns`, `z`) may be sent as JSON numbers or strings; the backend will coerce them to floats.
   - Telemetry events have removed the `latency_ms` field; please omit it from your payloads.
+  - Inventory events are sent automatically on character login/logout containing complete inventory data.
 
 Each entry shows all required and optional fields, their types, and example values.
 
@@ -253,11 +262,14 @@ Response:
 ## Frontend
 
 - **Live Map**: `static/index.html` – Real-time player positions on a map.
+- **Inventory Search**: `static/inventory.html` – Search and browse character inventories with advanced filtering.
 
 ## Database Schema
 
-This service uses PostgreSQL with the TimescaleDB extension to store telemetry time-series data
-and aggregate character statistics. The primary tables are:
+This service uses PostgreSQL with the TimescaleDB extension to store telemetry time-series data,
+aggregate character statistics, and a separate inventory database for equipment management. 
+
+### Telemetry Database Tables:
 
 - **telemetry_events** (hypertable):
   - `id` (PK, serial)
@@ -297,6 +309,41 @@ and aggregate character statistics. The primary tables are:
   - `timestamp` (timestamptz)
   - `ew`, `ns`, `z` (float)
 
+### Inventory Database Tables:
+
+- **items**:
+  - `id` (PK, serial)
+  - `character_name` (text, indexed)
+  - `item_id` (bigint)
+  - `name` (text)
+  - `object_class` (integer)
+  - `icon`, `value`, `burden` (integer)
+  - `current_wielded_location`, `bonded`, `attuned`, `unique` (various)
+  - `timestamp` (timestamptz)
+
+- **item_combat_stats**:
+  - `item_id` (FK to items.id)
+  - `armor_level`, `max_damage` (integer)
+  - `damage_bonus`, `attack_bonus` (float)
+  - Various defense bonuses
+
+- **item_enhancements**:
+  - `item_id` (FK to items.id)
+  - `material` (varchar)
+  - `item_set` (varchar)
+  - `tinks`, `workmanship` (integer/float)
+
+- **item_spells**:
+  - `item_id` (FK to items.id)
+  - `spell_id` (integer)
+  - `spell_name` (text)
+  - `is_legendary`, `is_epic` (boolean)
+
+- **item_raw_data**:
+  - `item_id` (FK to items.id)
+  - `int_values`, `double_values`, `string_values`, `bool_values` (JSONB)
+  - `original_json` (JSONB)
+
 ## Contributing
 
 Contributions are welcome! Feel free to open issues or submit pull requests.