Customer Notes

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/customer-notes/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Customer Notes lets staff add timestamped, threaded notes to customer profiles to document preferences, past issues, and follow-ups.

The problem

Staff can’t document customer interactions; each rep independently rediscovers the same preferences.

What it does

• Add note to customer profile (text, max 5000 chars)
• Notes timestamped and attributed to staff
• Notes threaded (replies to notes)
• List notes reverse-chronological (newest first)
• Edit own note
• Delete note (Admin-only, leaves audit trail)
• Search notes by email or content
• Note mentions: @mention staff member
• Audit log: created, edited, deleted, by whom

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Rich text in notes — plain text only
• File attachments — separate feature
• Email notification on mention — note-tagging only
• Bulk import from CSV — manual only
• Full threading UI — flat list + simple nesting

Data model

CustomerNote: id, customer_id, user_id, content, parent_note_id (nullable), created_at, updated_at, deleted_at. Migration: add customer_notes table with indexes on customer_id and user_id.

API

• POST /admin/customers/{id}/notes
• GET /admin/customers/{id}/notes
• PATCH /admin/customers/{id}/notes/{note_id}
• DELETE /admin/customers/{id}/notes/{note_id}
• POST /admin/customers/{id}/notes/{note_id}/replies

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Notes tab on customer detail: reverse-chronological list. Note display: author, timestamp, content, edit/delete buttons. Add form: text area. Reply form: click Reply, text area.

The seam — why this is core

Core owns: CustomerNote table, CRUD, threading (parent_note_id). Paid module owns: nothing; core infrastructure.

Core owns the interface + honest note storage; customer context is infrastructure, not a support commitment or credential.

Dependencies

• customer-profiles
• admin-user-management

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Adding note appears immediately with timestamp and staff name
• Reply appears indented/threaded
• Edit: note shows ‘edited’ indicator, new timestamp
• Delete: note shows ‘[deleted by Admin at timestamp]’; reply still shows parent as ‘[deleted]’
• Search ‘prefers DHL’ returns note + customer
• Newest-first sort: 1hr ago above yesterday
• @alice mention: stored; no email (out of scope)

Risks

10k+ notes per customer causes slow page load (must paginate). Edit changes audit trail. Hard-delete loses content. Contains customer PII. Threading logic broken.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.