From aa51ad70d9cc440765c4790120f4ff79bb712efa Mon Sep 17 00:00:00 2001
From: gbanyan <gbanyan.huang@gmail.com>
Date: Fri, 13 Feb 2026 10:53:03 +0800
Subject: [PATCH] docs: initialize project

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

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..a0dbe13
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,72 @@
+# Member Notes System (會員備註系統)
+
+## What This Is
+
+An enhancement to the existing admin member list that adds per-member note-taking capability. Any admin user can quickly add timestamped text notes to any member, and see a note count badge on the member list. Designed primarily for the chairman (理事長) to track observations and follow-ups, but shared across all admin roles.
+
+## Core Value
+
+The chairman can annotate any member with timestamped notes directly from the member list, without navigating away from the page.
+
+## Requirements
+
+### Validated
+
+<!-- Existing capabilities inferred from codebase -->
+
+- ✓ Member lifecycle management (pending → active → expired/suspended) — existing
+- ✓ Admin member list with search, filter, CRUD — existing
+- ✓ Role-based access control via Spatie permissions — existing
+- ✓ Multi-tier financial approval workflows — existing
+- ✓ CMS (articles, pages, documents) with headless API — existing
+- ✓ Issue tracking system — existing
+- ✓ Audit logging on business-critical actions — existing
+- ✓ Member profile with LINE ID — existing
+
+### Active
+
+- [ ] Per-member notes with text + timestamp, stored in DB
+- [ ] Inline quick-add note UI on the admin member list (no page navigation)
+- [ ] Note count badge displayed on each member row in the list
+- [ ] Click badge to expand/view full note history for that member
+- [ ] All admin roles can view and write notes (shared visibility)
+- [ ] Notes display author name and creation datetime
+- [ ] Notes management (view history, chronological order)
+
+### Out of Scope
+
+- Private/role-scoped notes — all notes are shared across admin roles
+- Note categories or tags — keep it simple, just text + time
+- Reminders or scheduled follow-ups — not needed for v1
+- Note editing or deletion — append-only for audit integrity
+- Dashboard/summary statistics — just the annotated member list
+- API endpoint for notes — admin-only, no public/headless API needed
+
+## Context
+
+- The existing admin member list is at `/admin/members` with full CRUD, search, and filtering
+- The chairman (理事長) role maps to `finance_chair` in the RBAC system
+- The `admin` middleware allows access to anyone with the `admin` role or any permissions
+- UI is Blade + Tailwind CSS + Alpine.js — inline interactions fit naturally with Alpine.js
+- All UI text is hardcoded Traditional Chinese
+- The member list uses standard Laravel pagination
+
+## Constraints
+
+- **Tech stack**: Must use existing Laravel 10 + Blade + Tailwind + Alpine.js stack
+- **Database**: SQLite (dev) / MySQL (prod) — standard Laravel migration
+- **Access control**: Reuse existing `admin` middleware — no new permission needed
+- **UI pattern**: Inline interaction via Alpine.js — no full-page reloads for note operations
+- **Audit**: Notes are append-only; use `AuditLogger` for tracking note creation
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Enhance existing member list vs new page | User wants notes integrated into existing workflow, not a separate tool | — Pending |
+| Shared notes (all admin roles) | Chairman wants transparency; secretary and others should see same notes | — Pending |
+| Append-only notes (no edit/delete) | Maintains audit integrity for member observations | — Pending |
+| Alpine.js inline UI | Matches existing stack; avoids full page reloads for quick note-taking | — Pending |
+
+---
+*Last updated: 2026-02-13 after initialization*