usher-manage-stack/.planning/phases/03-note-history-display/03-01-SUMMARY.md

---
phase: 03-note-history-display
plan: 01
subsystem: member-notes
tags: [ui, alpine.js, note-history, search, inline-expansion]

dependency_graph:
  requires:
    - "02-01 (Inline quick-add UI with per-row Alpine.js scope)"
  provides:
    - "Expandable note history panel with lazy loading and search"
    - "Alpine.js collapse plugin integration"
    - "Client-side note filtering by content/author"
  affects:
    - "resources/views/admin/members/index.blade.php (history panel UI)"
    - "app/Http/Controllers/Admin/MemberNoteController.php (ordering fix)"

tech_stack:
  added:
    - "@alpinejs/collapse v3.x"
  patterns:
    - "Alpine.js x-collapse directive for smooth expand/collapse animation"
    - "Lazy loading: notes fetched only on first panel open"
    - "Client-side search via computed property (filteredNotes)"
    - "Cache synchronization: inline form updates history panel immediately"

key_files:
  created: []
  modified:
    - "resources/js/app.js (collapse plugin registration)"
    - "app/Http/Controllers/Admin/MemberNoteController.php (latest ordering + eager load optimization)"
    - "resources/views/admin/members/index.blade.php (history panel UI with template wrapper)"
    - "tests/Feature/Admin/MemberNoteTest.php (+4 new tests)"
    - "package.json (@alpinejs/collapse dependency)"

decisions:
  - name: "Use Alpine.js collapse plugin instead of custom CSS transitions"
    rationale: "Provides smooth, accessible expand/collapse with minimal code"
    alternatives: "Custom CSS transitions (more code, harder to maintain)"

  - name: "Wrap main row + expansion row in <template x-data>"
    rationale: "Allows sibling <tr> elements to share Alpine.js state while maintaining table structure"
    alternatives: "Nested row (invalid HTML), separate x-data scopes (can't share state)"

  - name: "Client-side search via computed property"
    rationale: "Notes dataset is small (typically <20 notes/member), no need for server-side filtering"
    alternatives: "Server-side search (overkill for small datasets, adds latency)"

  - name: "Fix controller ordering from implicit to explicit latest()"
    rationale: "Prevents future bugs if database/seeder changes affect insertion order"
    type: "deviation-rule-1-bug-fix"

  - name: "Eager load only author id+name instead of full user model"
    rationale: "Reduces payload size, only needed fields for display"
    type: "deviation-rule-2-optimization"

metrics:
  tasks_completed: 2
  tests_added: 4
  tests_total: 11
  files_modified: 5
  duration_minutes: 2.2
  completed_at: "2026-02-13"
---

# Phase 03 Plan 01: Expandable Note History Panel with Search

**One-liner:** Clickable note count badge expands inline history panel with search filtering, showing all notes newest-first with author attribution and formatted timestamps.

## What Was Built

### Core Functionality

1. **Expandable History Panel**
   - Note count badge is now a clickable button that toggles expansion panel
   - Panel appears as a new `<tr>` row below the member row using `x-collapse` animation
   - Loading spinner shown while fetching notes (lazy load on first open)
   - Panel collapses cleanly when badge clicked again, search query auto-resets

2. **Note Display**
   - Notes displayed newest first (explicit `latest('created_at')` in controller)
   - Author name and formatted datetime shown: `{author} · {YYYY年MM月DD日 HH:mm}`
   - Content preserves line breaks with `whitespace-pre-line`
   - Left border accent (blue) for visual separation
   - Scrollable container (max-h-64) when >5-6 notes

3. **Search Filtering**
   - Search input appears only when notes exist
   - Filters notes by content OR author name (case-insensitive)
   - Client-side filtering via Alpine.js computed property `filteredNotes`
   - Shows "找不到符合的備忘錄" when search has no matches

4. **Empty States**
   - "尚無備註" when member has no notes
   - "找不到符合的備忘錄" when search yields no results

5. **Cache Synchronization**
   - After adding note via inline form, new note appears in history panel immediately
   - No re-fetch required (uses `this.notes.unshift(response.data.note)`)

### Technical Implementation

**Alpine.js Collapse Plugin**
```javascript
import collapse from '@alpinejs/collapse';
Alpine.plugin(collapse);
```

**Per-Row State Extended**
Added to existing x-data scope:
- `historyOpen: false` — panel visibility
- `notes: []` — cached note data
- `notesLoaded: false` — has data been fetched
- `isLoadingNotes: false` — loading state
- `searchQuery: ''` — search input value
- `toggleHistory()` — open/close + lazy load
- `loadNotes()` — fetch from API
- `filteredNotes` — computed property for search
- `formatDateTime()` — format to Traditional Chinese

**Controller Optimization**
```php
// Before (implicit ordering, full user model)
$notes = $member->notes()->with('author')->get();

// After (explicit ordering, minimal fields)
$notes = $member->notes()->with('author:id,name')->latest('created_at')->get();
```

**Template Structure**
```html
<template x-data="{ ...all state... }">
    <tr><!-- Main member row --></tr>
    <tr x-show="historyOpen" x-collapse><!-- Expansion panel --></tr>
</template>
```

Using `<template>` wrapper allows sibling `<tr>` elements to share Alpine.js state while maintaining valid table HTML.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed controller ordering from implicit to explicit**
- **Found during:** Task 1 implementation
- **Issue:** Controller used `$member->notes()->with('author')->get()` with no explicit ordering. This worked only because SQLite insertion order happened to match newest-first. Would break if seeder or database changed.
- **Fix:** Added explicit `->latest('created_at')` to guarantee newest-first ordering.
- **Files modified:** `app/Http/Controllers/Admin/MemberNoteController.php`
- **Commit:** c0ebbdb

**2. [Rule 2 - Optimization] Narrowed eager load to only needed fields**
- **Found during:** Task 1 implementation
- **Issue:** Controller loaded full `author` user model, but view only needs `id` and `name`.
- **Fix:** Changed `->with('author')` to `->with('author:id,name')` to reduce payload size.
- **Files modified:** `app/Http/Controllers/Admin/MemberNoteController.php`
- **Commit:** c0ebbdb

No architectural changes needed. No user decisions required.

## Testing

### New Tests Added (4)

1. **`test_notes_index_returns_author_name_and_created_at`**
   - Verifies API returns properly structured data for display
   - Tests multiple authors are represented correctly

2. **`test_notes_index_returns_empty_array_for_member_with_no_notes`**
   - Verifies empty state data contract

3. **`test_member_list_renders_history_panel_directives`**
   - Verifies Blade view contains all necessary Alpine.js directives
   - Checks for: `toggleHistory`, `historyOpen`, `x-collapse`, `searchQuery`, `filteredNotes`, etc.

4. **`test_store_note_returns_note_with_author_for_cache_sync`**
   - Verifies store endpoint returns complete note data needed for frontend cache sync
   - Ensures `author.name` is included in response

### Test Results

```
✓ All 11 tests pass (7 existing + 4 new)
✓ 86 assertions
✓ Duration: 0.72s
```

## Verification Checklist

- [x] `npm run build` completes without errors
- [x] `php artisan test --filter=MemberNoteTest` — all 11 tests pass
- [x] Blade view has clickable badge with `aria-expanded` and `aria-controls`
- [x] Expansion panel uses `x-collapse` directive
- [x] Search input present with `x-model="searchQuery"`
- [x] Empty state text "尚無備註" present
- [x] No-results state "找不到符合的備忘錄" present
- [x] Controller index method uses `->latest('created_at')`
- [x] Controller eager loads only `author:id,name`
- [x] `submitNote()` has `this.notes.unshift(response.data.note)` cache sync
- [x] `formatDateTime` method exists in x-data scope

## Success Criteria Met

- [x] Admin can click note count badge to expand inline panel showing all notes for that member
- [x] Notes display newest first with author name and formatted datetime (YYYY年MM月DD日 HH:mm)
- [x] Panel shows "尚無備註" when member has no notes
- [x] Admin can filter notes by text content or author name via search input
- [x] Closing panel resets search query; other member rows unaffected
- [x] Adding a note via inline form immediately appears in the history panel without re-fetch
- [x] All 11 MemberNoteTest tests pass

## Files Changed

### Modified (5)

| File | Changes | Lines |
|------|---------|-------|
| `resources/js/app.js` | Added collapse plugin import and registration | +2 |
| `app/Http/Controllers/Admin/MemberNoteController.php` | Fixed ordering + eager load optimization | ~1 |
| `resources/views/admin/members/index.blade.php` | Added history panel UI with template wrapper | +65 |
| `tests/Feature/Admin/MemberNoteTest.php` | Added 4 new feature tests | +83 |
| `package.json` | Added @alpinejs/collapse dependency | +1 |

### Created (0)

None — plan execution was fully incremental.

## Commits

| Hash | Type | Message |
|------|------|---------|
| c0ebbdb | feat | Add expandable note history panel with search |
| 46973c2 | test | Add feature tests for note history panel |

## Integration Points

**Consumes:**
- `GET /admin/members/{member}/notes` — notes index endpoint (Phase 01)
- `POST /admin/members/{member}/notes` — store endpoint (Phase 01)
- `$member->notes_count` — eager loaded count from Phase 02

**Provides:**
- Expandable history panel UI component (completes member note feature)
- Client-side search pattern (can be reused for other list views)

**Affects:**
- Member list page now has two interactive note features: inline add form (Phase 02) + history panel (Phase 03)
- Both features share Alpine.js state via template wrapper pattern

## Known Limitations

1. **Search is client-side only** — All notes loaded upfront, then filtered in browser. Fine for typical use (most members have <20 notes), but could become slow if a member has hundreds of notes.

2. **No pagination in history panel** — All notes rendered, scrollable container limits visible area. If note volume grows significantly, consider adding pagination or virtual scrolling.

3. **No real-time updates** — If another admin adds a note to the same member, current user won't see it until they close and re-open the panel (triggers fresh fetch). Could add WebSocket/polling if multi-user concurrency becomes important.

4. **Datetime formatting is client-side JavaScript** — Uses browser's Date object. Assumes server returns ISO 8601 timestamps. No timezone conversion (assumes all users in same timezone).

## Next Steps

**Immediate:**
- No further work needed for note history feature — complete as designed

**Future Enhancements (if needed):**
- Add edit/delete note actions in history panel (currently view-only)
- Add note categories/tags for better organization
- Add server-side search endpoint if note volume grows significantly
- Add real-time updates via WebSocket for multi-user scenarios

## Self-Check: PASSED

**Files Created:** None expected, none created ✓

**Files Modified:**
- [x] `/Users/gbanyan/Project/usher-manage-stack/resources/js/app.js` exists
- [x] `/Users/gbanyan/Project/usher-manage-stack/app/Http/Controllers/Admin/MemberNoteController.php` exists
- [x] `/Users/gbanyan/Project/usher-manage-stack/resources/views/admin/members/index.blade.php` exists
- [x] `/Users/gbanyan/Project/usher-manage-stack/tests/Feature/Admin/MemberNoteTest.php` exists
- [x] `/Users/gbanyan/Project/usher-manage-stack/package.json` exists

**Commits:**
```bash
✓ FOUND: c0ebbdb
✓ FOUND: 46973c2
```

All claims verified. Plan execution complete.