Initial commit

commands/troubleshoot.md

@@ -0,0 +1,694 @@
+Common issues and solutions for Odoo PWA projects.
+
+## What this command does:
+- Lists common problems and their solutions
+- Provides step-by-step debugging guides
+- Offers troubleshooting workflows
+- Helps diagnose connection, sync, and build issues
+- Links to relevant documentation and tools
+
+---
+
+## Quick Diagnostic Checklist ✅
+
+Before diving into specific issues, run through this checklist:
+
+```
+□ .env file exists and has all required variables
+□ Odoo URL is correct and reachable
+□ API key is valid and not expired
+□ Database name is correct
+□ Model name includes x_ prefix
+□ Development server is running
+□ No errors in browser console
+□ Internet connection is working
+□ Node.js version is 18 or higher
+```
+
+**Quick Test:** Run `/test-connection` to diagnose most issues automatically.
+
+---
+
+## Connection Issues 🔌
+
+### Problem: Cannot connect to Odoo
+**Symptoms:**
+- "Connection refused" error
+- "Network error" in console
+- Timeout errors
+- No data loading
+
+**Solutions:**
+
+#### 1. Verify Odoo URL
+```bash
+# Test if URL is reachable
+curl -I https://yourcompany.odoo.com
+
+# Expected: HTTP 200 or 301/302
+```
+
+**Common mistakes:**
+- Missing `https://`
+- Extra trailing slash
+- Wrong subdomain
+- Typo in URL
+
+**Fix:**
+```bash
+# Wrong
+VITE_ODOO_URL=yourcompany.odoo.com
+VITE_ODOO_URL=https://yourcompany.odoo.com/
+
+# Right
+VITE_ODOO_URL=https://yourcompany.odoo.com
+```
+
+#### 2. Check firewall / VPN
+- Try accessing Odoo URL in browser
+- Disable VPN temporarily
+- Check corporate firewall rules
+- Try from different network
+
+#### 3. Verify environment variables loaded
+```javascript
+// Add to your code temporarily
+console.log('Odoo URL:', import.meta.env.VITE_ODOO_URL);
+console.log('Database:', import.meta.env.VITE_ODOO_DB);
+```
+
+**If undefined:**
+- Restart development server
+- Check variable names (case-sensitive)
+- Ensure variables start with `VITE_`
+
+---
+
+## Authentication Issues 🔐
+
+### Problem: Invalid API key / Authentication failed
+**Symptoms:**
+- "Invalid credentials" error
+- "Access denied" message
+- 401 Unauthorized errors
+- UID is null
+
+**Solutions:**
+
+#### 1. Regenerate API Key
+1. Log into Odoo
+2. Go to Settings → Users & Companies → Users
+3. Open your user record
+4. Go to "API Keys" tab
+5. Click "New API Key"
+6. Copy the key immediately (shown only once!)
+7. Update `.env` file:
+```bash
+ODOO_API_KEY=your_new_api_key_here
+```
+8. Restart development server
+
+#### 2. Verify username matches
+```bash
+# Username must match the API key owner
+ODOO_USERNAME=john.doe@company.com  # ✅ Correct
+ODOO_USERNAME=John Doe              # ❌ Wrong
+```
+
+#### 3. Check user permissions
+- Ensure user has access to the model
+- Verify read/write permissions
+- Check if user account is active
+- Verify not locked out
+
+#### 4. Test authentication manually
+```javascript
+// In browser console
+fetch('/api/odoo', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    action: 'search',
+    model: 'res.partner',
+    domain: [],
+    fields: ['name'],
+    limit: 1
+  })
+})
+.then(r => r.json())
+.then(console.log);
+```
+
+---
+
+## Model Access Issues 📋
+
+### Problem: Model not found / No records returned
+**Symptoms:**
+- "Model does not exist" error
+- Empty array returned
+- "Access rights" error
+- Records don't appear
+
+**Solutions:**
+
+#### 1. Verify model name
+```bash
+# Check model name includes x_ prefix
+VITE_MODEL_NAME=x_expense  # ✅ Correct
+VITE_MODEL_NAME=expense    # ❌ Wrong
+```
+
+#### 2. Check model exists in Odoo
+1. Log into Odoo
+2. Go to Settings → Technical → Database Structure → Models
+3. Search for your model name
+4. Verify it exists and is active
+
+#### 3. Check field names
+```javascript
+// Fields must use full name with x_studio_ prefix
+const fields = [
+  'x_studio_name',      // ✅ Correct
+  'x_studio_amount',    // ✅ Correct
+  'name',               // ❌ Wrong (unless it's a standard field)
+  'amount'              // ❌ Wrong
+];
+```
+
+#### 4. Verify permissions
+- User must have read access to model
+- Check access rights in Odoo Studio
+- Verify record rules don't filter all records
+- Test with admin user
+
+#### 5. Check if model is published
+- In Odoo Studio, verify model is not in draft mode
+- Ensure model is accessible via API
+- Check if model requires special access
+
+---
+
+## Sync Issues 🔄
+
+### Problem: Data not syncing
+**Symptoms:**
+- Old data displayed
+- Changes don't appear
+- "Last synced" time not updating
+- Background sync not working
+
+**Solutions:**
+
+#### 1. Check browser console
+Look for:
+- Network errors
+- JavaScript errors
+- CORS errors
+- Authentication errors
+
+#### 2. Verify sync mechanism
+```javascript
+// Check if sync is running
+// Look for these console logs:
+"Syncing x_expense..."
+"Fetched X new records"
+"Cache updated"
+```
+
+#### 3. Force refresh
+```javascript
+// In browser console
+expenseCache.refresh();
+```
+
+#### 4. Clear cache and reload
+```javascript
+// In browser console
+localStorage.clear();
+// Then refresh page
+```
+
+#### 5. Check sync interval
+```javascript
+// Verify sync timer is running
+// Default: 3 minutes (180,000ms)
+// Look in cache store for:
+setInterval(() => sync(), 180000);
+```
+
+#### 6. Test incremental sync
+```javascript
+// Check lastRecordId is updating
+const cacheData = localStorage.getItem('expenseCache');
+console.log(JSON.parse(cacheData));
+// Should show: { lastRecordId: X, lastSyncTime: Y }
+```
+
+---
+
+## Offline Mode Issues 📵
+
+### Problem: Offline mode not working
+**Symptoms:**
+- App doesn't work without internet
+- "No connection" errors when offline
+- Service worker not registered
+- Data not available offline
+
+**Solutions:**
+
+#### 1. Verify service worker registered
+```javascript
+// In browser console
+navigator.serviceWorker.getRegistration()
+  .then(reg => console.log('Service Worker:', reg));
+```
+
+#### 2. Check cache stores
+```javascript
+// Verify data is cached
+localStorage.getItem('expenseCache');
+// Should return JSON string
+
+// Check IndexedDB
+// Open DevTools → Application → IndexedDB
+// Look for your database and tables
+```
+
+#### 3. Test offline mode
+1. Load app while online
+2. Open DevTools → Network tab
+3. Enable "Offline" checkbox
+4. Refresh page
+5. App should still work
+
+#### 4. Build and test production
+```bash
+# Offline mode works better in production build
+npm run build
+npm run preview
+```
+
+#### 5. Check manifest.json
+Verify PWA manifest is correct:
+- Located in `/static/manifest.json`
+- Has correct `start_url`
+- Has valid icons
+
+---
+
+## Build / Deployment Issues 🚀
+
+### Problem: Build fails
+**Symptoms:**
+- `npm run build` returns errors
+- TypeScript errors
+- Module not found errors
+- Build process hangs
+
+**Solutions:**
+
+#### 1. Check Node version
+```bash
+node --version
+# Must be v18 or higher
+
+# If too old:
+nvm install 18
+nvm use 18
+```
+
+#### 2. Clean install
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### 3. Check for errors
+```bash
+# Run build with verbose output
+npm run build -- --verbose
+```
+
+#### 4. Verify environment variables
+```bash
+# For production build, set env vars:
+VITE_ODOO_URL=https://yourcompany.odoo.com \
+VITE_ODOO_DB=yourcompany-main \
+npm run build
+```
+
+#### 5. Check imports
+- Verify all imports are correct
+- Check for circular dependencies
+- Ensure all files exist
+
+---
+
+### Problem: Deployment fails
+**Symptoms:**
+- Vercel/Netlify build fails
+- Environment variables not working
+- 404 errors in production
+- Blank page after deployment
+
+**Solutions:**
+
+#### 1. Set environment variables
+In hosting dashboard:
+- Add all `VITE_*` variables
+- Add `ODOO_API_KEY`
+- Add `ODOO_USERNAME`
+- Redeploy after adding
+
+#### 2. Check build logs
+- Review deployment logs
+- Look for specific errors
+- Check Node version in platform
+
+#### 3. Test build locally
+```bash
+npm run build
+npm run preview
+# Test at http://localhost:4173
+```
+
+#### 4. Verify base path
+```javascript
+// For GitHub Pages or subpath deployment
+// vite.config.js
+export default {
+  base: '/your-repo-name/'
+};
+```
+
+#### 5. Check API routes
+- Ensure serverless functions deploy correctly
+- Verify function size < 50MB
+- Check function logs in platform dashboard
+
+---
+
+## Performance Issues ⚡
+
+### Problem: App is slow
+**Symptoms:**
+- Slow initial load
+- Laggy UI
+- Long sync times
+- High memory usage
+
+**Solutions:**
+
+#### 1. Optimize initial load
+```javascript
+// Limit initial fetch
+const records = await odoo.searchRecords(
+  model,
+  [],
+  fields,
+  100  // Only fetch first 100
+);
+```
+
+#### 2. Add pagination
+```javascript
+// Load more on scroll
+let page = 1;
+const pageSize = 20;
+
+async function loadMore() {
+  const offset = (page - 1) * pageSize;
+  const more = await odoo.searchRecords(
+    model, [], fields, pageSize, offset
+  );
+  page++;
+  return more;
+}
+```
+
+#### 3. Optimize bundle size
+```bash
+# Analyze bundle
+npm run build -- --analyze
+
+# Lazy load routes
+// SvelteKit (automatic)
+// React
+const ExpenseList = lazy(() => import('./ExpenseList'));
+
+// Vue
+const ExpenseList = () => import('./ExpenseList.vue');
+```
+
+#### 4. Reduce sync frequency
+```javascript
+// Increase sync interval
+const SYNC_INTERVAL = 5 * 60 * 1000; // 5 minutes instead of 3
+```
+
+#### 5. Optimize images
+- Compress images before upload
+- Use appropriate image formats
+- Lazy load images
+
+---
+
+## Data Issues 📊
+
+### Problem: Wrong data displayed
+**Symptoms:**
+- Incorrect values shown
+- Missing fields
+- Corrupted data
+- Date format issues
+
+**Solutions:**
+
+#### 1. Clear cache
+```javascript
+expenseCache.clearCache();
+expenseCache.refresh();
+```
+
+#### 2. Verify field mapping
+```javascript
+// Check if fields are correctly named
+console.log(records[0]);
+// Should show x_studio_* fields
+```
+
+#### 3. Check data types
+```javascript
+// Ensure correct types
+const expense = {
+  x_studio_amount: 45.50,        // number ✅
+  x_studio_date: '2025-01-15',   // string (ISO) ✅
+  x_studio_employee: [12, false] // Many2one ✅
+};
+```
+
+#### 4. Format dates correctly
+```javascript
+// Store as ISO string
+const dateString = '2025-01-15';
+
+// Display formatted
+new Date(dateString).toLocaleDateString();
+```
+
+#### 5. Handle Many2one fields
+```javascript
+// Many2one can be [id, name] or just id
+function getPartnerId(field) {
+  return Array.isArray(field) ? field[0] : field;
+}
+
+function getPartnerName(field) {
+  return Array.isArray(field) ? field[1] : null;
+}
+```
+
+---
+
+## CORS Issues 🚫
+
+### Problem: CORS error
+**Symptoms:**
+- "Blocked by CORS policy" in console
+- Requests fail in browser but work in Postman
+- Preflight errors (OPTIONS)
+
+**Solutions:**
+
+#### 1. Use server-side proxy (recommended)
+All generated PWAs include server-side API routes. Ensure you're using them:
+```javascript
+// ✅ Good: Goes through server proxy
+fetch('/api/odoo', { ... });
+
+// ❌ Bad: Direct call to Odoo (CORS error)
+fetch('https://yourcompany.odoo.com/jsonrpc', { ... });
+```
+
+#### 2. Verify API route works
+```javascript
+// Test in browser console
+fetch('/api/odoo', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    action: 'search',
+    model: 'res.partner',
+    domain: [],
+    fields: ['name'],
+    limit: 1
+  })
+})
+.then(r => r.json())
+.then(console.log);
+```
+
+#### 3. Check if deployed correctly
+- Verify serverless functions deployed
+- Check function logs
+- Ensure environment variables set
+
+---
+
+## Browser-Specific Issues 🌐
+
+### Problem: Works in Chrome but not Safari/Firefox
+**Symptoms:**
+- Different behavior across browsers
+- Safari-specific errors
+- Mobile browser issues
+
+**Solutions:**
+
+#### 1. Check browser compatibility
+- Test in multiple browsers
+- Check for console errors in each
+- Verify IndexedDB support
+
+#### 2. Safari-specific
+- Safari has stricter storage limits
+- Check if localStorage/IndexedDB working
+- Test in private mode
+
+#### 3. Mobile browsers
+- Test on actual devices
+- Check responsive design
+- Verify touch interactions work
+
+---
+
+## Debugging Tools & Commands 🔧
+
+### Essential Commands
+```bash
+# Test connection
+/test-connection
+
+# View full help
+/help
+
+# See architecture details
+/architecture
+
+# Clear cache and start fresh
+/clear-cache
+
+# Fix sync issues
+/fix-sync
+```
+
+### Browser DevTools
+```javascript
+// Network tab
+// - See all API calls
+// - Check request/response
+// - View timing
+
+// Console tab
+// - See error messages
+// - Run test commands
+// - Inspect data
+
+// Application tab
+// - View localStorage
+// - Inspect IndexedDB
+// - Check Service Workers
+// - View Cache Storage
+
+// Performance tab
+// - Profile slow operations
+// - Find bottlenecks
+```
+
+### Useful Console Commands
+```javascript
+// View cache
+localStorage.getItem('expenseCache');
+
+// Clear cache
+localStorage.clear();
+
+// Force refresh
+expenseCache.refresh();
+
+// View current records
+console.log($expenseCache); // SvelteKit
+
+// Test API
+fetch('/api/odoo', { /* ... */ })
+  .then(r => r.json())
+  .then(console.log);
+```
+
+---
+
+## Getting Help 💬
+
+### Before asking for help:
+1. Run `/test-connection`
+2. Check browser console for errors
+3. Review this troubleshooting guide
+4. Try solutions listed above
+5. Test with minimal example
+
+### When reporting issues:
+Include:
+- Exact error message
+- Browser and version
+- Node.js version
+- Steps to reproduce
+- What you've already tried
+- Relevant code snippets
+
+### Helpful resources:
+- `/help` - Plugin documentation
+- `/examples` - Usage examples
+- `/architecture` - Design patterns
+- `/api-reference` - API documentation
+- Odoo docs: https://www.odoo.com/documentation/
+- Framework docs (SvelteKit/React/Vue)
+
+---
+
+## Example prompts to use this command:
+- `/troubleshoot` - Show troubleshooting guide
+- User: "Why isn't my data syncing?"
+- User: "I'm getting a connection error"
+- User: "Help! Nothing works!"
+
+## Still Stuck?
+If these solutions don't help:
+1. Run `/test-connection` for detailed diagnostics
+2. Check generated project's CLAUDE.md
+3. Review Odoo server logs
+4. Test with different Odoo model
+5. Try generating fresh project to compare
+
+Most issues are related to configuration or permissions. Double-check your `.env` file and Odoo settings!