codymaster 4.1.4 → 4.3.0

package/skills/cm-google-form/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: cm-google-form
+description: Google App Script form-to-sheet integration with auto-retry, toast notifications, and Zalo/contact fallback. Reusable across any static website.
+allowed-tools: Read, Write, Edit, Glob, Grep, Browser
+version: 1.0
+priority: HIGH
+---
+
+# Google Forms → Sheet Integration Skill
+
+> **Connect HTML forms → Google Sheets via Google Apps Script.**
+> Auto-retry, toast UI, contact fallback on errors. Zero dependencies, works on any static site.
+
+---
+
+## 🎯 When to Use
+
+| Trigger | Action |
+|---------|--------|
+| User says "create form", "connect Google Sheet" | Activate this skill |
+| User says "form broken", "submit not working" | Debug using Phase 4-5 |
+| User says "add new form to page" | Start from Phase 2 |
+| User says "form for another website" | Start from Phase 1 |
+
+---
+
+## 📋 5-Phase Workflow
+
+```
+Phase 1: DISCOVER → Scan forms, identify fields, determine sheet structure
+Phase 2: PLAN → Design sheet columns, map form fields, create deployment plan
+Phase 3: BUILD → Generate Apps Script + Frontend JS + Toast CSS
+Phase 4: INTEGRATE → Wire forms to JS, add CSS, deploy Apps Script
+Phase 5: VERIFY → Test submit, test retry, test error fallback
+```
+
+> 🔴 **Rule:** NEVER skip Phase 1. Always read existing forms first.
+
+---
+
+## Phase 1: DISCOVER (Scan & Analyze)
+
+**Goal:** Understand what forms exist and what fields they have.
+
+### Actions:
+
+1. **Search for forms** in the project:
+   ```
+   grep -r "data-form-type\|onsubmit\|<form" --include="*.html" .
+   ```
+
+2. **For each form found, extract:**
+
+| Info | How to Find |
+|------|-------------|
+| Form type | `data-form-type` attribute |
+| Fields | `<input name="...">`, `<select name="...">` |
+| Submit handler | `onsubmit` attribute |
+| Page URL | File path |
+
+3. **Ask user** (Socratic Gate):
+   - How many separate Google Sheets? (1 shared sheet or separate?)
+   - What columns does each sheet need?
+   - Is there a fallback contact channel? (WhatsApp, Messenger, Hotline?)
+   - Fallback contact URL (e.g., `https://wa.me/15551234567`)
+
+### Output: Form Inventory Table
+
+```markdown
+| # | Form Type | Pages | Fields | Target Sheet |
+|---|-----------|-------|--------|-------------|
+| 1 | massage   | 7     | name, phone, branch, problem, time, package | Sheet Massage |
+| 2 | course    | 1     | name, phone, goal | Course Sheet |
+```
+
+---
+
+## Phase 2: PLAN (Design & Map)
+
+**Goal:** Map form fields → Sheet columns → Apps Script params.
+
+### Sheet Column Design
+
+For each sheet, define columns in order:
+
+| Column | Source | Always Include |
+|--------|--------|---------------|
+| Timestamp | `new Date()` — auto | ✅ Yes |
+| (form fields) | `e.parameter.xxx` | From inventory |
+| Page Source | `e.parameter.url` | ✅ Yes |
+
+### Naming Convention
+
+| Element | Convention |
+|---------|-----------|
+| Sheet tab name | `Data` |
+| Form attribute | `data-form-type="<type>"` |
+| Hidden URL field | `<input type="hidden" name="url" value="">` |
+| JS global function | `window.submitToGoogleSheet` |
+
+### Deliverables Checklist
+
+- [ ] Apps Script code per sheet
+- [ ] Frontend JS with retry + toast
+- [ ] Toast CSS component
+- [ ] HTML form markup template
+- [ ] Deploy instructions
+- [ ] Verification test plan
+
+---
+
+## Phase 3: BUILD (Generate Code)
+
+### 3A. Google Apps Script Template
+
+> See `templates/apps-script.js` for the full template.
+
+**Key rules:**
+- Always use `doPost(e)` — NOT `doGet`
+- Always wrap in `try/catch`
+- Always return JSON with `{status: "success"}` or `{status: "error", message: "..."}`
+- Column order MUST match `sheet.appendRow([...])` order
+- Tab name MUST match `SHEET_NAME` constant
+
+### 3B. Frontend JavaScript
+
+> See `templates/form-submit.js` for the full template.
+
+**Key features:**
+
+| Feature | Detail |
+|---------|--------|
+| Auto-retry | 3 attempts, exponential backoff (1s → 2s → 4s) |
+| Toast UI | Success (green), Error (red), Retrying (amber) |
+| Phone validation | Vietnamese format: `/^0\d{8,10}$/` |
+| Button states | "Submitting..." → "Retrying (X/3)..." → reset |
+| CORS handling | Handles opaque responses from Apps Script |
+| Fallback | Zalo button in error toast |
+| Auto-dismiss | Success: 6s, Error: 15s, Retrying: 10s |
+
+### 3C. Toast CSS
+
+> See `templates/toast.css` for the full template.
+
+**3 variants:** `--success`, `--error`, `--retrying`
+
+### 3D. HTML Form Markup
+
+> See `templates/form-markup.html` for examples.
+
+**Required attributes:**
+```html
+<form data-form-type="TYPE" onsubmit="window.submitToGoogleSheet(event)">
+  <input type="hidden" name="url" value="">
+  <!-- form fields with name="..." -->
+  <button type="submit">Submit Text</button>
+</form>
+```
+
+---
+
+## Phase 4: INTEGRATE (Wire Everything)
+
+### Step-by-step:
+
+1. **Add Toast CSS** → Append to main CSS file (e.g., `design-system.css`)
+2. **Add Form JS** → Add to shared JS file or create `js/form-handler.js`
+3. **Update HTML forms:**
+   - Add `data-form-type="..."` attribute
+   - Add `onsubmit="window.submitToGoogleSheet(event)"`
+   - Add `<input type="hidden" name="url" value="">`
+   - Ensure all inputs have `name="..."` matching Apps Script params
+4. **Configure URLs:**
+   - Replace placeholder URLs in JS with deployed Apps Script URLs
+5. **Configure fallback contact:**
+   - Replace Zalo URL in JS toast with project's contact URL
+
+### Customization Points
+
+| Setting | Location | Default |
+|---------|----------|---------|
+| Apps Script URLs | JS `URLS` object | placeholder |
+| Fallback contact | Toast Zalo link | `https://zalo.me/...` |
+| Max retries | `fetchWithRetry` arg | 3 |
+| Phone regex | Validation block | `/^0\d{8,10}$/` |
+| Toast auto-dismiss | `showFormToast` timeouts | 6s/15s/10s |
+| Success message | `.then()` block | Customizable |
+| Error message | `.catch()` block | Customizable |
+
+---
+
+## Phase 5: VERIFY (Test & Report)
+
+### Test Checklist
+
+| # | Test Case | Expected | Status |
+|---|-----------|----------|--------|
+| 1 | Submit valid form | Toast success (green) + Zalo opens | |
+| 2 | Submit invalid phone | Toast error "Invalid phone number" | |
+| 3 | Network offline | 3 retries → Toast error with Zalo button | |
+| 4 | Check Google Sheet | New row appears with correct data | |
+| 5 | Button states | Disabled during submit, resets after | |
+| 6 | Toast close button | Toast disappears on click | |
+| 7 | Mobile responsive | Toast visible above sticky CTA | |
+| 8 | Multiple forms same page | Each form submits independently | |
+
+### How to Test Retry
+
+1. Open DevTools → Network tab
+2. Block domain `script.google.com`
+3. Submit form → Should see 3 retry attempts
+4. Unblock → Submit again → Should succeed
+
+### Report Template
+
+```markdown
+## Form Integration Test Report
+
+**Date:** YYYY-MM-DD
+**Pages tested:** X/Y
+
+| Page | Form Type | Submit | Retry | Fallback | Sheet |
+|------|-----------|--------|-------|----------|-------|
+| index.html | massage | ✅ | ✅ | ✅ | ✅ |
+| khoa-hoc.html | course | ✅ | ✅ | ✅ | ✅ |
+
+**Issues found:** None / [list issues]
+**Resolution:** [fixes applied]
+```
+
+---
+
+## ❌ Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|------|
+| Use `alert()` for feedback | Use toast notifications |
+| No retry on failure | Auto-retry 3x with backoff |
+| Silently fail | Show error + contact fallback |
+| Hardcode form URLs | Use config object (`URLS`) |
+| Skip phone validation | Validate before submit |
+| Forget `name` attribute | Every input MUST have `name` |
+| Use `doGet` for form submit | Use `doPost` only |
+| Multiple submit handlers | One shared `submitToGoogleSheet` |
+
+---
+
+## 📑 Templates
+
+| File | Purpose |
+|------|---------|
+| `templates/apps-script.js` | Google Apps Script doPost handler |
+| `templates/form-submit.js` | Frontend JS with retry + toast |
+| `templates/toast.css` | Toast notification CSS component |
+| `templates/form-markup.html` | HTML form examples |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| Form UI/UX design | `@[skills/cm-ux-master]` |
+| SEO for forms | `@[skills/cm-dockit]` |
+| Form security | `@[skills/vulnerability-scanner]` |
+| Deployment | `@[skills/deployment-procedures]` |

package/skills/cm-google-form/templates/apps-script.js

@@ -0,0 +1,55 @@
+/**
+ * Google Apps Script — Form to Sheet Handler
+ * 
+ * SETUP:
+ * 1. Create Google Sheet with headers matching appendRow columns
+ * 2. Extensions > Apps Script > paste this code
+ * 3. Deploy > New deployment > Web app
+ *    - Execute as: Me
+ *    - Who has access: Anyone
+ * 4. Copy the deployment URL → use in frontend URLS config
+ * 
+ * CUSTOMIZATION:
+ * - Change SHEET_NAME if tab is not "Data"
+ * - Modify appendRow columns to match your form fields
+ * - Add more e.parameter.xxx for additional fields
+ */
+
+const SHEET_NAME = 'Data';
+
+function doPost(e) {
+    try {
+        const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(SHEET_NAME);
+        if (!e || !e.parameter) {
+            return ContentService.createTextOutput(JSON.stringify({ status: 'error', message: 'No data received' }))
+                .setMimeType(ContentService.MimeType.JSON);
+        }
+
+        const p = e.parameter;
+
+        // ═══════════════════════════════════════
+        // CUSTOMIZE: Change columns below to match your form
+        // Column order MUST match Sheet header row
+        // ═══════════════════════════════════════
+        sheet.appendRow([
+            new Date(),           // A: Thời gian (auto)
+            p.name || '',         // B: Họ tên
+            p.phone || '',        // C: SĐT
+            // --- Add your custom fields below ---
+            // p.email || '',      // D: Email
+            // p.branch || '',     // E: Chi nhánh
+            // p.problem || '',    // F: Vấn đề
+            // p.time || '',       // G: Khung giờ
+            // p.package || '',    // H: Gói dịch vụ
+            // p.goal || '',       // I: Mục tiêu
+            // --- End custom fields ---
+            p.url || ''           // Last: Nguồn trang (auto)
+        ]);
+
+        return ContentService.createTextOutput(JSON.stringify({ status: 'success' }))
+            .setMimeType(ContentService.MimeType.JSON);
+    } catch (err) {
+        return ContentService.createTextOutput(JSON.stringify({ status: 'error', message: err.toString() }))
+            .setMimeType(ContentService.MimeType.JSON);
+    }
+}

package/skills/cm-google-form/templates/form-markup.html

@@ -0,0 +1,110 @@
+<!--
+  Form Markup Templates — Google Apps Script Integration
+  
+  RULES:
+  1. Every form MUST have data-form-type="TYPE"
+  2. Every form MUST have onsubmit="window.submitToGoogleSheet(event)"
+  3. Every form MUST include <input type="hidden" name="url" value="">
+  4. Every input/select MUST have name="..." matching Apps Script params
+  5. One submit button with type="submit"
+-->
+
+<!-- ═══════════════════════════════════════ -->
+<!-- EXAMPLE 1: Service Booking (Massage)   -->
+<!-- ═══════════════════════════════════════ -->
+<form data-form-type="massage" onsubmit="window.submitToGoogleSheet(event)">
+    <input type="hidden" name="url" value="">
+    
+    <div class="form-group">
+        <label class="form-label">Họ và tên</label>
+        <input type="text" class="form-input" name="name" placeholder="Nhập họ tên" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Số điện thoại</label>
+        <input type="tel" class="form-input" name="phone" placeholder="0xxx xxx xxx" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Chi nhánh</label>
+        <select class="form-input" name="branch">
+            <option>Chi nhánh 1</option>
+            <option>Chi nhánh 2</option>
+        </select>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Vấn đề quan tâm</label>
+        <select class="form-input" name="problem">
+            <option>Đau cổ vai gáy</option>
+            <option>Mất ngủ</option>
+            <option>Đau lưng</option>
+            <option>Khác</option>
+        </select>
+    </div>
+    
+    <button type="submit" class="btn btn-primary btn-lg" style="width:100%;">Đặt Lịch Ngay</button>
+    
+    <p style="text-align:center;margin-top:12px;font-size:14px;color:#666;">
+        Hoặc gọi: <a href="tel:0559669663" style="color:#C9A84C;font-weight:600;">0559.669.663</a>
+    </p>
+</form>
+
+
+<!-- ═══════════════════════════════════════ -->
+<!-- EXAMPLE 2: Course Registration          -->
+<!-- ═══════════════════════════════════════ -->
+<form data-form-type="course" onsubmit="window.submitToGoogleSheet(event)">
+    <input type="hidden" name="url" value="">
+    
+    <div class="form-group">
+        <label class="form-label">Họ và tên</label>
+        <input type="text" class="form-input" name="name" placeholder="Nhập họ tên" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Số điện thoại</label>
+        <input type="tel" class="form-input" name="phone" placeholder="0xxx xxx xxx" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Mục tiêu học</label>
+        <select class="form-input" name="goal">
+            <option>Chuyển nghề</option>
+            <option>Nâng cấp kỹ năng</option>
+            <option>Chăm sóc gia đình</option>
+        </select>
+    </div>
+    
+    <button type="submit" class="btn btn-primary btn-lg" style="width:100%;">Đăng Ký Tư Vấn</button>
+</form>
+
+
+<!-- ═══════════════════════════════════════ -->
+<!-- EXAMPLE 3: Simple Contact/Lead Form     -->
+<!-- ═══════════════════════════════════════ -->
+<form data-form-type="contact" onsubmit="window.submitToGoogleSheet(event)">
+    <input type="hidden" name="url" value="">
+    
+    <div class="form-group">
+        <label class="form-label">Họ và tên</label>
+        <input type="text" class="form-input" name="name" placeholder="Nhập họ tên" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Số điện thoại</label>
+        <input type="tel" class="form-input" name="phone" placeholder="0xxx xxx xxx" required>
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Email (tùy chọn)</label>
+        <input type="email" class="form-input" name="email" placeholder="email@example.com">
+    </div>
+    
+    <div class="form-group">
+        <label class="form-label">Nội dung</label>
+        <textarea class="form-input" name="message" rows="3" placeholder="Bạn cần hỗ trợ gì?"></textarea>
+    </div>
+    
+    <button type="submit" class="btn btn-primary btn-lg" style="width:100%;">Gửi Yêu Cầu</button>
+</form>

package/skills/cm-google-form/templates/form-submit.js

@@ -0,0 +1,201 @@
+/**
+ * Form Submission Handler — Auto Retry + Toast UI + Fallback
+ * 
+ * Features:
+ * - Auto retry 3x with exponential backoff (1s → 2s → 4s)
+ * - Toast notifications (success/error/retrying) — no alert()
+ * - Phone validation (Vietnamese format)
+ * - Zalo/contact fallback on total failure
+ * - CORS-safe: handles opaque responses from Google Apps Script
+ * 
+ * USAGE:
+ * 1. Include this script in your page (or append to shared.js)
+ * 2. Add toast.css to your stylesheet
+ * 3. Configure URLS object with your Apps Script deployment URLs
+ * 4. Configure FALLBACK_CONTACT with your Zalo/contact URL
+ * 5. Add forms with: data-form-type="xxx" onsubmit="window.submitToGoogleSheet(event)"
+ */
+
+// ═══════════════════════════════════════
+// CONFIGURATION — Change these values
+// ═══════════════════════════════════════
+const FORM_CONFIG = {
+    // Apps Script URLs per form type
+    URLS: {
+        // Add your deployed Apps Script URLs here
+        // massage: 'https://script.google.com/macros/s/YOUR_ID/exec',
+        // course:  'https://script.google.com/macros/s/YOUR_ID/exec',
+    },
+    // Fallback contact when form fails completely
+    FALLBACK_CONTACT: {
+        url: 'https://zalo.me/0559669663',   // Change to your Zalo/Messenger/etc
+        label: '💬 Nhắn tin Zalo ngay',       // Button text
+    },
+    // Retry settings
+    MAX_RETRIES: 3,
+    // Phone validation regex (Vietnamese)
+    PHONE_REGEX: /^0\d{8,10}$/,
+    // Messages (Vietnamese — customize for your language)
+    MESSAGES: {
+        sending: 'Đang gửi...',
+        retrying: (attempt, max) => `Đang thử lại (${attempt}/${max})...`,
+        phoneInvalid: {
+            title: 'Số điện thoại không hợp lệ',
+            msg: 'Vui lòng nhập số điện thoại bắt đầu bằng 0, từ 9-11 chữ số.',
+        },
+        success: {
+            title: 'Đăng ký thành công! 🎉',
+            msg: 'Chúng tôi sẽ liên hệ bạn trong 30 phút. Nhắn Zalo để được tư vấn nhanh hơn!',
+        },
+        retryNotice: {
+            title: 'Đang thử lại...',
+            msg: (attempt, max) => `Lần ${attempt}/${max} — Vui lòng chờ trong giây lát.`,
+        },
+        error: {
+            title: 'Gửi không thành công',
+            msg: 'Hệ thống đang bận. Vui lòng nhắn tin Zalo để được hỗ trợ ngay — chúng tôi sẽ phản hồi trong 5 phút!',
+        },
+    },
+};
+
+// ═══════════════════════════════════════
+// TOAST NOTIFICATION SYSTEM
+// ═══════════════════════════════════════
+
+function getToastContainer() {
+    let c = document.querySelector('.form-toast-container');
+    if (!c) {
+        c = document.createElement('div');
+        c.className = 'form-toast-container';
+        document.body.appendChild(c);
+    }
+    return c;
+}
+
+function showFormToast(type, title, msg, options = {}) {
+    const container = getToastContainer();
+    container.querySelectorAll('.form-toast').forEach(t => hideFormToast(t));
+
+    const icons = { success: '✅', error: '❌', retrying: '⏳' };
+    const toast = document.createElement('div');
+    toast.className = `form-toast form-toast--${type}`;
+
+    const fallback = FORM_CONFIG.FALLBACK_CONTACT;
+    toast.innerHTML = `
+        <span class="form-toast-icon">${icons[type] || '📋'}</span>
+        <div class="form-toast-body">
+            <div class="form-toast-title">${title}</div>
+            <div class="form-toast-msg">${msg}</div>
+            ${options.showFallback ? `<a href="${fallback.url}" target="_blank" class="form-toast-zalo">${fallback.label}</a>` : ''}
+        </div>
+        <button class="form-toast-close" aria-label="Close">✕</button>
+    `;
+
+    toast.querySelector('.form-toast-close').addEventListener('click', () => hideFormToast(toast));
+    container.appendChild(toast);
+
+    const dismissMs = { success: 6000, error: 15000, retrying: 10000 };
+    setTimeout(() => hideFormToast(toast), dismissMs[type] || 8000);
+
+    return toast;
+}
+
+function hideFormToast(toast) {
+    if (!toast || !toast.parentNode) return;
+    toast.classList.add('hiding');
+    setTimeout(() => toast.remove(), 300);
+}
+
+// ═══════════════════════════════════════
+// FETCH WITH RETRY (Exponential Backoff)
+// ═══════════════════════════════════════
+
+async function fetchWithRetry(url, options, maxRetries, onRetry) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const res = await fetch(url, options);
+            if (res.type === 'opaque' || res.ok) return res;
+            try {
+                const data = await res.json();
+                if (data.status === 'success') return res;
+                throw new Error(data.message || 'Server error');
+            } catch {
+                if (res.type === 'opaque') return res;
+                throw new Error(`HTTP ${res.status}`);
+            }
+        } catch (err) {
+            lastError = err;
+            if (attempt < maxRetries) {
+                const delay = Math.pow(2, attempt - 1) * 1000;
+                if (onRetry) onRetry(attempt, maxRetries);
+                await new Promise(r => setTimeout(r, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+
+// ═══════════════════════════════════════
+// FORM SUBMISSION HANDLER
+// ═══════════════════════════════════════
+
+window.submitToGoogleSheet = function (event) {
+    event.preventDefault();
+    const form = event.target;
+    const btn = form.querySelector('button[type="submit"]');
+    if (!btn || btn.disabled) return;
+    const originalText = btn.innerText;
+    const cfg = FORM_CONFIG;
+    const msgs = cfg.MESSAGES;
+
+    // Phone validation
+    const phoneInput = form.querySelector('input[name="phone"]');
+    if (phoneInput) {
+        const phone = phoneInput.value.replace(/\s+/g, '');
+        if (!cfg.PHONE_REGEX.test(phone)) {
+            showFormToast('error', msgs.phoneInvalid.title, msgs.phoneInvalid.msg);
+            phoneInput.focus();
+            return;
+        }
+    }
+
+    // Auto-fill source URL
+    const urlInput = form.querySelector('input[name="url"]');
+    if (urlInput) urlInput.value = window.location.href;
+
+    const formType = form.getAttribute('data-form-type') || Object.keys(cfg.URLS)[0];
+    const scriptURL = cfg.URLS[formType] || Object.values(cfg.URLS)[0];
+
+    if (!scriptURL) {
+        showFormToast('error', 'Lỗi cấu hình', 'Chưa cấu hình URL cho form type: ' + formType);
+        return;
+    }
+
+    btn.innerText = msgs.sending;
+    btn.disabled = true;
+
+    fetchWithRetry(
+        scriptURL,
+        { method: 'POST', body: new FormData(form) },
+        cfg.MAX_RETRIES,
+        (attempt, max) => {
+            btn.innerText = msgs.retrying(attempt, max);
+            showFormToast('retrying', msgs.retryNotice.title, msgs.retryNotice.msg(attempt, max));
+        }
+    )
+        .then(() => {
+            showFormToast('success', msgs.success.title, msgs.success.msg, { showFallback: true });
+            form.reset();
+            setTimeout(() => {
+                window.open(cfg.FALLBACK_CONTACT.url, '_blank');
+            }, 1500);
+        })
+        .catch(() => {
+            showFormToast('error', msgs.error.title, msgs.error.msg, { showFallback: true });
+        })
+        .finally(() => {
+            btn.innerText = originalText;
+            btn.disabled = false;
+        });
+};