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

**Defined:** 2026-02-13
**Core Value:** The chairman can annotate any member with timestamped notes directly from the member list, without navigating away from the page.

## v1 Requirements

### Note Creation

- [ ] **NOTE-01**: Admin can add a text note to any member inline from the member list (no page navigation)
- [ ] **NOTE-02**: Each note stores text content, author (current user), and creation datetime
- [ ] **NOTE-03**: Note submission uses AJAX (Axios) with CSRF protection — no page reload

### Note Display

- [ ] **DISP-01**: Each member row shows a note count badge indicating number of notes
- [ ] **DISP-02**: Clicking the badge expands an inline panel showing full note history (newest first)
- [ ] **DISP-03**: Each note displays author name and formatted datetime
- [ ] **DISP-04**: Notes can be filtered/searched by text content within a member's note history

### Data Layer

- [ ] **DATA-01**: Notes use polymorphic relationship (`notable_type`/`notable_id`) for future extensibility
- [ ] **DATA-02**: Migration includes proper indexes for member lookups and chronological ordering
- [ ] **DATA-03**: Member list uses eager loading (`withCount('notes')`) to prevent N+1 queries

### Access & Audit

- [ ] **ACCS-01**: All admin roles can view and write notes (reuses existing `admin` middleware)
- [ ] **ACCS-02**: Note creation is logged via `AuditLogger::log()`
- [ ] **ACCS-03**: Dark mode fully supported on all note UI elements

### UI/UX

- [ ] **UI-01**: All UI text in Traditional Chinese
- [ ] **UI-02**: Note quick-add works correctly across paginated member list pages
- [ ] **UI-03**: Alpine.js manages inline state (expand/collapse, form submission, loading states)

## v2 Requirements

### Enhanced Notes

- **NOTE-04**: Note editing with revision history
- **NOTE-05**: Note deletion with soft delete and audit trail
- **NOTE-06**: Rich text / markdown support in note content

### Advanced Display

- **DISP-05**: Export member notes to PDF
- **DISP-06**: Full-text search across all members' notes (global search)

### Extended Data

- **DATA-04**: Attach notes to other entities (Issues, Payments) using polymorphic relationship
- **DATA-05**: Note categories or tags for organization

### Permissions

- **ACCS-04**: Granular `manage_member_notes` permission via Spatie

## Out of Scope

| Feature | Reason |
|---------|--------|
| Private/role-scoped notes | All notes shared across admin roles per user decision |
| Note reminders/follow-ups | Over-engineering for v1; revisit based on usage |
| Note attachments (files/images) | Keep notes lightweight — text only |
| API endpoint for notes | Admin-only feature, no public/headless API needed |
| Dedicated notes management page | Notes integrated into existing member list |
| Real-time updates (WebSocket) | Single-user note-taking doesn't need real-time sync |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| NOTE-01 | — | Pending |
| NOTE-02 | — | Pending |
| NOTE-03 | — | Pending |
| DISP-01 | — | Pending |
| DISP-02 | — | Pending |
| DISP-03 | — | Pending |
| DISP-04 | — | Pending |
| DATA-01 | — | Pending |
| DATA-02 | — | Pending |
| DATA-03 | — | Pending |
| ACCS-01 | — | Pending |
| ACCS-02 | — | Pending |
| ACCS-03 | — | Pending |
| UI-01 | — | Pending |
| UI-02 | — | Pending |
| UI-03 | — | Pending |

**Coverage:**
- v1 requirements: 16 total
- Mapped to phases: 0
- Unmapped: 16 ⚠️

---
*Requirements defined: 2026-02-13*
*Last updated: 2026-02-13 after initial definition*