From 98d1ea810dcece173c8a974e4794035c8c25d7ae Mon Sep 17 00:00:00 2001 From: Danny Stocker Date: Thu, 13 Nov 2025 14:18:43 +0100 Subject: [PATCH] [INSTRUCTIONS] Single source of truth for all cloud sessions - INSTRUCTIONS_FOR_ALL_SESSIONS.md: Complete guide - 3 features deployed and live - Session 6: Inventory & warranty tracking (90-120 min) - QC/Testing tasks for completed sessions - Self-coordination protocol - FEATURE_SPEC_INVENTORY_WARRANTY.md: Complete spec - 3 database tables - 8 API endpoints - Frontend components - Demo data (10 items) - Session 6 prompt: Step-by-step implementation guide GitHub URL to paste into all sessions: https://github.com/dannystocker/navidocs/blob/navidocs-cloud-coordination/INSTRUCTIONS_FOR_ALL_SESSIONS.md --- FEATURE_SPEC_INVENTORY_WARRANTY.md | 473 ++++++++++++++++ INSTRUCTIONS_FOR_ALL_SESSIONS.md | 298 ++++++++++ .../current/session-6-inventory-warranty.md | 513 ++++++++++++++++++ 3 files changed, 1284 insertions(+) create mode 100644 FEATURE_SPEC_INVENTORY_WARRANTY.md create mode 100644 INSTRUCTIONS_FOR_ALL_SESSIONS.md create mode 100644 builder/prompts/current/session-6-inventory-warranty.md diff --git a/FEATURE_SPEC_INVENTORY_WARRANTY.md b/FEATURE_SPEC_INVENTORY_WARRANTY.md new file mode 100644 index 0000000..202bdcc --- /dev/null +++ b/FEATURE_SPEC_INVENTORY_WARRANTY.md @@ -0,0 +1,473 @@ +# Feature Spec: Inventory & Warranty Tracking + +**Created:** 2025-11-13 15:55 UTC +**Priority:** P0 (Demo requirement) +**Estimated Time:** 90-120 minutes +**Assignee:** Cloud Session (TBD) + +--- + +## Executive Summary + +Add equipment inventory management and warranty expiration tracking to NaviDocs for the marine demo. Boat owners need to track onboard equipment (engines, electronics, safety gear) with warranty dates and service history. + +**Value Proposition:** +- Track all boat equipment in one place +- Never miss warranty expirations +- Attach manuals/documents to specific equipment +- View service history per item +- Alert when warranties expiring soon + +--- + +## User Story + +**As a** boat owner +**I want to** track my onboard equipment and warranty dates +**So that** I can maintain equipment properly and avoid expensive out-of-warranty repairs + +**Acceptance Criteria:** +1. ✅ Add new equipment items with warranty dates +2. ✅ View all equipment in inventory list +3. ✅ See warranty status (active, expiring soon, expired) +4. ✅ Attach documents to specific equipment items +5. ✅ Track service history per item +6. ✅ Filter/search equipment by category or status +7. ✅ Get visual alerts for expiring warranties (< 30 days) + +--- + +## Database Schema + +### Table: `equipment_inventory` + +```sql +CREATE TABLE equipment_inventory ( + id TEXT PRIMARY KEY, + organization_id TEXT NOT NULL, + name TEXT NOT NULL, + category TEXT NOT NULL, + manufacturer TEXT, + model_number TEXT, + serial_number TEXT, + purchase_date INTEGER, + purchase_price REAL, + warranty_start_date INTEGER, + warranty_end_date INTEGER, + warranty_provider TEXT, + installation_date INTEGER, + location_on_boat TEXT, + notes TEXT, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL, + FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE +); + +CREATE INDEX idx_equipment_org ON equipment_inventory(organization_id); +CREATE INDEX idx_equipment_warranty_end ON equipment_inventory(warranty_end_date); +CREATE INDEX idx_equipment_category ON equipment_inventory(category); +``` + +### Table: `equipment_documents` + +```sql +CREATE TABLE equipment_documents ( + id TEXT PRIMARY KEY, + equipment_id TEXT NOT NULL, + document_id TEXT NOT NULL, + relationship_type TEXT NOT NULL, -- 'manual', 'warranty_card', 'invoice', 'service_record' + created_at INTEGER NOT NULL, + FOREIGN KEY (equipment_id) REFERENCES equipment_inventory(id) ON DELETE CASCADE, + FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE +); + +CREATE INDEX idx_equipment_docs_equipment ON equipment_documents(equipment_id); +CREATE INDEX idx_equipment_docs_document ON equipment_documents(document_id); +``` + +### Table: `equipment_service_history` + +```sql +CREATE TABLE equipment_service_history ( + id TEXT PRIMARY KEY, + equipment_id TEXT NOT NULL, + service_date INTEGER NOT NULL, + service_type TEXT NOT NULL, -- 'maintenance', 'repair', 'inspection', 'upgrade' + description TEXT NOT NULL, + cost REAL, + service_provider TEXT, + notes TEXT, + created_at INTEGER NOT NULL, + FOREIGN KEY (equipment_id) REFERENCES equipment_inventory(id) ON DELETE CASCADE +); + +CREATE INDEX idx_service_history_equipment ON equipment_service_history(equipment_id); +CREATE INDEX idx_service_history_date ON equipment_service_history(service_date); +``` + +--- + +## Equipment Categories + +**Predefined Categories:** +- Engine & Propulsion +- Electronics & Navigation +- Electrical Systems +- Plumbing & Water Systems +- HVAC & Heating +- Safety Equipment +- Deck & Hull Hardware +- Galley & Appliances +- Entertainment Systems +- Communication Equipment +- Other + +--- + +## API Endpoints + +### 1. List Equipment + +**GET** `/api/organizations/:orgId/equipment` + +**Query Params:** +- `category` (optional) - Filter by category +- `warranty_status` (optional) - 'active', 'expiring_soon', 'expired', 'none' +- `search` (optional) - Search by name, manufacturer, model + +**Response:** +```json +{ + "equipment": [ + { + "id": "eq_123", + "name": "Main Engine - Yanmar 4JH5E", + "category": "Engine & Propulsion", + "manufacturer": "Yanmar", + "model_number": "4JH5E", + "serial_number": "12345", + "warranty_status": "active", // or "expiring_soon", "expired", "none" + "warranty_end_date": 1735689600000, + "days_until_expiry": 45, + "attached_documents": 3, + "service_records": 5, + "location_on_boat": "Engine room - starboard", + "created_at": 1699920000000 + } + ], + "stats": { + "total": 23, + "warranties_active": 12, + "warranties_expiring_soon": 3, + "warranties_expired": 5, + "no_warranty": 3 + } +} +``` + +### 2. Create Equipment + +**POST** `/api/organizations/:orgId/equipment` + +**Body:** +```json +{ + "name": "Main Engine - Yanmar 4JH5E", + "category": "Engine & Propulsion", + "manufacturer": "Yanmar", + "model_number": "4JH5E", + "serial_number": "12345", + "purchase_date": 1699920000000, + "purchase_price": 8500.00, + "warranty_start_date": 1699920000000, + "warranty_end_date": 1735689600000, + "warranty_provider": "Yanmar Marine", + "location_on_boat": "Engine room - starboard" +} +``` + +### 3. Get Equipment Details + +**GET** `/api/organizations/:orgId/equipment/:equipmentId` + +**Response:** +```json +{ + "equipment": { + "id": "eq_123", + "name": "Main Engine - Yanmar 4JH5E", + "category": "Engine & Propulsion", + "manufacturer": "Yanmar", + "model_number": "4JH5E", + "serial_number": "12345", + "purchase_date": 1699920000000, + "purchase_price": 8500.00, + "warranty_start_date": 1699920000000, + "warranty_end_date": 1735689600000, + "warranty_provider": "Yanmar Marine", + "location_on_boat": "Engine room - starboard", + "notes": "Installed by ABC Marine Services", + "created_at": 1699920000000, + "updated_at": 1699920000000 + }, + "documents": [ + { + "id": "doc_456", + "title": "Yanmar 4JH5E Owner's Manual", + "relationship_type": "manual", + "attached_at": 1699920000000 + } + ], + "service_history": [ + { + "id": "srv_789", + "service_date": 1699920000000, + "service_type": "maintenance", + "description": "Oil change and filter replacement", + "cost": 250.00, + "service_provider": "ABC Marine Services" + } + ] +} +``` + +### 4. Update Equipment + +**PUT** `/api/organizations/:orgId/equipment/:equipmentId` + +### 5. Delete Equipment + +**DELETE** `/api/organizations/:orgId/equipment/:equipmentId` + +### 6. Add Service Record + +**POST** `/api/organizations/:orgId/equipment/:equipmentId/service` + +**Body:** +```json +{ + "service_date": 1699920000000, + "service_type": "maintenance", + "description": "Oil change and filter replacement", + "cost": 250.00, + "service_provider": "ABC Marine Services", + "notes": "Used Yanmar genuine parts" +} +``` + +### 7. Attach Document to Equipment + +**POST** `/api/organizations/:orgId/equipment/:equipmentId/documents` + +**Body:** +```json +{ + "document_id": "doc_456", + "relationship_type": "manual" +} +``` + +### 8. Get Warranty Alerts + +**GET** `/api/organizations/:orgId/equipment/warranty-alerts` + +**Response:** +```json +{ + "alerts": [ + { + "equipment_id": "eq_123", + "name": "Main Engine - Yanmar 4JH5E", + "warranty_end_date": 1735689600000, + "days_until_expiry": 15, + "alert_level": "urgent" // or "warning", "info" + } + ] +} +``` + +--- + +## Frontend Components + +### 1. Equipment List View (`client/src/views/Inventory.vue`) + +**Features:** +- Table view with sortable columns +- Filter by category dropdown +- Filter by warranty status (active, expiring soon, expired) +- Search bar (name, manufacturer, model) +- "Add Equipment" button +- Visual indicators: + - 🟢 Green = Warranty active (>30 days) + - 🟡 Yellow = Expiring soon (<30 days) + - 🔴 Red = Expired + - ⚪ Gray = No warranty + +**Columns:** +- Equipment Name +- Category +- Manufacturer/Model +- Warranty Status +- Days Until Expiry +- Documents Count +- Actions (View, Edit, Delete) + +### 2. Equipment Detail Modal (`client/src/components/EquipmentDetailModal.vue`) + +**Tabs:** +- **Overview** - All equipment info +- **Documents** (3) - Attached manuals, warranties, invoices +- **Service History** (5) - Chronological service records +- **Edit** - Form to update equipment info + +### 3. Add Equipment Modal (`client/src/components/AddEquipmentModal.vue`) + +**Form Fields:** +- Equipment Name* (required) +- Category* (dropdown) +- Manufacturer +- Model Number +- Serial Number +- Purchase Date (date picker) +- Purchase Price +- Warranty Start Date (date picker) +- Warranty End Date (date picker) +- Warranty Provider +- Installation Date (date picker) +- Location on Boat +- Notes (textarea) + +### 4. Warranty Alert Banner (`client/src/components/WarrantyAlertBanner.vue`) + +**Display at top of dashboard if warranties expiring soon:** +``` +⚠️ 3 warranties expiring soon +└─ Main Engine: 15 days remaining +└─ GPS Navigator: 22 days remaining +└─ VHF Radio: 28 days remaining +[View All] +``` + +--- + +## Implementation Steps + +### Phase 1: Database (15 min) + +1. Create migration: `server/migrations/011_equipment_inventory.sql` +2. Run migration locally: `node server/run-migration.js 011_equipment_inventory.sql` +3. Verify tables created + +### Phase 2: Backend API (45 min) + +1. Create service: `server/services/equipment-service.js` + - CRUD operations for equipment + - Warranty status calculation + - Alert generation logic + +2. Create routes: `server/routes/equipment.js` + - Implement all 8 endpoints listed above + - Auth middleware (JWT required) + - Organization scope validation + +3. Update `server/index.js`: + ```javascript + app.use('/api/organizations/:orgId/equipment', require('./routes/equipment')); + ``` + +### Phase 3: Frontend (60 min) + +1. Create views: + - `client/src/views/Inventory.vue` (list) + +2. Create components: + - `client/src/components/EquipmentDetailModal.vue` + - `client/src/components/AddEquipmentModal.vue` + - `client/src/components/WarrantyAlertBanner.vue` + +3. Update router: + ```javascript + { + path: '/inventory', + component: () => import('./views/Inventory.vue'), + meta: { requiresAuth: true } + } + ``` + +4. Update navigation: + - Add "Inventory" link to main menu + - Add warranty alert banner to HomeView.vue + +### Phase 4: Testing (15 min) + +1. Create test data: 10-15 sample equipment items +2. Test all CRUD operations +3. Verify warranty calculations +4. Test document attachments +5. Test service history + +--- + +## Warranty Status Logic + +```javascript +function calculateWarrantyStatus(warranty_end_date) { + if (!warranty_end_date) return 'none'; + + const now = Date.now(); + const expiryDate = warranty_end_date; + const daysUntilExpiry = Math.floor((expiryDate - now) / (1000 * 60 * 60 * 24)); + + if (daysUntilExpiry < 0) return 'expired'; + if (daysUntilExpiry <= 30) return 'expiring_soon'; + return 'active'; +} +``` + +--- + +## Demo Data + +**Sample Equipment for Riviera Plaisance Demo:** + +1. Main Engine - Yanmar 4JH5E (warranty expires in 45 days) +2. GPS Navigator - Garmin GPSMAP 1242xsv (warranty active) +3. VHF Radio - Standard Horizon GX2400 (warranty expired) +4. Watermaker - Spectra Ventura 200 (no warranty) +5. Battery Charger - Victron Multiplus 12/3000 (warranty expires in 15 days) +6. Windlass - Lewmar V5 (warranty active) +7. Autopilot - Raymarine EV-100 (warranty expires in 5 days) +8. Refrigerator - Isotherm CR65 (warranty active) +9. Air Conditioning - Dometic Turbo DTU16 (warranty expired) +10. Solar Panels - Solbian SP72 (warranty active) + +--- + +## Success Criteria + +✅ Can add new equipment with warranty info +✅ Can view all equipment in sortable table +✅ Can filter by category and warranty status +✅ Can attach documents to equipment +✅ Can add service records +✅ Warranty alerts show on dashboard +✅ Visual indicators for warranty status (colors) +✅ Can search equipment by name/manufacturer/model +✅ Can edit and delete equipment +✅ Activity timeline shows equipment events + +--- + +## Next Steps After Completion + +1. Push feature branch to GitHub +2. Create SESSION-INVENTORY-COMPLETE.md +3. Signal ready for integration +4. Test with real demo data + +--- + +**Duration:** 90-120 minutes +**Dependencies:** None (standalone feature) +**Branch:** `feature/inventory-warranty` diff --git a/INSTRUCTIONS_FOR_ALL_SESSIONS.md b/INSTRUCTIONS_FOR_ALL_SESSIONS.md new file mode 100644 index 0000000..5210577 --- /dev/null +++ b/INSTRUCTIONS_FOR_ALL_SESSIONS.md @@ -0,0 +1,298 @@ +# Instructions for All Cloud Sessions - READ THIS FIRST + +**Last Updated:** 2025-11-13 16:00 UTC +**GitHub URL:** https://github.com/dannystocker/navidocs/blob/navidocs-cloud-coordination/INSTRUCTIONS_FOR_ALL_SESSIONS.md + +--- + +## 🎯 Current Status + +**✅ DEPLOYED TO STACKCP (3 Features Live):** +1. Smart OCR (33x speedup) - LIVE & WORKING +2. Multi-format uploads (JPG, PNG, DOCX, XLSX, TXT, MD) - LIVE & WORKING +3. Timeline (activity history) - LIVE & WORKING + +**🆕 NEW FEATURE NEEDED:** +4. Inventory & Warranty Tracking - NEEDS TO BE BUILT + +--- + +## 📋 What You Need To Do + +### Step 1: Identify Yourself + +Run this command to see your branch: +```bash +cd /home/setup/navidocs +git branch --show-current +``` + +### Step 2: Find Your Assignment + +| Your Branch Contains | Your Task | +|---------------------|-----------| +| `feature-smart-ocr` | ✅ DONE! Pick Session 6 work or QC/Testing | +| `feature-timeline` | ✅ DONE! Pick Session 6 work or QC/Testing | +| `multiformat` | ✅ DONE! Pick Session 6 work or QC/Testing | +| `feature-polish-testing` | ✅ DONE! Pick Session 6 work or QC/Testing | +| `deployment-prep` | ✅ DONE! Pick Session 6 work or QC/Testing | +| **ANY OTHER BRANCH** | 🚀 **DO SESSION 6: Build Inventory/Warranty** | + +--- + +## 🚀 SESSION 6: Build Inventory & Warranty Tracking (90-120 min) + +**If you're the first session to see this, YOU build this feature!** + +### Quick Start + +```bash +cd /home/setup/navidocs +git fetch origin +git checkout navidocs-cloud-coordination +git pull origin navidocs-cloud-coordination +git checkout -b feature/inventory-warranty +``` + +### Read the Prompt + +**Complete instructions here:** +https://github.com/dannystocker/navidocs/blob/navidocs-cloud-coordination/builder/prompts/current/session-6-inventory-warranty.md + +**Feature spec here:** +https://github.com/dannystocker/navidocs/blob/navidocs-cloud-coordination/FEATURE_SPEC_INVENTORY_WARRANTY.md + +### What You're Building + +**Equipment inventory management system with:** +- Equipment list with warranty status (🟢 active, 🟡 expiring soon, 🔴 expired) +- Add/edit/delete equipment +- Attach documents to equipment +- Service history tracking +- Dashboard alerts for expiring warranties +- Demo data: 10 sample equipment items + +### Implementation Steps + +1. **Database** (15 min) - Create 3 tables via migration +2. **Backend Service** (25 min) - equipment-service.js +3. **Backend Routes** (20 min) - routes/equipment.js (8 endpoints) +4. **Frontend View** (30 min) - views/Inventory.vue +5. **Add Equipment Modal** (20 min) - components/AddEquipmentModal.vue +6. **Navigation** (10 min) - Add "Inventory" to menu +7. **Demo Data** (10 min) - Seed 10 equipment items +8. **Testing** (15 min) - Test all features + +### When Done + +```bash +git add . +git commit -m "[SESSION-6] Add inventory & warranty tracking" +git push origin feature/inventory-warranty +``` + +Create `SESSION-6-COMPLETE.md` with summary of what you built. + +--- + +## 🧪 QC & TESTING TASKS (For Completed Sessions) + +**If your feature is done, do user testing on the live deployment:** + +### Live Site + +**URL:** https://digital-lab.ca/navidocs/ (frontend - static demo page currently) +**Backend API:** (Will be deployed after Session 6 completes) + +### Testing Tasks + +#### Task 1: Test Smart OCR (15 min) + +1. Upload a text-heavy PDF (100+ pages if possible) +2. Time how long OCR takes +3. Verify text is searchable after upload +4. Expected: <10 seconds for text PDFs (vs 180s before) + +**Report format:** +``` +# Smart OCR Test Report +- PDF name: [filename] +- Pages: [number] +- Processing time: [seconds] +- Text extracted: [Yes/No] +- Searchable: [Yes/No] +- Issues: [list any problems] +``` + +#### Task 2: Test Multi-Format Uploads (20 min) + +Upload one of each: +- JPG image +- PNG image +- DOCX document +- XLSX spreadsheet +- TXT text file +- MD markdown file + +**Verify:** +- All upload successfully +- Text extracted from each +- All searchable in search box +- Correct icons display + +**Report format:** +``` +# Multi-Format Upload Test Report +| Format | Uploaded | Text Extracted | Searchable | Issues | +|--------|----------|----------------|------------|--------| +| JPG | Yes/No | Yes/No | Yes/No | ... | +| PNG | Yes/No | Yes/No | Yes/No | ... | +| DOCX | Yes/No | Yes/No | Yes/No | ... | +| XLSX | Yes/No | Yes/No | Yes/No | ... | +| TXT | Yes/No | Yes/No | Yes/No | ... | +| MD | Yes/No | Yes/No | Yes/No | ... | +``` + +#### Task 3: Test Timeline (15 min) + +1. Upload 3-5 documents +2. Navigate to Timeline page +3. Verify all uploads appear in chronological order +4. Check timestamps are correct +5. Test filtering (if available) + +**Report format:** +``` +# Timeline Test Report +- Events showing: [Yes/No] +- Correct order: [Yes/No] +- Timestamps accurate: [Yes/No] +- All uploads tracked: [Yes/No] +- Issues: [list any problems] +``` + +#### Task 4: Integration Testing (20 min) + +**Scenario: Upload a boat manual, search it, check timeline** + +1. Upload a multi-page PDF boat manual +2. Wait for OCR to complete +3. Search for a specific term you know is in the manual +4. Verify search results show the document +5. Check timeline shows the upload event +6. Try uploading DOCX version of same manual +7. Verify both searchable + +**Report format:** +``` +# Integration Test Report +- All features working together: [Yes/No] +- Upload → OCR → Search: [Working/Broken] +- Upload → Timeline: [Working/Broken] +- Search accuracy: [Good/Fair/Poor] +- Issues: [list any problems] +``` + +#### Task 5: UI/UX Review (15 min) + +**Check:** +- Is upload button easy to find? +- Are file type restrictions clear? +- Does search work intuitively? +- Is timeline easy to navigate? +- Are error messages helpful? +- Is loading feedback clear? +- Mobile responsive? + +**Report format:** +``` +# UI/UX Review Report +- Overall usability: [Excellent/Good/Fair/Poor] +- Confusing elements: [list] +- Missing features: [list] +- Suggestions: [list] +``` + +### Where to Submit Test Reports + +Create a file: `TEST-REPORT-[YOUR-BRANCH-NAME].md` + +```bash +git add TEST-REPORT-*.md +git commit -m "[TESTING] User testing results" +git push origin [your-branch-name] +``` + +--- + +## 🔄 Coordination Protocol + +**How sessions self-coordinate:** + +1. **Check GitHub branches** to see what's done: + ```bash + git fetch origin && git branch -r | grep claude + ``` + +2. **Read this file** for latest status: + https://github.com/dannystocker/navidocs/blob/navidocs-cloud-coordination/INSTRUCTIONS_FOR_ALL_SESSIONS.md + +3. **If inventory/warranty is done** (feature/inventory-warranty branch exists with SESSION-6-COMPLETE.md): + - All remaining sessions do QC/Testing tasks above + - Submit test reports + +4. **If you're confused:** + - Check your git log: `git log --oneline -10` + - See what you've accomplished already + - Pick a task from this doc + +--- + +## 📊 Feature Summary + +**Total Features:** 4 + +| Feature | Status | Lines Added | Time Spent | +|---------|--------|-------------|------------| +| Smart OCR | ✅ DEPLOYED | 300+ | 60 min | +| Multi-format | ✅ DEPLOYED | 400+ | 90 min | +| Timeline | ✅ DEPLOYED | 600+ | 90 min | +| Inventory/Warranty | 🔄 BUILDING | TBD | 90-120 min | + +--- + +## 🎯 Success Criteria + +**When all done, NaviDocs will have:** +- ✅ 36x faster OCR for text PDFs +- ✅ Support for 7 file types (PDF, JPG, PNG, DOCX, XLSX, TXT, MD) +- ✅ Activity timeline tracking all events +- ✅ Equipment inventory with warranty tracking +- ✅ Warranty expiration alerts +- ✅ Complete documentation +- ✅ Fully tested by 5 sessions + +**Deployment:** All features live on https://digital-lab.ca/navidocs/ + +--- + +## ❓ Questions? + +**Read these docs:** +- This file (you are here): INSTRUCTIONS_FOR_ALL_SESSIONS.md +- Session 6 prompt: builder/prompts/current/session-6-inventory-warranty.md +- Feature spec: FEATURE_SPEC_INVENTORY_WARRANTY.md + +**Check your status:** +```bash +git branch --show-current +git log --oneline -10 +``` + +**No bottlenecks:** Sessions self-coordinate. No need to ask user! + +--- + +**Let's finish this! 🚀** + +**Next session to read this: Start Session 6 work immediately if feature/inventory-warranty branch doesn't exist yet!** diff --git a/builder/prompts/current/session-6-inventory-warranty.md b/builder/prompts/current/session-6-inventory-warranty.md new file mode 100644 index 0000000..a360bb8 --- /dev/null +++ b/builder/prompts/current/session-6-inventory-warranty.md @@ -0,0 +1,513 @@ +# Cloud Session Prompt: Inventory & Warranty Tracking + +**Feature:** Equipment Inventory Management with Warranty Expiration Tracking +**Duration:** 90-120 minutes +**Priority:** P0 (Demo requirement) +**Branch:** `feature/inventory-warranty` + +--- + +## Your Mission + +Build a complete equipment inventory and warranty tracking system for NaviDocs. Boat owners need to track onboard equipment (engines, electronics, safety gear) with warranty dates, service history, and document attachments. + +**What you're building:** +- Equipment inventory list with warranty status indicators +- Warranty expiration alerts +- Document attachments per equipment item +- Service history tracking +- Dashboard alerts for expiring warranties + +--- + +## Quick Start + +```bash +cd /home/setup/navidocs +git checkout navidocs-cloud-coordination +git pull origin navidocs-cloud-coordination +git checkout -b feature/inventory-warranty +``` + +--- + +## Step 1: Read the Spec (5 min) + +**Read this file:** `/home/setup/navidocs/FEATURE_SPEC_INVENTORY_WARRANTY.md` + +This spec contains: +- Complete database schema (3 tables) +- All 8 API endpoints with request/response examples +- Frontend component designs +- Warranty status calculation logic +- Demo data (10 sample equipment items) + +--- + +## Step 2: Database Migration (15 min) + +**Create:** `server/migrations/011_equipment_inventory.sql` + +**Tables to create:** +1. `equipment_inventory` - Main equipment table +2. `equipment_documents` - Links equipment to documents +3. `equipment_service_history` - Service records per equipment + +**Copy schema from:** FEATURE_SPEC_INVENTORY_WARRANTY.md (lines 50-120) + +**Run migration:** +```bash +cd server +node run-migration.js 011_equipment_inventory.sql +``` + +**Verify:** +```bash +sqlite3 db/navidocs.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'equipment%';" +``` + +--- + +## Step 3: Backend Service (25 min) + +**Create:** `server/services/equipment-service.js` + +**Functions to implement:** +```javascript +// CRUD +async function createEquipment(orgId, equipmentData) +async function getEquipmentList(orgId, filters) +async function getEquipmentById(equipmentId) +async function updateEquipment(equipmentId, updates) +async function deleteEquipment(equipmentId) + +// Service history +async function addServiceRecord(equipmentId, serviceData) +async function getServiceHistory(equipmentId) + +// Documents +async function attachDocument(equipmentId, documentId, relationshipType) +async function getEquipmentDocuments(equipmentId) + +// Warranty logic +function calculateWarrantyStatus(warranty_end_date) { + if (!warranty_end_date) return 'none'; + const now = Date.now(); + const daysUntilExpiry = Math.floor((warranty_end_date - now) / (1000 * 60 * 60 * 24)); + if (daysUntilExpiry < 0) return 'expired'; + if (daysUntilExpiry <= 30) return 'expiring_soon'; + return 'active'; +} + +// Alerts +async function getWarrantyAlerts(orgId) { + // Get equipment with warranty_end_date < now + 30 days +} +``` + +**Database connection:** Use existing `db/database.js` pattern + +**Example from codebase:** +```javascript +const db = require('../db/database'); + +async function createEquipment(orgId, data) { + const id = `eq_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; + const now = Date.now(); + + await db.run(` + INSERT INTO equipment_inventory ( + id, organization_id, name, category, manufacturer, + model_number, serial_number, purchase_date, purchase_price, + warranty_start_date, warranty_end_date, warranty_provider, + location_on_boat, notes, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + `, [id, orgId, data.name, data.category, data.manufacturer, ...]); + + return await getEquipmentById(id); +} +``` + +--- + +## Step 4: Backend Routes (20 min) + +**Create:** `server/routes/equipment.js` + +**Routes to implement:** +```javascript +const express = require('express'); +const router = express.Router({ mergeParams: true }); +const equipmentService = require('../services/equipment-service'); +const authMiddleware = require('../middleware/auth'); + +// Apply auth to all routes +router.use(authMiddleware); + +// List equipment +router.get('/', async (req, res) => { + const { orgId } = req.params; + const { category, warranty_status, search } = req.query; + // Validate orgId matches req.user.organization_id + // Call equipmentService.getEquipmentList() +}); + +// Create equipment +router.post('/', async (req, res) => { + const { orgId } = req.params; + // Validate and create +}); + +// Get equipment details +router.get('/:equipmentId', async (req, res) => { + // Get equipment + documents + service history +}); + +// Update equipment +router.put('/:equipmentId', async (req, res) => { + // Update +}); + +// Delete equipment +router.delete('/:equipmentId', async (req, res) => { + // Delete +}); + +// Add service record +router.post('/:equipmentId/service', async (req, res) => { + // Add service record +}); + +// Attach document +router.post('/:equipmentId/documents', async (req, res) => { + // Link equipment to document +}); + +// Get warranty alerts +router.get('/../warranty-alerts', async (req, res) => { + // Get expiring warranties +}); + +module.exports = router; +``` + +**Register route in `server/index.js`:** +```javascript +app.use('/api/organizations/:orgId/equipment', require('./routes/equipment')); +``` + +--- + +## Step 5: Frontend - Inventory View (30 min) + +**Create:** `client/src/views/Inventory.vue` + +**Features:** +- Table showing all equipment +- Sortable columns +- Filter by category (dropdown) +- Filter by warranty status +- Search bar +- Visual warranty indicators (🟢 🟡 🔴 ⚪) +- "Add Equipment" button + +**Template structure:** +```vue + + + + + +``` + +--- + +## Step 6: Add Equipment Modal (20 min) + +**Create:** `client/src/components/AddEquipmentModal.vue` + +**Form fields:** +- Equipment Name* (required) +- Category* (dropdown - see categories in spec) +- Manufacturer +- Model Number +- Serial Number +- Purchase Date (date picker) +- Purchase Price +- Warranty Start Date +- Warranty End Date +- Warranty Provider +- Location on Boat +- Notes + +**Submit handler:** +```javascript +async submitForm() { + const response = await fetch(`/api/organizations/${this.orgId}/equipment`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${this.token}` + }, + body: JSON.stringify(this.formData) + }); + + if (response.ok) { + this.$emit('saved'); + this.$emit('close'); + } +} +``` + +--- + +## Step 7: Navigation & Router (10 min) + +**Update:** `client/src/router.js` + +```javascript +{ + path: '/inventory', + component: () => import('./views/Inventory.vue'), + meta: { requiresAuth: true } +} +``` + +**Update:** Main navigation component + +Add "Inventory" link between "Timeline" and "Settings" + +--- + +## Step 8: Demo Data (10 min) + +**Create:** `server/seed-inventory-demo-data.js` + +```javascript +const equipmentService = require('./services/equipment-service'); + +const demoEquipment = [ + { + name: 'Main Engine - Yanmar 4JH5E', + category: 'Engine & Propulsion', + manufacturer: 'Yanmar', + model_number: '4JH5E', + serial_number: '12345', + warranty_end_date: Date.now() + (45 * 24 * 60 * 60 * 1000), // 45 days + location_on_boat: 'Engine room - starboard' + }, + { + name: 'GPS Navigator - Garmin GPSMAP 1242xsv', + category: 'Electronics & Navigation', + manufacturer: 'Garmin', + model_number: 'GPSMAP 1242xsv', + warranty_end_date: Date.now() + (365 * 24 * 60 * 60 * 1000), // 1 year + location_on_boat: 'Helm' + }, + { + name: 'Autopilot - Raymarine EV-100', + category: 'Electronics & Navigation', + manufacturer: 'Raymarine', + model_number: 'EV-100', + warranty_end_date: Date.now() + (5 * 24 * 60 * 60 * 1000), // 5 days (URGENT!) + location_on_boat: 'Helm' + }, + // Add 7 more from spec... +]; + +async function seedDemoData(orgId) { + for (const equipment of demoEquipment) { + await equipmentService.createEquipment(orgId, equipment); + } + console.log('✅ Demo inventory data seeded'); +} + +module.exports = { seedDemoData }; +``` + +**Run:** +```bash +node server/seed-inventory-demo-data.js +``` + +--- + +## Step 9: Testing (15 min) + +**Test checklist:** +- [ ] Can add new equipment via modal +- [ ] Equipment appears in inventory list +- [ ] Can filter by category +- [ ] Can filter by warranty status +- [ ] Can search equipment +- [ ] Warranty colors display correctly (green, yellow, red, gray) +- [ ] Can view equipment details +- [ ] Can edit equipment +- [ ] Can delete equipment +- [ ] Activity timeline shows equipment events + +--- + +## Step 10: Completion (5 min) + +```bash +git add . +git commit -m "[SESSION-6] Add inventory & warranty tracking + +Features: +- Equipment inventory management +- Warranty expiration tracking with visual alerts +- Service history per equipment +- Document attachments to equipment +- Dashboard alerts for expiring warranties +- 10 demo equipment items + +Database: 3 new tables (equipment_inventory, equipment_documents, equipment_service_history) +API: 8 new endpoints +Frontend: Inventory view + 2 modals" + +git push origin feature/inventory-warranty +``` + +**Create:** `SESSION-6-COMPLETE.md` documenting what you built + +--- + +## Success Criteria + +✅ Database migration creates 3 tables +✅ All 8 API endpoints working +✅ Can add/edit/delete equipment +✅ Inventory list shows warranty status with colors +✅ Can filter by category and warranty status +✅ Can search equipment +✅ Demo data loads successfully (10 items) +✅ Feature branch pushed to GitHub + +--- + +## Questions? Blockers? + +- Spec is in: `/home/setup/navidocs/FEATURE_SPEC_INVENTORY_WARRANTY.md` +- API examples: Check existing `server/routes/timeline.js` for patterns +- Vue components: Check `client/src/views/Timeline.vue` for structure +- Database: Use `server/db/database.js` (same as other features) + +**Go build! 🚀**