gbanyan/usher-manage-stack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: research member notes ecosystem

Browse Source
This commit is contained in:
gbanyan
2026-02-13 11:14:28 +08:00
parent 23573d3ebc
commit c962514532
6 changed files with 1980 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
.planning/research/FEATURES.md Normal file
View File

@@ -0,0 +1,232 @@
# Feature Landscape
**Domain:** CRM/Admin Member Note Systems
**Researched:** 2026-02-13
**Confidence:** MEDIUM
## Table Stakes
Features users expect. Missing = product feels incomplete.
| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Create note inline | Standard in admin interfaces; users expect quick annotation without navigation | Low | Alpine.js inline form on member list row |
| View note count | Badge indicators are universal pattern for "items present" | Low | Badge on member row, clickable to expand |
| Display author + timestamp | Audit integrity; users need "who wrote this when" | Low | Laravel auth()->user() + created_at |
| Chronological ordering | Notes are temporal; most recent first/last is expected | Low | ORDER BY created_at DESC in query |
| Expandable note history | Accordion/expansion is standard UX for "show more" | Low | Alpine.js x-show toggle, accordion pattern |
| Search/filter by content | Modern CRMs make notes searchable; users expect to find past comments | Medium | Full-text search on notes.content field |
| Empty state messaging | When no notes exist, users need clear "no notes yet" indicator | Low | Conditional display in Blade template |
| Responsive display | Admin interfaces must work on tablets; notes should be readable on smaller screens | Low | Tailwind responsive classes |
## Differentiators
Features that set product apart. Not expected, but valued.
| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Note export (member-specific) | Chairman can generate member note history PDF for meetings or handoffs | Medium | barryvdh/laravel-dompdf already in stack |
| Batch note visibility filter | Show only members with notes vs. all members for focused review | Low | Query scope: whereHas('notes') |
| Recent notes dashboard widget | Surface latest N notes across all members for quick admin overview | Medium | Dashboard addition with notes query |
| Note length indicator | Visual cue for long vs short notes (e.g., truncated preview with "read more") | Low | CSS + Alpine.js for text truncation |
| Keyboard shortcuts | Power users expect quick access (e.g., 'N' to add note on focused row) | Medium | Alpine.js keyboard listener, accessibility consideration |
| Note context linking | Link note to specific member action (payment, status change, etc.) for context | High | Polymorphic relationship, context metadata |
## Anti-Features
Features to explicitly NOT build.
| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Note editing/deletion | Destroys audit trail; creates compliance risk (append-only is healthcare/NPO standard) | Addendum pattern: add new note clarifying/correcting previous note |
| Private/role-scoped notes | Chairman explicitly wants transparency; adds complexity with minimal value | All admin roles share notes; document in UI that notes are shared |
| Rich text editor (WYSIWYG) | Overkill for simple observations; formatting rarely needed; security risk (XSS) | Plain text with auto-linking for URLs |
| Note categories/tags | Premature optimization; no user request; adds cognitive overhead | If categorization needed later, add via simple text conventions (e.g., "[follow-up]") |
| Note attachments/files | Scope creep; files belong in member documents, not quick notes | Link to existing document library in note text if needed |
| Scheduled reminders/tasks | Transforms simple note system into task manager; different domain | Keep notes as observations only; use separate task system if needed |
| Real-time collaboration | Single chairman use case; no concurrent editing needed; adds WebSocket complexity | Standard AJAX; page refresh shows new notes from other admins |
| Note templates | No evidence of repeated note patterns; premature optimization | Copy-paste from previous notes if patterns emerge |
| Soft delete for notes | Violates append-only principle; creates "hidden but recoverable" ambiguity | Hard constraint: no delete operation at all |
## Feature Dependencies
```
Display note count badge
└──requires──> Create note (must have notes to count)
Expandable note history
└──requires──> Display note count badge (badge is the expand trigger)
└──requires──> Display author + timestamp (what to show when expanded)
Search/filter by content
└──requires──> Create note (must have notes to search)
Note export (member-specific)
└──requires──> View note history (export queries same data)
Batch note visibility filter
└──requires──> Display note count badge (filters on notes existence)
Recent notes dashboard widget
└──requires──> Display author + timestamp (widget shows who/when)
Note context linking
└──enhances──> Display author + timestamp (adds "why" context to "who/when")
```
### Dependency Notes
- **Display note count badge requires Create note:** Badge shows count; zero notes = no badge or "0" badge (design choice)
- **Expandable note history requires Display note count badge:** Badge is the UI affordance for expansion (click to show)
- **Search/filter by content enhances Create note:** Makes note system scalable beyond 10-20 notes per member
- **Note context linking enhances everything:** If added, transforms simple notes into action-linked annotations (v2+ feature)
## MVP Recommendation
### Launch With (v1)
Minimum viable product — what's needed to validate the concept.
- [x] Create note inline — Core value: quick annotation on member list
- [x] Display note count badge — Table stakes: visual indicator of notes present
- [x] Expandable note history — Table stakes: view past notes without navigation
- [x] Display author + timestamp — Table stakes: audit integrity
- [x] Chronological ordering — Table stakes: temporal display
- [x] Empty state messaging — Table stakes: UX clarity when no notes
**Rationale:** These 6 features deliver the core value ("annotate members inline") with minimal complexity. All are Low complexity and align with user's stated need.
### Add After Validation (v1.x)
Features to add once core is working and chairman confirms value.
- [ ] Search/filter by content — Add when: chairman has >50 total notes across members and reports difficulty finding specific comments
- [ ] Batch note visibility filter — Add when: chairman wants to review "all members I've annotated" without scrolling
- [ ] Note length indicator — Add when: notes consistently exceed 200 characters and full display clutters UI
**Trigger for adding:** User feedback after 2-4 weeks of usage, or when specific pain point emerges.
### Future Consideration (v2+)
Features to defer until product-market fit is established.
- [ ] Note export (member-specific) — Defer: no stated need for printed reports in initial request
- [ ] Recent notes dashboard widget — Defer: chairman uses member list as entry point, not dashboard
- [ ] Keyboard shortcuts — Defer: no power-user workflow identified yet
- [ ] Note context linking — Defer: major complexity; evaluate after understanding note content patterns
**Why defer:** Not requested, not table stakes, and complexity doesn't justify speculative value.
## Feature Prioritization Matrix
| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Create note inline | HIGH | LOW | P1 |
| Display note count badge | HIGH | LOW | P1 |
| Expandable note history | HIGH | LOW | P1 |
| Display author + timestamp | HIGH | LOW | P1 |
| Chronological ordering | HIGH | LOW | P1 |
| Empty state messaging | MEDIUM | LOW | P1 |
| Search/filter by content | MEDIUM | MEDIUM | P2 |
| Batch note visibility filter | MEDIUM | LOW | P2 |
| Note length indicator | LOW | LOW | P2 |
| Note export (member-specific) | MEDIUM | MEDIUM | P3 |
| Recent notes dashboard widget | LOW | MEDIUM | P3 |
| Keyboard shortcuts | LOW | MEDIUM | P3 |
| Note context linking | LOW | HIGH | P3 |
**Priority key:**
- P1: Must have for launch (table stakes + core value)
- P2: Should have, add when specific need emerges
- P3: Nice to have, future consideration after validation
## Competitor Feature Analysis
Based on research of CRM and member management systems in 2026:
| Feature | SugarCRM/Salesforce | Sumac (Nonprofit) | Our Approach |
|---------|---------------------|-------------------|--------------|
| Note creation | Separate "Notes" tab, requires navigation | Case notes within case management module | Inline on member list (no navigation) |
| Note visibility | Role-based permissions available | Shared across caseworkers | Shared across all admin roles |
| Edit/Delete | Editable with audit log | Append-only with addendum pattern | Append-only (no edit/delete) |
| Rich formatting | WYSIWYG editor | Plain text with attachments | Plain text only |
| Search notes | Full-text search with filters | Search across cases and notes | Full-text search (v1.x) |
| Note categories | Tags and custom fields | Service plan categories | None (anti-feature) |
| Timestamps | Absolute + relative display | Absolute timestamps | Absolute + relative (tooltip) |
| Count indicator | Badge on related list tab | Note count in case summary | Badge on member row |
| Export | Include in reports/exports | PDF export per case | PDF export (v2+) |
**Our competitive position:**
- **Simpler:** No categories, tags, or rich formatting (reduces cognitive overhead)
- **Faster:** Inline creation vs. tab navigation (optimized for quick annotation)
- **More transparent:** Forced shared visibility (aligns with NPO culture)
- **More auditable:** Strictly append-only (exceeds healthcare standards)
## Implementation Pattern Reference
Based on research findings, recommended UX patterns:
**Badge UI (Material Design 3, PatternFly):**
- Pill shape, positioned at right edge of member row
- Count display: "3" for small counts, "99+" for >99 notes
- Color: Blue/info semantic (not red/error unless tied to action required)
- Clickable affordance: Cursor pointer + hover state
**Accordion/Expansion (Smashing Magazine, Accessible Accordion):**
- Caret icon: Downward when collapsed, upward when expanded
- Entire badge area clickable (not just icon)
- Icon position stays constant (no layout shift on toggle)
- Smooth transition (Alpine.js x-transition)
- ARIA: aria-expanded attribute for screen readers
**Timestamp Display (PatternFly, Cloudscape):**
- Recent (<24h): "2小時前" (relative)
- Older: "2026-02-11 14:30" (absolute)
- Tooltip on hover: Full ISO 8601 timestamp
- Format: Taiwan locale (zh-TW), 24-hour time
**Inline Form (Eleken List UI, Data Table UX):**
- Textarea (not single-line input) for multi-line notes
- 3 rows visible, auto-expand on focus
- Submit on Ctrl+Enter (keyboard UX)
- Cancel button to close without saving
- Loading state during AJAX submit
## Research Confidence
**HIGH confidence (Context7/Official docs):**
- None (no Context7 libraries for this domain-specific question)
**MEDIUM confidence (Multiple credible sources agree):**
- Table stakes features: Based on CRM industry standards from Salesforce/Sugar docs, Material Design, PatternFly component libraries
- Append-only best practice: Healthcare compliance docs (Healthie, Sessions Health), audit trail standards
- UI patterns: Design system documentation (Material Design 3, PatternFly, Smashing Magazine)
- NPO CRM landscape: Multiple 2026 nonprofit CRM reviews (Neon One, Bloomerang, Case Management Hub)
**LOW confidence (WebSearch only, needs validation):**
- Specific NPO note-taking workflows beyond Sumac case management
- Exact usage frequency of note export features (no user research data available)
## Sources
- [Best Practices for Taking Notes in CRM: A Complete Guide](https://www.sybill.ai/blogs/best-way-to-take-notes-in-crm)
- [CRM Notes - Optimize CRM Notes: Key Features and Benefits | Pipedrive](https://www.pipedrive.com/en/blog/crm-notes)
- [Historical Summary vs. Activity Stream vs. Audit Log - SugarCRM](https://support.sugarcrm.com/knowledge_base/user_interface/historical_summary_vs._activity_stream_vs._change_log/)
- [10 Essential Audit Trail Best Practices for 2026 – OpsHub Signal](https://signal.opshub.me/audit-trail-best-practices/)
- [Addendums to Progress Notes - Healthcare Best Practice](https://support.sessionshealth.com/article/393-addendum)
- [Best Nonprofit CRM for Managing Donors, Clients & Operations – Case Management Hub](https://casemanagementhub.org/nonprofit-crm/)
- [Sumac | #1 Nonprofit Case Management Software](https://www.societ.com/solutions/case-management/sumac/)
- [PatternFly • Notification badge](https://www.patternfly.org/components/notification-badge/design-guidelines/)
- [Badge – Material Design 3](https://m3.material.io/components/badges/guidelines)
- [Designing The Perfect Accordion — Smashing Magazine](https://www.smashingmagazine.com/2017/06/designing-perfect-accordion-checklist/)
- [Accordion UI Examples: Best Practices & Real-World Designs](https://www.eleken.co/blog-posts/accordion-ui)
- [UI Date Stamp Best Practices | Medium](https://medium.com/user-experince/ui-date-stamp-best-practices-85ae2c5ad9eb)
- [PatternFly • Timestamp](https://www.patternfly.org/components/timestamp/design-guidelines/)
- [30+ List UI Design Examples with Tips and Insights](https://www.eleken.co/blog-posts/list-ui-design)
- [Data Table Design UX Patterns & Best Practices - Pencil & Paper](https://www.pencilandpaper.io/articles/ux-pattern-analysis-enterprise-data-tables)
- [Filtering Contacts and Companies | Agile CRM](https://www.agilecrm.com/sales-enablement/filtering-contacts-and-companies)
- [33 CRM Features Your Small Business Needs in 2026](https://www.onepagecrm.com/blog/crm-features/)
---
*Feature research for: Member Notes System (會員備註系統)*
*Researched: 2026-02-13*