docs: research member notes ecosystem

2026-02-13 11:14:28 +08:00
parent 23573d3ebc
commit c962514532
6 changed files with 1980 additions and 0 deletions
--- a/.planning/research/PITFALLS_INLINE_AJAX.md
+++ b/.planning/research/PITFALLS_INLINE_AJAX.md
@@ -0,0 +1,647 @@
+# Domain Pitfalls: Inline AJAX Implementation
+
+**Domain:** Inline AJAX CRUD features in Laravel 10 Blade + Alpine.js admin pages
+**Researched:** 2026-02-13
+**Confidence:** HIGH
+
+**Note:** This document focuses specifically on **implementation pitfalls for inline AJAX features** with pagination. See `PITFALLS.md` for domain-level member notes system pitfalls.
+
+## Critical Pitfalls
+
+### Pitfall 1: Missing CSRF Token in AJAX Requests
+
+**What goes wrong:**
+POST/PATCH/DELETE requests fail with 419 status code, appearing as silent failures or generic errors in console.
+
+**Why it happens:**
+Developers forget to include CSRF token in fetch/Axios headers when adding inline AJAX, especially when copying patterns from API routes or SPA examples. Laravel's `web` middleware requires CSRF validation by default.
+
+**Consequences:**
+- All write operations fail silently
+- Users see loading states that never complete
+- Error messages are generic "Page Expired" instead of actionable feedback
+- Difficult to debug if console isn't open
+
+**Prevention:**
+1. Add meta tag to layout: `<meta name="csrf-token" content="{{ csrf_token() }}">`
+2. For Alpine.js fetch calls, include header: `'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content`
+3. If using Axios (from Laravel's bootstrap.js), it handles XSRF-TOKEN automatically
+4. Never exclude admin routes from CSRF protection
+
+**Detection:**
+- 419 status codes in browser Network tab
+- Console errors about token mismatch
+- Operations work in Postman but not in UI
+
+**Phase to address:**
+Phase 1: Backend API + Frontend scaffolding - Include CSRF handling in initial Alpine.js component template.
+
+**Sources:**
+- [Laravel CSRF Protection Documentation](https://laravel.com/docs/10.x/csrf) (HIGH confidence)
+- [PostSrc: CSRF Token Setup in Alpine.js](https://postsrc.com/code-snippets/set-up-csrf-token-in-alpine-js-within-laravel-application) (MEDIUM confidence)
+
+---
+
+### Pitfall 2: Missing Alpine.initTree() After Dynamic Content Injection
+
+**What goes wrong:**
+After pagination or AJAX content reload, Alpine.js directives stop working. Newly inserted DOM elements don't have Alpine reactivity - buttons don't respond, x-show doesn't toggle, x-model doesn't bind.
+
+**Why it happens:**
+Alpine.js initializes on page load but doesn't automatically bind to dynamically inserted HTML. When pagination replaces table rows or AJAX appends new content, developers forget to reinitialize Alpine for the new DOM.
+
+**Consequences:**
+- Page 1 works fine, but page 2+ has broken interactions
+- Newly added notes/rows appear but can't be edited/deleted
+- Users must refresh entire page to restore functionality
+- Inconsistent UX between static and dynamic content
+
+**Prevention:**
+After inserting HTML via AJAX, always call:
+```javascript
+// After innerHTML or DOM manipulation
+Alpine.initTree(document.querySelector('.target-container'));
+```
+
+Better: Use Alpine's built-in reactivity (x-for loops) instead of manual DOM manipulation.
+
+**Detection:**
+- Alpine directives (x-data, @click) visible in inspect but not functioning
+- Works on initial load but breaks after any AJAX update
+- Console shows no errors but clicks do nothing
+
+**Phase to address:**
+Phase 2: Inline quick-add - Document pattern in component implementation guide. Test pagination explicitly.
+
+**Sources:**
+- [Fixing Reactivity and DOM Lifecycle Issues in Alpine.js](https://www.mindfulchase.com/explore/troubleshooting-tips/front-end-frameworks/fixing-reactivity-and-dom-lifecycle-issues-in-alpine-js-applications.html) (MEDIUM confidence)
+- [GitHub Alpine.js Discussion #857](https://github.com/alpinejs/alpine/discussions/857) (MEDIUM confidence)
+
+---
+
+### Pitfall 3: 422 Validation Errors Displayed as Generic "Error" Messages
+
+**What goes wrong:**
+Laravel returns specific validation errors (e.g., "Note content required", "Note too long") but UI shows generic "Error saving note" without field-specific feedback.
+
+**Why it happens:**
+Developers catch the 422 response but don't parse the `errors` object structure. They display `response.statusText` or generic messages instead of extracting field-specific errors from the JSON payload.
+
+**Consequences:**
+- Users don't know what to fix
+- Repeated submission failures frustrate users
+- Looks like a bug rather than validation issue
+- Undermines trust in the system
+
+**Prevention:**
+1. Laravel sends validation errors as JSON with 422 status:
+```json
+{
+  "message": "The note content field is required.",
+  "errors": {
+    "note_content": ["The note content field is required."]
+  }
+}
+```
+
+2. Parse and display field-specific errors:
+```javascript
+.catch(error => {
+  if (error.response && error.response.status === 422) {
+    const errors = error.response.data.errors;
+    // Display errors next to corresponding fields
+    this.errors = errors;
+  }
+})
+```
+
+3. Use Alpine.js reactive `errors` object to show messages inline with Traditional Chinese translations.
+
+**Detection:**
+- Users report "unclear error messages"
+- All errors show same generic text
+- Network tab shows detailed errors but UI doesn't
+
+**Phase to address:**
+Phase 2: Inline quick-add - Build error handling into initial component. Include validation error display in acceptance criteria.
+
+**Sources:**
+- [Laravel Validation Documentation](https://laravel.com/docs/10.x/validation) (HIGH confidence)
+- [Laravel AJAX Form Validation Tutorial](https://webjourney.dev/laravel-9-ajax-form-validation-and-display-error-messages) (MEDIUM confidence)
+
+---
+
+### Pitfall 4: Memory Leaks from Unremoved Alpine Components in Pagination
+
+**What goes wrong:**
+As users navigate through paginated results, each page load leaves orphaned Alpine.js components in memory. After 20-30 page changes, browser becomes sluggish, especially on resource-constrained devices.
+
+**Why it happens:**
+Alpine.js components created for each row aren't explicitly destroyed when pagination replaces content. Event listeners and reactive observers accumulate as "detached DOM nodes" in memory.
+
+**Consequences:**
+- Browser tabs slow down over time
+- Memory usage grows unbounded
+- Mobile/tablet users hit memory limits faster
+- Admin users working long sessions are most affected
+
+**Prevention:**
+1. Prefer Alpine's x-for over manual DOM replacement (Alpine handles cleanup):
+```blade
+<template x-for="member in members" :key="member.id">
+  <!-- Alpine manages lifecycle -->
+</template>
+```
+
+2. If manually replacing content, use x-effect instead of x-init for side effects (ensures automatic teardown).
+
+3. Monitor detached DOM nodes in Chrome DevTools > Memory > Take Heap Snapshot > Search "Detached".
+
+4. For SPA-like navigation, implement cleanup hooks before replacing content.
+
+**Detection:**
+- Chrome DevTools Memory Profiler shows growing heap
+- Detached DOM nodes increase after each pagination
+- UI becomes sluggish after extended use
+- Memory warnings on mobile devices
+
+**Phase to address:**
+Phase 2: Inline quick-add - Choose x-for pattern from start. Add memory leak testing to acceptance criteria.
+
+**Sources:**
+- [Alpine.js Memory Leak Issues on GitHub](https://github.com/alpinejs/alpine/issues/2140) (HIGH confidence)
+- [Troubleshooting Alpine.js in Enterprise Front-End Architectures](https://www.mindfulchase.com/explore/troubleshooting-tips/front-end-frameworks/troubleshooting-alpine-js-in-enterprise-front-end-architectures.html) (MEDIUM confidence)
+
+---
+
+### Pitfall 5: Optimistic UI Updates Without Rollback on Failure
+
+**What goes wrong:**
+Note appears added immediately in UI, but if server request fails (validation, network, permissions), the note remains visible even though it wasn't saved. User navigates away thinking note was saved.
+
+**Why it happens:**
+Developers implement optimistic UI for snappy UX (add note to list immediately) but forget to handle rollback when server rejects the request.
+
+**Consequences:**
+- Data loss: User believes note was saved but it's gone on refresh
+- Trust erosion: System appears to lie about save status
+- Duplicate submissions: User re-adds "missing" note creating duplicates
+- Worst case: Important notes lost (especially critical for member admin context)
+
+**Prevention:**
+1. Store previous state before optimistic update:
+```javascript
+// Before optimistic update
+const previousState = [...this.notes];
+
+// Add note optimistically
+this.notes.push(newNote);
+
+// If server fails
+.catch(error => {
+  // Rollback to previous state
+  this.notes = previousState;
+  // Show non-intrusive error
+  this.showError('儲存失敗，請重試');
+});
+```
+
+2. Alternative: Don't use optimistic updates for critical data like notes. Show loading state, then add on success.
+
+3. Add visual indicators: Pending notes show spinner/opacity until confirmed.
+
+**Detection:**
+- User reports "saved data disappeared"
+- Testing network throttling/failures shows inconsistent state
+- Refresh reveals missing items user thought were saved
+
+**Phase to address:**
+Phase 2: Inline quick-add - Decision point: Optimistic (with rollback) vs. Conservative (loading state). Document chosen pattern and rationale.
+
+**Sources:**
+- [Optimistic UI in Rails with Inertia](https://evilmartians.com/chronicles/optimistic-ui-in-rails-with-optimism-and-inertia) (MEDIUM confidence - Rails but patterns apply)
+- [Understanding Optimistic UI and React's useOptimistic Hook](https://blog.logrocket.com/understanding-optimistic-ui-react-useoptimistic-hook/) (MEDIUM confidence - React but architectural patterns transfer)
+
+---
+
+### Pitfall 6: Race Conditions on Concurrent Edit/Delete
+
+**What goes wrong:**
+User opens member in two tabs. Tab 1 deletes a note while Tab 2 is editing same note. Tab 2's save succeeds, recreating the deleted note. Or two admins edit same note simultaneously, last write wins and overwrites the other's changes.
+
+**Why it happens:**
+No locking mechanism or version checking. Laravel processes each request independently. Last request to complete overwrites database state regardless of what changed in between.
+
+**Consequences:**
+- Data corruption: Changes silently lost
+- User confusion: "I just deleted that!"
+- Audit trail breaks: Delete logged but note reappears
+- Multi-admin scenarios especially vulnerable
+
+**Prevention:**
+1. **Pessimistic Locking** (simple but blocks concurrent access):
+```php
+$note = MemberNote::where('id', $id)->lockForUpdate()->first();
+// Update within transaction
+```
+
+2. **Optimistic Locking** (better for this use case):
+Add `version` column, increment on each update:
+```php
+// Check version matches before update
+$updated = MemberNote::where('id', $id)
+    ->where('version', $request->version)
+    ->update(['content' => $request->content, 'version' => DB::raw('version + 1')]);
+
+if (!$updated) {
+    return response()->json(['error' => '此筆記已被他人更新，請重新整理'], 409);
+}
+```
+
+3. **Rate Limiting**: Prevent rapid-fire requests from same user:
+```php
+Route::post('/notes', [NoteController::class, 'store'])
+    ->middleware('throttle:10,1'); // 10 requests per minute
+```
+
+4. **UI-Level Prevention**: Disable edit/delete buttons while request pending.
+
+**Detection:**
+- User reports "changes disappeared"
+- Testing with two browser tabs shows last-write-wins behavior
+- Audit logs show delete then recreate of same record
+
+**Phase to address:**
+Phase 2: Inline quick-add - Add basic request throttling. Consider optimistic locking for Phase 3+ if multi-admin concurrent editing is common.
+
+**Sources:**
+- [Handling Race Conditions in Laravel: Pessimistic Locking](https://ohansyah.medium.com/handling-race-conditions-in-laravel-pessimistic-locking-d88086433154) (MEDIUM confidence)
+- [Prevent Race Conditions in Laravel with Atomic Locks](https://www.twilio.com/en-us/blog/developers/tutorials/prevent-race-conditions-laravel-atomic-locks) (HIGH confidence)
+- [Laravel Rate Limiting Documentation](https://laravel.com/docs/12.x/rate-limiting) (HIGH confidence)
+
+---
+
+## Moderate Pitfalls
+
+### Pitfall 7: Nested x-data Scope Conflicts
+
+**What goes wrong:**
+Member row has `x-data="memberRow()"` and inline note form has `x-data="noteForm()"`. Form can't access parent row's member ID, or parent's `showForm` toggle doesn't work from child.
+
+**Why it happens:**
+Alpine.js v2 vs v3 behavior differs. In v3, nested components can access parent scope, but explicit scoping can override. Developers coming from Vue/React expect automatic scope inheritance.
+
+**Prevention:**
+1. Use single x-data at row level with all needed state:
+```blade
+<tr x-data="{
+  memberId: {{ $member->id }},
+  showNoteForm: false,
+  noteContent: '',
+  saveNote() { /* has access to memberId */ }
+}">
+```
+
+2. For complex components, use Alpine.store() for shared state across components.
+
+3. Test nested interactions explicitly - don't assume scope works.
+
+**Detection:**
+- Console errors: "undefined is not a function"
+- Form submits without required data (like member_id)
+- Toggle buttons affect wrong rows
+
+**Phase to address:**
+Phase 2: Inline quick-add - Design component scope structure upfront. Document in implementation guide.
+
+**Sources:**
+- [Alpine.js x-data Directive Documentation](https://alpinejs.dev/directives/data) (HIGH confidence)
+- [Nested Components with Alpine.js v2 and v3](https://docs.hyva.io/hyva-themes/writing-code/patterns/nested-components-with-alpine-js-v2.html) (MEDIUM confidence)
+
+---
+
+### Pitfall 8: Dark Mode Styles Missing on Dynamic Content
+
+**What goes wrong:**
+Inline note form injected via AJAX has proper light mode styles but dark mode styles don't apply. Form is unreadable in dark mode.
+
+**Why it happens:**
+Developer adds Tailwind classes to dynamic HTML but forgets `dark:` variants. Existing page elements have dark mode tested, but AJAX content is only tested in light mode.
+
+**Consequences:**
+- Poor UX for dark mode users (admin users often prefer dark mode)
+- Accessibility issues: Contrast ratios fail
+- Professional appearance suffers
+- Inconsistent with rest of application
+
+**Prevention:**
+1. Every input/button/text element needs dark mode variant:
+```blade
+class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100"
+```
+
+2. Create component library with dark mode built-in (don't rewrite classes each time).
+
+3. Test all AJAX flows in dark mode as part of acceptance criteria.
+
+4. Use existing dark mode patterns from project (see budgets/edit.blade.php as reference).
+
+**Detection:**
+- Toggle dark mode, test all inline features
+- Visual regression testing in dark mode
+- User reports "can't read form in dark mode"
+
+**Phase to address:**
+Phase 2: Inline quick-add - Add dark mode testing to DoD. Reference existing dark mode patterns in CLAUDE.md.
+
+**Sources:**
+- Project codebase: `/resources/views/admin/budgets/edit.blade.php` uses `dark:bg-gray-700 dark:border-gray-600 dark:text-gray-100` consistently (HIGH confidence)
+- [How to Add Dark Mode Switcher to Alpine.js and Tailwind CSS](https://joshsalway.com/how-to-add-a-dark-mode-selector-to-your-alpinejs-and-tailwind-css-app/) (MEDIUM confidence)
+
+---
+
+### Pitfall 9: SQLite vs MySQL Text Field Differences Breaking Dev/Prod Parity
+
+**What goes wrong:**
+Notes save fine in SQLite (dev) but fail in MySQL (prod) with charset errors or truncation. Or migration works locally but fails on production.
+
+**Why it happens:**
+SQLite treats TEXT and VARCHAR identically (both become TEXT). MySQL distinguishes them with different limits and charset handling. Migration uses `->text()` which behaves differently across databases.
+
+**Consequences:**
+- "Works on my machine" syndrome
+- Production deployment failures
+- Emergency hotfixes for DB schema
+- Long notes truncated without warning
+
+**Prevention:**
+1. Use consistent column types in migrations:
+```php
+// For notes up to 65K characters
+$table->text('content'); // Same on both
+
+// Or explicitly
+$table->string('content', 500); // Clear limit
+```
+
+2. Test migrations on both SQLite AND MySQL before deploying:
+```bash
+# Test on SQLite (dev)
+php artisan migrate:fresh --seed
+
+# Test on MySQL (staging/prod clone)
+DB_CONNECTION=mysql php artisan migrate:fresh --seed
+```
+
+3. Add validation max length that works on both:
+```php
+'content' => 'required|string|max:65000', // Under both limits
+```
+
+4. Be aware: MySQL VARCHAR max is 65,535 bytes (not characters) - multibyte chars (Chinese!) reduce limit.
+
+**Detection:**
+- Charset errors in production logs
+- Notes saved in dev disappear in prod
+- Migration works locally, fails on deploy
+
+**Phase to address:**
+Phase 1: Backend API - Define note schema with explicit limits. Test migration on MySQL early.
+
+**Sources:**
+- [Laravel Migrations: String vs Text](https://laravel.io/forum/02-10-2014-string-vs-text-in-schema) (MEDIUM confidence)
+- [SQLite in Laravel: Comprehensive Guide](https://tutorial.sejarahperang.com/2026/02/sqlite-in-laravel-comprehensive-guide.html) (MEDIUM confidence)
+- [MySQL VARCHAR vs TEXT in Laravel](https://copyprogramming.com/howto/laravel-migrations-string-mysql-varchar-vs-text) (MEDIUM confidence)
+
+---
+
+### Pitfall 10: Missing Authorization Checks in AJAX Endpoints
+
+**What goes wrong:**
+Frontend checks permissions (e.g., only membership_manager can add notes) but AJAX endpoint doesn't verify. Malicious user crafts POST request in console and bypasses UI restrictions.
+
+**Why it happens:**
+Developer assumes UI permission checks are sufficient. Focuses on happy path where only authorized users see the form. Forgets client-side checks are advisory only.
+
+**Consequences:**
+- Security vulnerability: Unauthorized data modification
+- Audit trail inconsistency
+- Compliance issues (especially for NPO with member data)
+- Privilege escalation attack vector
+
+**Prevention:**
+1. Always authorize in controller:
+```php
+public function store(Request $request)
+{
+    $this->authorize('create', MemberNote::class);
+    // Or
+    if (!auth()->user()->can('manage_members')) {
+        abort(403, '無權限新增筆記');
+    }
+    // Then process request
+}
+```
+
+2. Use Form Request classes with authorization:
+```php
+public function authorize()
+{
+    return $this->user()->can('manage_members');
+}
+```
+
+3. Test authorization by crafting direct API calls in browser console.
+
+**Detection:**
+- Security audit/penetration testing
+- Try endpoint calls from unauthorized account
+- Check audit logs for unexpected actions
+
+**Phase to address:**
+Phase 1: Backend API - Include authorization in controller from start. Add to code review checklist.
+
+**Sources:**
+- Laravel project pattern: Existing controllers use middleware(['auth', 'admin']) but may lack granular permission checks (MEDIUM confidence - based on codebase review)
+- Standard security practice (HIGH confidence)
+
+---
+
+## Minor Pitfalls
+
+### Pitfall 11: Event Bubbling Breaking Pagination/Row Clicks
+
+**What goes wrong:**
+Clicking "Add Note" button also triggers row click event, expanding/collapsing row or navigating to detail page.
+
+**Why it happens:**
+Event propagates from button → row → table. Alpine @click handlers at multiple levels all fire unless explicitly stopped.
+
+**Prevention:**
+Use `.stop` modifier to prevent event bubbling:
+```blade
+<button @click.stop="showNoteForm = true">新增筆記</button>
+```
+
+**Detection:**
+- Clicking button triggers unintended parent actions
+- Users report "can't click button without row expanding"
+
+**Phase to address:**
+Phase 2: Inline quick-add - Use `.stop` modifier by default on all inline action buttons.
+
+**Sources:**
+- [Alpine.js Event Modifiers](https://scriptbinary.com/alpinejs/event-handling-dynamic-interactions-alpinejs) (HIGH confidence)
+
+---
+
+### Pitfall 12: Loading States Cause Layout Shift (CLS)
+
+**What goes wrong:**
+"Add Note" button is 100px tall. On click, it's replaced by form that's 200px tall. Entire member list below jumps down, disorienting users.
+
+**Why it happens:**
+No reserved space for expanded state. Developers focus on functionality, forget layout stability.
+
+**Prevention:**
+1. Reserve space with min-height or placeholder:
+```blade
+<div class="min-h-[200px]" x-show="showNoteForm">
+  <!-- Form content -->
+</div>
+```
+
+2. Use Alpine transitions to smooth expansion:
+```blade
+x-transition:enter="transition ease-out duration-200"
+```
+
+**Detection:**
+- Visual jump when clicking buttons
+- Layout shift metrics in Lighthouse/Core Web Vitals
+
+**Phase to address:**
+Phase 2: Inline quick-add - Add transition/min-height to component template. Minor UX polish.
+
+**Sources:**
+- UX best practice (HIGH confidence)
+
+---
+
+## Technical Debt Patterns
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| Skip AJAX error handling | Faster initial implementation | Users see broken UI on errors, hard to debug | Never - errors are inevitable |
+| Generic "Error occurred" messages | Less code, no i18n needed | Users can't self-correct, support burden increases | Never for MVP+ |
+| No rate limiting on endpoints | Simpler code | Vulnerable to abuse, server overload from bugs (e.g., infinite loops) | Only in private/demo environments |
+| Manual DOM manipulation instead of x-for | More control, familiar jQuery pattern | Memory leaks, complexity, hard to maintain | Never - Alpine handles it better |
+| Skip dark mode testing | Half the test cases | Half your users (admins) have poor UX | Never - dark mode is project requirement |
+| Optimistic UI without rollback | Snappy UX with less code | Silent data loss on failures | Never for critical data like notes |
+| Client-side only permission checks | Easier than backend auth | Security vulnerability | Never - always validate server-side |
+
+## Performance Traps
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| Fetching full member list for autocomplete | Works fine locally | Paginate/search endpoint, fetch as user types | >100 members |
+| Re-rendering entire table on note add | Smooth with 10 rows | Use targeted DOM updates, Alpine x-for with :key | >50 members/page |
+| No request debouncing on search | Responsive to every keystroke | Debounce 300ms, cancel previous requests | Any real usage |
+| Loading all notes upfront | Simple implementation | Lazy load notes on row expand, paginate notes per member | >20 notes/member or >50 members |
+
+## Security Mistakes
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| No CSRF token | CSRF attacks, unauthorized actions | Always include X-CSRF-TOKEN header |
+| Client-side only permission checks | Privilege escalation | Authorize in controller/middleware |
+| No rate limiting | DoS, brute force, bug amplification | Throttle middleware (e.g., 10/min per user) |
+| Exposing sensitive data in Alpine x-data | Data visible in HTML source | Only include IDs in frontend, fetch details server-side |
+| No XSS escaping in note content | Stored XSS attacks | Use `{{ }}` not `{!! !!}`, sanitize on save |
+| No input validation on AJAX endpoints | Data corruption, injection attacks | Validate with Form Requests, same rules as traditional forms |
+
+## UX Pitfalls
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| No feedback while saving | User clicks again, creating duplicates | Show spinner, disable button during request |
+| Success state unclear | User unsure if save worked | Flash green border + check icon for 2 seconds |
+| Error hidden in console | User thinks it worked, confusion on refresh | Show inline red error message in Traditional Chinese |
+| Dark mode blind spot | Admin users (often dark mode) can't read form | Test both modes, use `dark:` variants consistently |
+| No keyboard shortcuts | Power users (admins) slow down | Escape to close, Enter to submit |
+| Form persists after save | User must manually close/clear | Auto-close form or clear fields on success |
+
+## "Looks Done But Isn't" Checklist
+
+- [ ] **AJAX write operations:** CSRF token included in headers - verify 419 doesn't occur
+- [ ] **Validation errors:** Field-specific errors displayed in Traditional Chinese - verify 422 responses show proper messages
+- [ ] **Pagination:** Alpine.js works on page 2+ - verify click handlers still work after pagination
+- [ ] **Dark mode:** All new elements readable in dark mode - verify `dark:` classes on inputs/text
+- [ ] **Authorization:** Endpoint checks permissions server-side - verify console API calls from unauthorized account fail with 403
+- [ ] **Error states:** All failure scenarios show user-facing messages - verify network errors, validation errors, auth errors display correctly
+- [ ] **Loading states:** Buttons disabled during requests - verify rapid clicking doesn't create duplicates
+- [ ] **SQLite/MySQL parity:** Migrations and queries work on both - verify on MySQL before production deploy
+- [ ] **Race conditions:** Concurrent actions don't corrupt data - verify two-tab test doesn't lose changes
+- [ ] **Memory leaks:** Repeated pagination doesn't accumulate detached nodes - verify Chrome Memory Profiler after 20+ page loads
+
+## Recovery Strategies
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| Missing CSRF token | LOW | Add meta tag + header, redeploy frontend |
+| No Alpine.initTree() | LOW | Add call after DOM updates, test pagination |
+| Generic error messages | LOW | Parse 422 response, map to fields with Chinese text |
+| Memory leaks from pagination | MEDIUM | Refactor to x-for pattern, may need significant HTML changes |
+| No optimistic rollback | MEDIUM | Add state backup before update, rollback on error |
+| Race conditions | HIGH | Add optimistic locking (version column + migration), update all write endpoints |
+| No authorization checks | HIGH | Add authorize() to all endpoints, security audit all AJAX routes, test exhaustively |
+| SQLite/MySQL schema mismatch | HIGH | Write MySQL-compatible migration, coordinate deploy with DB update, possible data migration |
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| Missing CSRF token | Phase 1: Backend API | POST endpoint without token returns 419 |
+| Missing Alpine.initTree() | Phase 2: Inline quick-add | Pagination test: page 2 buttons still work |
+| Generic validation errors | Phase 2: Inline quick-add | Submit invalid note, see Chinese field-specific error |
+| Memory leaks | Phase 2: Inline quick-add | Memory profiler: no detached nodes after 20 page loads |
+| No optimistic rollback | Phase 2: Inline quick-add | Network throttling: failed save removes optimistic update |
+| Race conditions | Phase 2 (basic throttle) or Phase 3+ (optimistic locking) | Two-tab test: concurrent edits don't corrupt data |
+| Nested scope conflicts | Phase 2: Inline quick-add | Note form has access to member ID from parent row |
+| Dark mode missing | Phase 2: Inline quick-add | Toggle dark mode: all new elements readable |
+| SQLite/MySQL differences | Phase 1: Backend API | Run migration on both databases successfully |
+| No authorization checks | Phase 1: Backend API | Unauthorized console API call returns 403 |
+| Event bubbling | Phase 2: Inline quick-add | Click "Add Note" doesn't expand row |
+| Layout shift | Phase 2: Inline quick-add | Form expansion doesn't push content down |
+
+## Sources
+
+**Official Documentation (HIGH confidence):**
+- [Laravel 10.x CSRF Protection](https://laravel.com/docs/10.x/csrf)
+- [Laravel 10.x Validation](https://laravel.com/docs/10.x/validation)
+- [Laravel 12.x Rate Limiting](https://laravel.com/docs/12.x/rate-limiting)
+- [Alpine.js x-data Directive](https://alpinejs.dev/directives/data)
+
+**Community Resources (MEDIUM confidence):**
+- [PostSrc: CSRF Token Setup in Alpine.js within Laravel](https://postsrc.com/code-snippets/set-up-csrf-token-in-alpine-js-within-laravel-application)
+- [Inline Edit Example - Alpine AJAX](https://alpine-ajax.js.org/examples/inline-edit/)
+- [Laravel AJAX Form Validation Tutorial](https://webjourney.dev/laravel-9-ajax-form-validation-and-display-error-messages)
+- [Handling Race Conditions in Laravel: Pessimistic Locking](https://ohansyah.medium.com/handling-race-conditions-in-laravel-pessimistic-locking-d88086433154)
+- [Prevent Race Conditions in Laravel with Atomic Locks](https://www.twilio.com/en-us/blog/developers/tutorials/prevent-race-conditions-laravel-atomic-locks)
+- [Fixing Reactivity and DOM Lifecycle Issues in Alpine.js](https://www.mindfulchase.com/explore/troubleshooting-tips/front-end-frameworks/fixing-reactivity-and-dom-lifecycle-issues-in-alpine-js-applications.html)
+- [Troubleshooting Alpine.js in Enterprise Front-End Architectures](https://www.mindfulchase.com/explore/troubleshooting-tips/front-end-frameworks/troubleshooting-alpine-js-in-enterprise-front-end-architectures.html)
+- [Alpine.js Memory Leak Issues - GitHub #2140](https://github.com/alpinejs/alpine/issues/2140)
+- [How to Add Dark Mode Switcher to Alpine.js and Tailwind CSS](https://joshsalway.com/how-to-add-a-dark-mode-selector-to-your-alpinejs-and-tailwind-css-app/)
+- [SQLite in Laravel: Comprehensive Guide](https://tutorial.sejarahperang.com/2026/02/sqlite-in-laravel-comprehensive-guide.html)
+- [MySQL VARCHAR vs TEXT in Laravel](https://copyprogramming.com/howto/laravel-migrations-string-mysql-varchar-vs-text)
+- [Nested Components with Alpine.js v2](https://docs.hyva.io/hyva-themes/writing-code/patterns/nested-components-with-alpine-js-v2.html)
+
+**Codebase Review (HIGH confidence):**
+- Project codebase: `/resources/views/admin/budgets/edit.blade.php` - demonstrates Alpine.js with dark mode patterns
+- Project codebase: `/resources/views/components/dropdown.blade.php` - demonstrates x-data scope and event handling
+- Project CLAUDE.md - confirms dark mode requirement, Traditional Chinese UI, SQLite dev/MySQL prod setup
+
+---
+
+*Pitfalls research for: Inline AJAX implementation in Laravel 10 Blade + Alpine.js admin*
+*Researched: 2026-02-13*