initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,74 @@
+# AI Write Debugging Guide
+
+The AI Write feature has multiple call sites with different element IDs, and
+several silent-failure modes. Use this guide when "AI Write does nothing."
+
+## Call sites (3 locations, different element IDs)
+
+| Function | Button ID | Explanation ID | Notes ID |
+|----------|-----------|---------------|----------|
+| `setupCustomServiceModalEventListeners()` | `custom-service-ai-write-btn` | `custom-service-explanation` | `custom-service-technician-notes` |
+| `setupServiceEditEventListeners()` (inline modal) | `ai-write-btn-quote` | `service-edit-explanation-quote` | `service-edit-technician-notes-quote` |
+| Settings `setupServiceEventListeners()` | `ai-write-btn-settings` | `service-edit-explanation-settings` | `service-edit-technician-notes` |
+
+## Common failure modes
+
+### 1. Element ID mismatch
+The handler looks for one ID but the HTML has a different suffix. Always use
+`||` fallback chains that include ALL possible ID variants:
+```javascript
+const btn = document.getElementById('ai-write-btn-main') 
+         || document.getElementById('ai-write-btn-fallback') 
+         || document.getElementById('ai-write-btn-quote');
+```
+
+### 2. Duplicate event listeners (race condition)
+`setupServiceEditEventListeners()` was called every time the modal opened,
+accumulating click handlers via `addEventListener()`. After 3 opens, clicking
+AI Write fired 4 simultaneous API calls. Fix: guard with attribute.
+```javascript
+if (modal.hasAttribute('data-edit-event-listeners-attached')) return;
+modal.setAttribute('data-edit-event-listeners-attached', 'true');
+```
+
+### 3. FormValidator blocks save silently
+FormValidator initialized with wrong IDs → `validateForm()` always false →
+`saveServiceEdit()` never called. No error shown. Fix: call `saveServiceEdit()`
+directly.
+
+### 4. LLM ignores technician notes
+The notes were sent to the LLM but the prompt never told it to use them. Fix:
+put notes in the system prompt body with a prominent header AND add explicit
+numbered instructions.
+
+### 5. `explanationTextarea` vs `explTextarea` typo
+Variable defined as `explanationTextarea` but used as `explTextarea` at one
+call site. ReferenceError — caught by the catch block, shows generic error.
+
+### 6. Custom service modal AI Write missing technician notes / vehicle context
+`setupCustomServiceModalEventListeners()` calls `handleAiWrite(nameInput, recInput, explTextarea, aiWriteBtn)` — only 4 args. Missing:
+- 5th arg: `technicianNotesEl` (the `custom-service-technician-notes` textarea)
+- 6th arg: `vehicleContext` object with vehicleInfo and mileage
+
+Without these, the LLM prompt never includes \"Technician's internal notes:\" or
+\"Vehicle:\" / \"Current mileage:\" context. The AI writes generic explanations
+instead of incorporating the technician's specific observations.
+
+**Fix**: Match the edit-service call site pattern:
+```js
+const technicianNotesEl = document.getElementById('custom-service-technician-notes');
+const vehicleCtx = {
+    vehicleInfo: document.getElementById('vehicleInfo')?.value || '',
+    mileage: document.getElementById('mileage')?.value || '',
+    maintenanceInterval: null
+};
+await handleAiWrite(nameInput, recInput, explTextarea, aiWriteBtn, technicianNotesEl, vehicleCtx);
+```
+
+## Diagnostic checklist
+
+1. `grep -n "ai-write-btn" repair-orders.html` — verify button ID exists
+2. Check console for "Missing required elements for AI Write" log
+3. Check if `handleAiWrite` is actually imported (line 5 of quote-tab-manager.js)
+4. Verify the LLM endpoint is reachable: `curl -sk https://localhost/llm/v1/chat/completions`
+5. Check nginx error log for 403 on shared modules