From a8623841aec2db3386ddc145cf2ae50607705f2a Mon Sep 17 00:00:00 2001
From: gbanyan <gbanyan.huang@gmail.com>
Date: Fri, 13 Feb 2026 11:35:01 +0800
Subject: [PATCH] docs: define v1 requirements

---
 .planning/REQUIREMENTS.md | 100 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 .planning/REQUIREMENTS.md

diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..444a9cc
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,100 @@
+# 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*