usher-manage-stack/.planning/ROADMAP.md

Roadmap: Member Notes System (會員備註系統)

Overview

This roadmap delivers inline note-taking capabilities for the Taiwan NPO admin member list, enabling quick annotation without page navigation. The implementation follows a foundation-first approach: database schema and backend API (Phase 1), followed by inline quick-add UI delivering core value (Phase 2), and concluding with full note history and display features (Phase 3). All work leverages the existing Laravel 10 + Alpine.js + Tailwind stack (Phase 3 adds @alpinejs/collapse, the official Alpine.js collapse plugin).

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Database Schema & Backend API - Foundation layer with polymorphic relationships
• Phase 2: Inline Quick-Add UI - Core value: quick annotation from member list
• Phase 3: Note History & Display - Full note viewing and search capabilities

Phase Details

Phase 1: Database Schema & Backend API

Goal: Establish database foundation and backend endpoints for note storage and retrieval

Depends on: Nothing (first phase)

Requirements: DATA-01, DATA-02, DATA-03, ACCS-01, ACCS-02

Success Criteria (what must be TRUE):

1. Notes table exists with polymorphic columns (notable_type, notable_id) and proper indexes
2. Admin can create a note via POST endpoint with text, member ID, and author auto-captured
3. Admin can retrieve all notes for a member via GET endpoint with author name and timestamps
4. Member list shows accurate note count for each member without N+1 queries
5. Note creation events are logged in audit trail with action and metadata

Plans: 2 plans

Plans:

• 01-01-PLAN.md — Database schema, Note model, Member relationship, morph map, factory
• 01-02-PLAN.md — MemberNoteController, routes, member list withCount, feature tests

Phase 2: Inline Quick-Add UI

Goal: Deliver core value — admins can annotate members inline without page navigation

Depends on: Phase 1

Requirements: NOTE-01, NOTE-02, NOTE-03, DISP-01, UI-01, UI-02, UI-03, ACCS-03

Success Criteria (what must be TRUE):

1. Each member row displays a note count badge showing number of notes
2. Admin can click an inline form to add a note without leaving the member list page
3. After submitting a note, the badge updates immediately and the form clears
4. Note submission shows loading state during AJAX request (disabled button)
5. Validation errors display in Traditional Chinese below the form field
6. All note UI elements work correctly in both light and dark mode
7. Quick-add functionality works across paginated member list pages (pages 1, 2, 3+)

Plans: 1 plan

Plans:

• 02-01-PLAN.md — Inline note form with Alpine.js, note count badge, AJAX submission, dark mode, and feature tests

Phase 3: Note History & Display

Goal: Complete the note feature with full history viewing and search

Depends on: Phase 2

Requirements: DISP-02, DISP-03, DISP-04

Success Criteria (what must be TRUE):

1. Admin can click the note count badge to expand an inline panel showing all notes for that member
2. Notes display in chronological order (newest first) with author name and formatted datetime
3. Panel shows empty state message ("尚無備註") when member has no notes
4. Admin can filter/search notes by text content within a member's note history
5. Expanded panel collapses cleanly without affecting other member rows

Plans: 1 plan

Plans:

• 03-01-PLAN.md — Expandable note history panel with search, collapse plugin, controller ordering fix, and feature tests

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3

Phase	Plans Complete	Status	Completed
1. Database Schema & Backend API	2/2	✓ Complete	2026-02-13
2. Inline Quick-Add UI	1/1	✓ Complete	2026-02-13
3. Note History & Display	1/1	✓ Complete	2026-02-13

---

Roadmap created: 2026-02-13 Last updated: 2026-02-13 (Phase 3 complete — all phases done)