Initial commit

2025-11-29 18:50:06 +08:00
commit 5e3ca965d9
68 changed files with 11257 additions and 0 deletions
--- a/commands/help.md
+++ b/commands/help.md
@@ -0,0 +1,322 @@
+Display comprehensive help and documentation for the Odoo PWA Generator plugin.
+
+## What this command does:
+- Provides overview of the plugin and its capabilities
+- Lists all available commands with descriptions
+- Explains the plugin's skills and when to use them
+- Shows common usage patterns and workflows
+- Links to detailed documentation
+
+## Plugin Overview:
+The **odoo-pwa-generator** plugin helps you create offline-first Progressive Web Apps with Odoo Studio backend integration. It supports SvelteKit, React, and Vue frameworks.
+
+### Key Features:
+✨ **Quick Project Generation** - Create complete PWAs in minutes
+📱 **Offline-First** - Smart caching with background sync
+🔄 **Odoo Integration** - Seamless Odoo Studio connectivity
+🚀 **Production Ready** - Pre-configured deployment setups
+⚡ **Framework Support** - SvelteKit, React, and Vue
+
+### Core Capabilities:
+- Automatic CRUD operations for Odoo models
+- Smart caching with localStorage + IndexedDB
+- Incremental sync (only fetch new records)
+- Optimistic UI updates
+- Partner/relation resolution
+- PWA installability
+- Offline functionality
+
+## Available Commands:
+
+### 🎯 Skill Shortcuts (Project Generation)
+Create new PWA projects:
+- `/new-svelte-pwa` - Generate SvelteKit PWA
+- `/new-react-pwa` - Generate React PWA
+- `/new-vue-pwa` - Generate Vue PWA
+- `/add-model` - Add Odoo model to existing PWA
+- `/create-cache-store` - Create cache store for a model
+
+### 🔧 Workflow Commands
+Development and deployment:
+- `/init-project` - Initialize new PWA project
+- `/setup-env` - Configure environment variables
+- `/test-connection` - Test Odoo API connection
+- `/deploy-vercel` - Deploy to Vercel
+- `/deploy-github` - Deploy to GitHub Pages
+
+### 📚 Documentation Commands
+Help and reference:
+- `/help` - This help document (you are here!)
+- `/examples` - Real-world usage examples
+- `/architecture` - Explain PWA architecture
+- `/api-reference` - Odoo API client documentation
+- `/troubleshoot` - Common issues and solutions
+
+### 🛠 Maintenance Commands
+Project management:
+- `/update-deps` - Update project dependencies
+- `/fix-sync` - Diagnose and fix sync issues
+- `/clear-cache` - Clear application caches
+- `/add-deployment` - Add new deployment target
+- `/optimize` - Run optimization checks
+
+## Common Workflows:
+
+### 1️⃣ Starting a New Project
+```
+1. /new-svelte-pwa (or /new-react-pwa or /new-vue-pwa)
+2. Provide project details (name, model, etc.)
+3. /init-project
+4. Start coding!
+```
+
+### 2️⃣ Setting Up Environment
+```
+1. /setup-env
+2. Provide Odoo credentials
+3. /test-connection
+4. Verify everything works
+```
+
+### 3️⃣ Adding More Models
+```
+1. /add-model
+2. Specify model name and details
+3. Test CRUD operations
+4. Customize UI as needed
+```
+
+### 4️⃣ Deploying to Production
+```
+1. /deploy-vercel (recommended)
+   OR /deploy-github
+2. Configure environment variables
+3. Test deployed application
+4. Set up custom domain (optional)
+```
+
+### 5️⃣ Troubleshooting Issues
+```
+1. /test-connection - Check Odoo connectivity
+2. /troubleshoot - Find specific solutions
+3. /fix-sync - Diagnose sync problems
+4. /clear-cache - Reset if needed
+```
+
+## Quick Start Guide:
+
+### Step 1: Generate a New PWA
+Choose your framework and run the appropriate command:
+```
+/new-svelte-pwa
+```
+
+### Step 2: Provide Project Details
+When prompted, provide:
+- **Project name**: e.g., "expense-tracker"
+- **Odoo model**: e.g., "expense" (without x_ prefix)
+- **Display name**: e.g., "Expense"
+- **Deployment target**: e.g., "vercel" (optional)
+
+### Step 3: Initialize the Project
+```
+cd your-project-name
+/init-project
+```
+
+### Step 4: Configure Odoo Connection
+```
+/setup-env
+```
+Provide your Odoo URL, database, API key, and username.
+
+### Step 5: Test Everything
+```
+/test-connection
+```
+Verify your Odoo connection works correctly.
+
+### Step 6: Start Developing
+The dev server should be running. Open your browser and start customizing!
+
+### Step 7: Deploy (when ready)
+```
+/deploy-vercel
+```
+Follow the prompts to deploy to production.
+
+## Plugin Skills:
+
+### create-odoo-pwa
+Generates a complete PWA project from scratch.
+
+**When to use**: Starting a new project
+
+**What it generates**:
+- Base configuration (package.json, vite.config, etc.)
+- Odoo API client
+- Cache stores with smart syncing
+- Server-side API proxy
+- UI components (forms, lists)
+- PWA manifest and service worker
+- Deployment configurations
+- Complete documentation
+
+### add-odoo-model
+Adds integration for additional Odoo models.
+
+**When to use**: Adding new data models to existing project
+
+**What it generates**:
+- Cache store for the new model
+- API methods in Odoo client
+- Form and list pages (optional)
+- Navigation updates
+
+### create-cache-store
+Creates a standalone cache store.
+
+**When to use**: Need custom caching logic
+
+**What it generates**:
+- Framework-specific cache store
+- Smart caching logic
+- Background sync
+- Optimistic updates
+
+## Best Practices:
+
+### Security
+- ✅ Keep API keys in `.env` file (never commit)
+- ✅ Use different credentials for dev and production
+- ✅ Set environment variables in hosting platform
+- ✅ Rotate API keys periodically
+
+### Development
+- ✅ Test Odoo connection before coding
+- ✅ Use version control (Git)
+- ✅ Test offline functionality regularly
+- ✅ Read generated CLAUDE.md for patterns
+
+### Deployment
+- ✅ Build and test locally first
+- ✅ Use Vercel/Netlify for full functionality
+- ✅ Set up continuous deployment from Git
+- ✅ Monitor performance and errors
+
+### Maintenance
+- ✅ Keep dependencies updated
+- ✅ Monitor Odoo API changes
+- ✅ Test after Odoo upgrades
+- ✅ Clear caches when schema changes
+
+## Getting More Help:
+
+### Example prompts to use this command:
+- `/help` - Show this help document
+- User: "How do I use the Odoo PWA plugin?"
+- User: "What commands are available?"
+
+### In Generated Projects:
+- `README.md` - Getting started guide
+- `CLAUDE.md` - Architecture patterns
+- `API.md` - API client reference
+
+### External Resources:
+- Odoo API Documentation: https://www.odoo.com/documentation/
+- SvelteKit: https://kit.svelte.dev/
+- React: https://react.dev/
+- Vue: https://vuejs.org/
+- PWA Guide: https://web.dev/progressive-web-apps/
+
+### Troubleshooting:
+If you encounter issues:
+1. Run `/test-connection` to diagnose
+2. Check `/troubleshoot` for common solutions
+3. Review browser console for errors
+4. Verify Odoo configuration
+5. Check generated documentation
+
+### Support:
+For bugs or feature requests:
+- Check existing issues
+- Review documentation thoroughly
+- Provide detailed error messages
+- Include environment details
+
+## Framework-Specific Notes:
+
+### SvelteKit (Recommended)
+- Uses Svelte 5 runes syntax
+- Server-side API routes work perfectly
+- Best offline functionality
+- Smallest bundle size
+- Easiest to deploy
+
+### React
+- Modern React 18+ hooks
+- Context API for state management
+- Wide ecosystem support
+- Popular and familiar
+
+### Vue
+- Vue 3 Composition API
+- Pinia for state management
+- Great developer experience
+- Progressive framework
+
+## Architecture Highlights:
+
+### Data Flow
+```
+Component → Cache Store → API Client → Server Route → Odoo
+```
+
+### Caching Strategy
+1. **Load from cache** (instant, may be stale)
+2. **Check if stale** (> 5 minutes)
+3. **Background sync** (fetch new data)
+4. **Update cache** (localStorage + IndexedDB)
+5. **Reactive update** (UI updates automatically)
+
+### Sync Strategy
+1. **Incremental fetch** - Only `id > lastRecordId`
+2. **Partner resolution** - Batch fetch related records
+3. **Optimistic updates** - UI updates before server
+4. **Error recovery** - Graceful offline handling
+
+## Tips and Tricks:
+
+💡 **Use the right command for the job**
+- Quick start? `/new-svelte-pwa`
+- Need help? `/help` or `/troubleshoot`
+- Deploy ready? `/deploy-vercel`
+
+💡 **Test early and often**
+- Run `/test-connection` after setup
+- Test offline mode frequently
+- Verify sync works correctly
+
+💡 **Read the generated docs**
+- CLAUDE.md has architecture details
+- API.md has client method docs
+- README.md has setup instructions
+
+💡 **Customize to your needs**
+- Start with generated code
+- Modify UI components
+- Add business logic
+- Extend with new features
+
+💡 **Deploy with confidence**
+- Test build locally first
+- Use environment variables properly
+- Monitor after deployment
+- Set up error tracking
+
+## Summary:
+The odoo-pwa-generator plugin makes it easy to create production-ready PWAs with Odoo integration. Use the commands above to generate, develop, deploy, and maintain your applications.
+
+For more details on any command, just run that command and follow the prompts!
+
+Happy coding! 🚀