diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index d4ab4a4..f250b9f 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -32,10 +32,11 @@ Decimal phases appear between their surrounding integers in numeric order.
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**: TBD
+**Plans:** 2 plans
Plans:
-- [ ] TBD (will be defined in plan-phase)
+- [ ] 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
@@ -84,7 +85,7 @@ Phases execute in numeric order: 1 → 2 → 3
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
-| 1. Database Schema & Backend API | 0/TBD | Not started | - |
+| 1. Database Schema & Backend API | 0/2 | Planning complete | - |
| 2. Inline Quick-Add UI | 0/TBD | Not started | - |
| 3. Note History & Display | 0/TBD | Not started | - |
diff --git a/.planning/phases/01-database-schema-backend-api/01-01-PLAN.md b/.planning/phases/01-database-schema-backend-api/01-01-PLAN.md
new file mode 100644
index 0000000..4f18f38
--- /dev/null
+++ b/.planning/phases/01-database-schema-backend-api/01-01-PLAN.md
@@ -0,0 +1,181 @@
+---
+phase: 01-database-schema-backend-api
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+ - database/migrations/YYYY_MM_DD_HHMMSS_create_notes_table.php
+ - app/Models/Note.php
+ - app/Models/Member.php
+ - app/Providers/AppServiceProvider.php
+ - database/factories/NoteFactory.php
+autonomous: true
+
+must_haves:
+ truths:
+ - "Notes table exists with polymorphic columns (notable_type, notable_id) and composite index"
+ - "Note model has morphTo relationship to notable and belongsTo relationship to author (User)"
+ - "Member model has morphMany relationship to notes ordered by created_at desc"
+ - "Morph map registered in AppServiceProvider maps 'member' to Member::class"
+ - "NoteFactory can generate test notes with forMember() state method"
+ artifacts:
+ - path: "database/migrations/*_create_notes_table.php"
+ provides: "Notes table schema with polymorphic columns and indexes"
+ contains: "morphs('notable')"
+ - path: "app/Models/Note.php"
+ provides: "Note model with relationships"
+ exports: ["Note"]
+ min_lines: 25
+ - path: "app/Models/Member.php"
+ provides: "notes() morphMany relationship added to existing model"
+ contains: "morphMany(Note::class"
+ - path: "app/Providers/AppServiceProvider.php"
+ provides: "Morph map registration for namespace safety"
+ contains: "enforceMorphMap"
+ - path: "database/factories/NoteFactory.php"
+ provides: "Factory for test note creation"
+ contains: "forMember"
+ key_links:
+ - from: "app/Models/Note.php"
+ to: "app/Models/Member.php"
+ via: "morphTo/morphMany polymorphic relationship"
+ pattern: "morphTo|morphMany"
+ - from: "app/Models/Note.php"
+ to: "app/Models/User.php"
+ via: "belongsTo author relationship"
+ pattern: "belongsTo.*User::class.*author_user_id"
+ - from: "app/Providers/AppServiceProvider.php"
+ to: "app/Models/Member.php"
+ via: "Morph map registration"
+ pattern: "enforceMorphMap.*member.*Member::class"
+---
+
+
+Create the database foundation for the member notes system: migration, Note model with polymorphic relationships, Member model relationship addition, morph map registration, and test factory.
+
+Purpose: Establishes the data layer that all subsequent note features depend on. Without this, no notes can be stored or queried.
+Output: Notes table in database, Note model, Member->notes relationship, NoteFactory for testing.
+
+
+
+@/Users/gbanyan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/gbanyan/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-database-schema-backend-api/01-RESEARCH.md
+
+@app/Models/Member.php
+@app/Models/CustomFieldValue.php
+@app/Providers/AppServiceProvider.php
+@database/factories/MemberFactory.php
+
+
+
+
+
+ Task 1: Create notes migration and Note model with polymorphic relationships
+
+ database/migrations/YYYY_MM_DD_HHMMSS_create_notes_table.php
+ app/Models/Note.php
+
+
+ Create migration using `php artisan make:migration create_notes_table`. In the migration:
+ - `$table->id()`
+ - `$table->morphs('notable')` — creates notable_type (string), notable_id (unsignedBigInteger), and composite index on [notable_type, notable_id] automatically
+ - `$table->longText('content')` — note text content
+ - `$table->foreignId('author_user_id')->constrained('users')->cascadeOnDelete()` — links to User who wrote the note
+ - `$table->timestamps()`
+ - `$table->index('created_at')` — for chronological sorting queries
+
+ Create `app/Models/Note.php`:
+ - Use `HasFactory` trait
+ - `$fillable`: notable_type, notable_id, content, author_user_id
+ - `notable()` method returning `$this->morphTo()` (MorphTo relationship)
+ - `author()` method returning `$this->belongsTo(User::class, 'author_user_id')` (BelongsTo relationship)
+ - Follow existing model patterns from CustomFieldValue.php (same polymorphic pattern)
+
+ Run `php artisan migrate` to apply the migration.
+
+
+ Run `php artisan migrate:status` and confirm the create_notes_table migration shows as "Ran".
+ Run `php artisan tinker --execute="Schema::hasTable('notes')"` and confirm it returns true.
+ Run `php artisan tinker --execute="Schema::getColumnListing('notes')"` and confirm columns: id, notable_type, notable_id, content, author_user_id, created_at, updated_at.
+
+
+ Notes table exists in database with all columns (id, notable_type, notable_id, content, author_user_id, created_at, updated_at), composite index on [notable_type, notable_id], and index on created_at. Note model exists with notable() morphTo and author() belongsTo relationships.
+
+
+
+
+ Task 2: Add Member relationship, morph map, and test factory
+
+ app/Models/Member.php
+ app/Providers/AppServiceProvider.php
+ database/factories/NoteFactory.php
+
+
+ In `app/Models/Member.php`:
+ - Add `use Illuminate\Database\Eloquent\Relations\MorphMany;` import
+ - Add `notes()` method returning `$this->morphMany(Note::class, 'notable')->orderBy('created_at', 'desc')` — default ordering newest first for display
+ - Add `use App\Models\Note;` import
+ - Place the method near existing relationship methods (after payments, user, etc.)
+
+ In `app/Providers/AppServiceProvider.php`:
+ - Add `use Illuminate\Database\Eloquent\Relations\Relation;` import
+ - Add `use App\Models\Member;` import
+ - In `boot()` method, add: `Relation::enforceMorphMap(['member' => Member::class]);`
+ - This ensures 'member' is stored in notable_type column instead of the full class name 'App\Models\Member', protecting against future namespace refactoring
+
+ Create `database/factories/NoteFactory.php`:
+ - Follow existing MemberFactory pattern
+ - `definition()` returns: notable_type => 'member' (uses morph map alias, NOT Member::class), notable_id => Member::factory(), content => $this->faker->paragraph(), author_user_id => User::factory()
+ - Add `forMember(Member $member)` state method that sets notable_type => 'member', notable_id => $member->id
+ - Add `byAuthor(User $user)` state method that sets author_user_id => $user->id
+
+
+ Run `php artisan tinker --execute="use App\Models\Member; use App\Models\Note; echo (new Member)->notes() instanceof \Illuminate\Database\Eloquent\Relations\MorphMany ? 'OK' : 'FAIL';"` and confirm "OK".
+ Run `php artisan tinker --execute="use Illuminate\Database\Eloquent\Relations\Relation; echo json_encode(Relation::morphMap());"` and confirm output contains "member" key mapping to Member class.
+ Run `php artisan tinker --execute="use App\Models\Note; echo class_exists(\Database\Factories\NoteFactory::class) ? 'OK' : 'FAIL';"` and confirm "OK".
+
+
+ Member model has notes() morphMany relationship returning notes ordered by created_at desc. AppServiceProvider registers morph map with 'member' => Member::class. NoteFactory exists with definition(), forMember(), and byAuthor() state methods.
+
+
+
+
+
+
+Run `php artisan migrate:fresh --seed` to confirm migration works cleanly with existing seeders.
+Run `php artisan tinker` and execute:
+```php
+use App\Models\Member;
+use App\Models\User;
+use App\Models\Note;
+
+$user = User::first();
+$member = Member::first();
+$note = $member->notes()->create(['content' => 'Test note', 'author_user_id' => $user->id]);
+echo $note->id . ' - ' . $note->notable_type . ' - ' . $note->content;
+echo $note->author->name;
+echo $member->notes()->count();
+```
+All commands should execute without errors. The notable_type should show 'member' (not 'App\Models\Member') due to the morph map.
+
+
+
+1. Notes table exists with all required columns and indexes
+2. Note model has working morphTo and belongsTo relationships
+3. Member model has working morphMany notes relationship (ordered by created_at desc)
+4. Morph map stores 'member' string (not full class name) in notable_type
+5. NoteFactory can create notes with forMember() and byAuthor() state methods
+6. `php artisan migrate:fresh --seed` runs without errors
+
+
+
diff --git a/.planning/phases/01-database-schema-backend-api/01-02-PLAN.md b/.planning/phases/01-database-schema-backend-api/01-02-PLAN.md
new file mode 100644
index 0000000..10bc555
--- /dev/null
+++ b/.planning/phases/01-database-schema-backend-api/01-02-PLAN.md
@@ -0,0 +1,242 @@
+---
+phase: 01-database-schema-backend-api
+plan: 02
+type: execute
+wave: 2
+depends_on: ["01-01"]
+files_modified:
+ - app/Http/Controllers/Admin/MemberNoteController.php
+ - app/Http/Requests/StoreNoteRequest.php
+ - routes/web.php
+ - app/Http/Controllers/AdminMemberController.php
+ - tests/Feature/Admin/MemberNoteTest.php
+autonomous: true
+
+must_haves:
+ truths:
+ - "Admin can create a note for a member via POST /admin/members/{member}/notes with text content"
+ - "Admin can retrieve all notes for a member via GET /admin/members/{member}/notes with author names and timestamps"
+ - "Member list at /admin/members shows accurate note count per member without N+1 queries"
+ - "Note creation is wrapped in DB::transaction with AuditLogger::log call"
+ - "Non-admin users receive 403 when attempting to create notes"
+ - "Feature tests pass covering CRUD, authorization, audit logging, and N+1 prevention"
+ artifacts:
+ - path: "app/Http/Controllers/Admin/MemberNoteController.php"
+ provides: "Note store and index endpoints"
+ exports: ["MemberNoteController"]
+ min_lines: 30
+ - path: "app/Http/Requests/StoreNoteRequest.php"
+ provides: "Validation for note creation with Traditional Chinese error messages"
+ exports: ["StoreNoteRequest"]
+ min_lines: 15
+ - path: "routes/web.php"
+ provides: "Admin routes for member notes (store + index)"
+ contains: "members.notes"
+ - path: "app/Http/Controllers/AdminMemberController.php"
+ provides: "withCount('notes') added to member list query"
+ contains: "withCount"
+ - path: "tests/Feature/Admin/MemberNoteTest.php"
+ provides: "Feature tests for note creation, retrieval, auth, audit, N+1"
+ min_lines: 80
+ key_links:
+ - from: "app/Http/Controllers/Admin/MemberNoteController.php"
+ to: "app/Models/Note.php"
+ via: "Creates notes via Member morphMany relationship"
+ pattern: "notes\\(\\)->create"
+ - from: "app/Http/Controllers/Admin/MemberNoteController.php"
+ to: "app/Support/AuditLogger.php"
+ via: "Logs note creation in audit trail"
+ pattern: "AuditLogger::log.*note\\.created"
+ - from: "app/Http/Controllers/AdminMemberController.php"
+ to: "app/Models/Note.php"
+ via: "withCount('notes') for N+1 prevention"
+ pattern: "withCount.*notes"
+ - from: "routes/web.php"
+ to: "app/Http/Controllers/Admin/MemberNoteController.php"
+ via: "Route registration for store and index"
+ pattern: "MemberNoteController"
+---
+
+
+Create the backend API endpoints for member notes: controller with store/index actions, form request validation, route registration, member list note count integration, and comprehensive feature tests.
+
+Purpose: Provides the backend API that Phase 2 (inline UI) will consume. After this plan, notes can be created and retrieved via HTTP endpoints, and the member list shows note counts.
+Output: Working POST/GET endpoints for member notes, StoreNoteRequest validation, note count on member list, feature tests.
+
+
+
+@/Users/gbanyan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/gbanyan/.claude/get-shit-done/templates/summary.md
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-database-schema-backend-api/01-RESEARCH.md
+@.planning/phases/01-database-schema-backend-api/01-01-SUMMARY.md
+
+@app/Http/Controllers/AdminMemberController.php
+@app/Http/Controllers/Admin/ArticleController.php
+@app/Http/Requests/StoreMemberRequest.php
+@app/Support/AuditLogger.php
+@routes/web.php
+@tests/Feature/MemberRegistrationTest.php
+
+
+
+
+
+ Task 1: Create MemberNoteController, StoreNoteRequest, and register routes
+
+ app/Http/Controllers/Admin/MemberNoteController.php
+ app/Http/Requests/StoreNoteRequest.php
+ routes/web.php
+
+
+ Create `app/Http/Requests/StoreNoteRequest.php`:
+ - `authorize()` returns true (authorization is handled by the admin middleware on the route group; this matches the pattern where controllers in the admin route group rely on the middleware, not Form Request authorization)
+ - `rules()`: content => 'required|string|min:1|max:65535'
+ - `messages()`: Traditional Chinese error messages — 'content.required' => '備忘錄內容為必填欄位', 'content.min' => '備忘錄內容不可為空白'
+
+ Create `app/Http/Controllers/Admin/MemberNoteController.php`:
+ - Namespace: `App\Http\Controllers\Admin` (matches ArticleController pattern in Admin namespace)
+ - Extends `App\Http\Controllers\Controller`
+
+ **`index(Member $member)` method:**
+ - Load notes with author: `$member->notes()->with('author')->get()`
+ - Return JSON response: `response()->json(['notes' => $notes])` — This returns JSON because Phase 2 will consume it via AJAX/Axios from Alpine.js. This is NOT a public API endpoint; it's an admin endpoint returning JSON for inline UI consumption.
+ - Each note in the response should include: id, content, created_at, author (with name)
+
+ **`store(StoreNoteRequest $request, Member $member)` method:**
+ - Wrap in `DB::transaction()` closure
+ - Create note: `$member->notes()->create(['content' => $request->content, 'author_user_id' => $request->user()->id])`
+ - Audit log: `AuditLogger::log('note.created', $note, ['member_id' => $member->id, 'member_name' => $member->full_name, 'author' => $request->user()->name])`
+ - Return JSON: `response()->json(['note' => $note->load('author'), 'message' => '備忘錄已新增'], 201)` — JSON response for AJAX consumption in Phase 2
+
+ In `routes/web.php`:
+ - Inside the existing `Route::middleware(['auth', 'admin'])->prefix('admin')->name('admin.')->group(...)` block
+ - Add these routes near the existing member routes (after line ~139 where member payment routes end):
+ ```php
+ // Member Notes (會員備忘錄)
+ Route::get('/members/{member}/notes', [MemberNoteController::class, 'index'])->name('members.notes.index');
+ Route::post('/members/{member}/notes', [MemberNoteController::class, 'store'])->name('members.notes.store');
+ ```
+ - Add the import at the top of web.php: `use App\Http\Controllers\Admin\MemberNoteController;`
+
+
+ Run `php artisan route:list --name=members.notes` and confirm both routes appear:
+ - GET /admin/members/{member}/notes → admin.members.notes.index
+ - POST /admin/members/{member}/notes → admin.members.notes.store
+
+
+ MemberNoteController exists with store() (JSON response, DB::transaction, AuditLogger) and index() (JSON with notes + author) methods. StoreNoteRequest validates content field with Traditional Chinese messages. Routes registered as admin.members.notes.store and admin.members.notes.index.
+
+
+
+
+ Task 2: Add withCount to member list and create feature tests
+
+ app/Http/Controllers/AdminMemberController.php
+ tests/Feature/Admin/MemberNoteTest.php
+
+
+ In `app/Http/Controllers/AdminMemberController.php`:
+ - In the `index()` method, change line 18 from `$query = Member::query()->with('user');` to `$query = Member::query()->with('user')->withCount('notes');`
+ - This adds a `notes_count` attribute to each member via a single subquery (no N+1)
+ - The Blade view can access `$member->notes_count` — Phase 2 will use this for the badge
+
+ Create `tests/Feature/Admin/MemberNoteTest.php`:
+ - Namespace: `Tests\Feature\Admin`
+ - Use `RefreshDatabase` trait
+ - `setUp()`: seed roles via `$this->artisan('db:seed', ['--class' => 'RoleSeeder']);`
+ - Create admin user helper: `$admin = User::factory()->create(); $admin->assignRole('admin');`
+
+ **Test cases (minimum required):**
+
+ 1. `test_admin_can_create_note_for_member()`:
+ - Create admin user, create member
+ - POST to `route('admin.members.notes.store', $member)` with `['content' => 'Test note content']`
+ - Assert 201 status
+ - Assert response JSON has note with content and author
+ - Assert `assertDatabaseHas('notes', ['notable_type' => 'member', 'notable_id' => $member->id, 'content' => 'Test note content', 'author_user_id' => $admin->id])`
+
+ 2. `test_admin_can_retrieve_notes_for_member()`:
+ - Create admin, member, and 3 notes using NoteFactory::forMember($member)->byAuthor($admin)
+ - GET `route('admin.members.notes.index', $member)`
+ - Assert 200 status
+ - Assert response JSON has 'notes' array with 3 items
+ - Assert each note has 'content', 'created_at', and 'author.name' keys
+
+ 3. `test_note_creation_requires_content()`:
+ - POST with empty content
+ - Assert 422 status (validation error)
+ - Assert response JSON has errors for 'content' field
+
+ 4. `test_note_creation_logs_audit_trail()`:
+ - Create note via POST
+ - Assert `assertDatabaseHas('audit_logs', ['action' => 'note.created'])` with metadata containing member_id
+
+ 5. `test_non_admin_cannot_create_note()`:
+ - Create regular user (no admin role, no permissions)
+ - POST to create note
+ - Assert 403 status
+
+ 6. `test_member_list_includes_notes_count()`:
+ - Create admin, create 2 members
+ - Create 3 notes for member 1, 0 notes for member 2
+ - GET `route('admin.members.index')`
+ - Assert 200 status
+ - Assert view has 'members' data
+ - Assert first member has notes_count attribute (verify it's 3 or 0 as expected)
+
+ 7. `test_notes_returned_newest_first()`:
+ - Create member with 3 notes at different timestamps (use `created_at` overrides in factory)
+ - GET index endpoint
+ - Assert first note in response has the most recent created_at
+
+ Follow existing test patterns from MemberRegistrationTest.php and CashierLedgerWorkflowTest.php.
+
+
+ Run `php artisan test --filter=MemberNoteTest` and confirm all 7 tests pass.
+ Run `php artisan test` to confirm no existing tests are broken by the changes.
+
+
+ AdminMemberController index() includes withCount('notes') for N+1 prevention. MemberNoteTest.php has 7 passing feature tests covering: note creation, retrieval, validation, audit logging, authorization, member list note count, and chronological ordering. All existing tests still pass.
+
+
+
+
+
+
+1. Run `php artisan test --filter=MemberNoteTest` — all 7 tests pass
+2. Run `php artisan test` — no regressions in existing tests
+3. Run `php artisan route:list --name=members.notes` — both routes (GET index, POST store) visible
+4. Manual verification with tinker:
+```php
+// Create a note via the relationship
+$admin = User::where('email', 'admin@test.com')->first();
+$member = Member::first();
+$note = $member->notes()->create(['content' => 'Manual test', 'author_user_id' => $admin->id]);
+echo $note->notable_type; // Should print 'member' (not App\Models\Member)
+echo $note->author->name; // Should print admin name
+
+// Verify withCount works
+$members = Member::withCount('notes')->get();
+echo $members->first()->notes_count; // Should print integer
+```
+
+
+
+1. POST /admin/members/{member}/notes creates a note and returns 201 JSON with note + author data
+2. GET /admin/members/{member}/notes returns JSON array of notes with author names and timestamps
+3. Note creation wrapped in DB::transaction with AuditLogger::log('note.created', ...)
+4. StoreNoteRequest validates content (required, string, min:1) with Traditional Chinese messages
+5. AdminMemberController index uses withCount('notes') — notes_count available on each member
+6. All 7 feature tests pass
+7. No regressions in existing test suite
+
+
+