h

2026-09-03 12:44:43 -03:00
parent 95dbf16d04
commit 69a9370104
2 changed files with 165 additions and 1284 deletions
@@ -0,0 +1,163 @@
+# Order Dashboard - Project Guide
+
+## Overview
+
+A professional, modern dashboard for order management that fetches data from a webhook API. Features include real-time data loading, column filtering, sorting, global search, authentication handling, and recheck status tracking.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.html` | Main HTML structure, links to CSS and JS |
+| `style.css` | All styling and animations |
+| `app.js` | Application logic, API calls, state management |
+
+## API
+
+- **Endpoint:** `https://n8n.finorbrands.com/webhook/61f89d5c-8474-4045-b52c-50ee608435c0`
+- **GET:** Fetches order data
+- **POST:** Updates recheck status (body: `{Order_ID: string, recheck: boolean}`)
+- **Auth:** Basic Authentication (username:password) via `Authorization: Basic <base64>` header
+- **Response format:** `{"data": [{Month, Odoo_AR_Nr, Order_ID, Country_Name, VAT, Remark, recheck?}]}`
+
+## Data Model
+
+```javascript
+{
+    Month: string,
+    Odoo_AR_Nr: string,
+    Order_ID: string,
+    Country_Name: string | null,
+    VAT: string | null,
+    Remark: string | null,
+    recheck: boolean | undefined
+}
+```
+
+## Features
+
+- Real-time data loading from webhook API
+- Column-level filtering with checkboxes
+- Column sorting (ascending/descending)
+- Global search across all fields
+- Statistics dashboard (total orders, countries, VAT entries)
+- Authentication modal with credential persistence
+- Recheck checkboxes with POST updates
+- NOK remark detection (red highlighting)
+- Country classification with color badges
+- Responsive design for mobile/desktop
+- Debug console logging
+
+## Architecture
+
+### State Management
+- `allData` - Raw data from API
+- `filteredData` - Data after global search/filtering
+- `currentSort` - Current sort column and direction
+- `filters` - Column filter selections
+- `globalSearch` - Search term
+- `apiCredentials` - Current auth session
+
+### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `loadData()` | Fetches data from API, handles auth |
+| `applyFilters()` | Applies search and column filters |
+| `sortTable()` | Sorts data by column |
+| `renderTable()` | Generates HTML table rows |
+| `handleRecheck()` | POSTs recheck status change |
+| `showCredentialPrompt()` | Shows auth modal |
+| `toggleAuth()` | Toggle credential session |
+
+## Lessons Learned
+
+### What Worked Well
+
+1. **Null-safe string operations** - Always use `String(value)` or `value || ''` before calling `.includes()` or `.toString()`
+2. **Modal click handling** - Use `e.target === this` to differentiate clicking overlay vs modal children
+3. **CSS specificity** - Use `!important` strategically for modal overlay to override other styles
+4. **Separated concerns** - Keeping HTML, CSS, and JS in separate files makes debugging easier
+5. **Console debugging** - Color-coded, grouped console logs make debugging fast
+
+### Critical Bug Patterns
+
+1. **`.includes()` on null/undefined** - Always guard: `if (!val) return ''; val.toString().includes()`
+2. **Event bubbling on modals** - Clicking input inside overlay triggers overlay click handler
+3. **Colspan mismatches** - Loading/empty state must match table column count
+4. **CSS order matters** - Modal reset styles must come before modal component styles
+
+### Common Pitfalls
+
+- Don't forget to handle `null` and `undefined` for API fields
+- Don't use `item[column] === null ? 'null' : item[column]` inconsistently (string 'null' vs actual null)
+- Don't nest modal HTML inside overlay div if overlay click handler checks `e.target === this`
+- Don't forget to escape Order_ID in onclick handlers (use single quotes)
+
+## Code Style
+
+- No frameworks, vanilla JS only
+- CSS custom properties for theming
+- CSS Grid for stats, Flexbox for layout
+- Async/await for API calls
+- IIFE-free, module-style globals
+- JSDoc-style comments for functions
+
+## Adding New Columns
+
+1. Add `<th>` in table header with filter/sort indicators
+2. Add column to filter data in `applyFilters()`
+3. Add rendering in `renderTable()`
+4. Add null-safe getter function if needed
+5. Add CSS classes if special styling required
+
+## Authentication Flow
+
+1. API returns 401 → Show credential modal
+2. User enters credentials → Save to localStorage
+3. Next `loadData()` call → Include Basic Auth header
+4. User clicks auth button when logged in → Clear credentials
+
+## Debug Console
+
+All major operations log to console with colored, grouped messages:
+- Webhook Call (green header)
+- Credentials (purple header)
+- Filter State (purple header)
+- Table View (cyan header)
+- Recheck (green header)
+- Errors (red header)
+
+## Future Enhancements
+
+- Export to CSV
+- Pagination for large datasets
+- Column width resizing
+- Saved filter presets
+- Dark/light theme toggle
+- Data caching
+- Offline mode
+
+## Running Locally
+
+```bash
+# Start with live-reload
+./start.sh
+
+# Or open directly
+open index.html
+```
+
+## Browser Compatibility
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Requires ES6+ features
+
+## Performance Notes
+
+- All filtering/sorting is client-side
+- Consider pagination for >1000 records
+- Debounce search input for large datasets
+- Filter dropdowns are created on-demand