Add ProfessionalLicense and ContinuingEducationRegistration models (PR 1: foundation)

[maebeale]

🤖 PR, suggested 👤 review level: 🔬 Inspect — new data model + migrations (adds two tables, drops two Person columns)

What is the goal of this PR and why is this important?

CE data lives as three flat columns on EventRegistration, which can't model what AWBW needs: CE hours tracked per professional license, a person holding several licenses, and a CE record with its own payment + certificate lifecycle.

This is PR 1 of 2 — the foundation only (additive, no behavior change). PR 2 reroutes intake, the callout, and read sites, then drops the old ce_* columns.

How did you approach the change?

• ProfessionalLicense (per Person) — nullable number is a placeholder; find_or_create_for keeps one license per (person, number) and a single placeholder. No status (derived number_known?/expired?).
• ContinuingEducationRegistration (per EventRegistration, one per license) — allocatable so it reuses the existing Payment/Allocation machinery; string status (requested→paid→issued/unawarded, no enum); hours defaults from the event but stays editable, driving amount_cents.
• Event gains ce_hours_eligible (the explicit "CE offered" gate) + ce_hours (fractional hours).
• Allocation gets a CE over-payment guard and a requested→paid status sync.
• Drops the unused Person#license_number/license_type columns (no data) and their form/controller bits.
• Adds an "avoid Rails enums — prefer string values" project convention.

Anything else to add?

The existing ce_* columns and the CE form are deliberately left untouched here; suite stays green. Billing model: two licenses charge 2× but bill once (one payment allocated across the CE registrations).

Interface comparison: ContinuingEducationRegistration vs EventRegistration (incl. Allocation cost-validation pair)

CE deliberately mirrors only the allocatable/payment seam of EventRegistration so both behave identically wherever allocations are summed. Everything else diverges because CE is a lightweight, audited child record of an EventRegistration (scoped to one professional license), not a first-class resource.

Member	EventRegistration	ContinuingEducationRegistration	Same / Different — why
— Associations —
registrant (Person)	belongs_to	— (via event_registration.registrant)	Diff — CE is one level removed
event	belongs_to	— (via event_registration.event)	Diff — reached through parent
event_registration	—	belongs_to	Diff — CE is a child of ER
professional_license	—	belongs_to	Diff — ties cert to one license
created_by / updated_by	—	belongs_to … optional: true	Diff — CE audits actor (with paper trail)
comments, …_organizations, organizations, notifications, scholarships, checklist_completions	has_many	—	Diff — ER-only rich graph
continuing_education_registrations	has_many … dependent: :destroy	—	Diff — ER is the parent side
allocations (polymorphic)	has_many	has_many … dependent: :destroy	Same seam — both allocatable; CE adds dependent: :destroy
payments through allocations	— (derived ad hoc)	has_many … through: :allocations	Diff — CE declares it explicitly
accepts_nested_attributes_for	comments, notifications, registrant	none	Diff — driven by ER edit form
— Callbacks —
has_paper_trail	—	✓	Diff — CE is audited
before_create :generate_slug	✓	—	Diff — ER is URL-addressable
before_validation :default_from_event, on: :create	—	✓	Diff — CE snapshots hours/cost_cents
after_commit :send_cancellation_emails	✓	—	Diff — ER emails on cancel
payment-status sync	—	via Allocation callback → sync_payment_status!	Diff — CE status is payment-driven; ER status is attendance
— Constants —
Status set	ACTIVE/INACTIVE/ATTENDANCE_STATUSES (attendance)	STATUSES = requested/paid/issued/unawarded (fulfillment)	Diff — different domains
CHECKLIST_STEPS, DAY_FIELDS, CE_HOURLY_RATE_DOLLARS	✓	—	Diff — ER onboarding/CE-summary helpers
— Validations —
registrant_id unique per event_id, event_id presence, slug uniqueness	✓	—	Diff — ER-only
status inclusion	in: ATTENDANCE_STATUSES	in: STATUSES	Same mechanism, different set
numericality	ce_hours_requested ≥ 0	hours ≥ 0, cost_cents ≥ 0	Diff — ER stores the request; CE stores the snapshot
license_belongs_to_registrant	—	✓	Diff — CE-only integrity check
— Scopes —	~20 (name/event/active/scholarship/payment/keyword/…)	none	Diff — ER backs filterable rosters; CE accessed via parent
— Class methods —	search_by_params, remote_searchable_by	none	Diff — ER is searchable
— Payment / allocatable interface (the shared seam) —
allocations_sum	✓ (loaded-aware)	✓ (identical)	Same — intentional mirror
payments_sum	✓ (loaded-aware)	✓ (identical)	Same — intentional mirror
remaining_cost	[event.cost_cents - sum, 0].max	[cost_cents - sum, 0].max	Same logic, diff cost source (event vs. own snapshot)
paid_in_full?	free-event short-circuit (≤ 0 → true), else sum ≥ event.cost_cents	sum ≥ cost_cents.to_i (no free short-circuit)	Diff — ER special-cases free events
partially_paid?	✓	✓ (identical)	Same
sync_payment_status!	—	✓ (advances requested↔paid, leaves issued/unawarded)	Diff — CE-only
paid?	✓	✓ (→ paid_in_full?)	Same — mirrored for polymorphic allocatable callers
payment_status_label, discounted?, discount_sum	✓	✓ (mirrored in PR 2 / #1917)	Same — CE has no intends_to_pay, so its label's middle state is a real partial payment
payment_access_granted?, intends_to_pay?	✓	—	Diff — event-access affordance; no CE analog
— ER-only domain methods —	name, active?, attended?, scholarship?, certificate_available?, joinable?, videoconference_details_visible?, account_status, attendance_status_label, program_statuses, checklist/day helpers, remote_search_label, …	—	Diff — ER is the rich resource
— CE-only private —	—	default_from_event, license_belongs_to_registrant	Diff
— Supporting layer —
Controller / routes	EventRegistrationsController + full routes	none	Diff — CE managed indirectly
Decorator / Policy / Services / Mailers	✓	none	Diff
Factory / model spec	✓	✓	Same

Allocation cost-validation pair — validate_event_registration_cost vs validate_ce_registration_cost are structurally identical (same amount_was/persisted? self-exclusion, same already-paid + over-allocation math, same MoneyFormatter messages). Two intended differences:

Step	ER variant	CE variant	Why
Cost source	event_reg.event.cost_cents	ce_reg.cost_cents.to_i	ER cost lives on the event; CE stores its own snapshot
"No cost" guard	cost_cents.blank? → "free event"	cost_cents <= 0 → "no cost"	Event cost is nullable (blank-guards before arithmetic); CE column is null: false, default: 0

[maebeale]

🤖 From Claude: number.presence collapses ""→nil, so a CE opt-in with no number on file resolves to the person's single placeholder license rather than spawning a new blank row each time. The DB unique index on (person_id, number) enforces the numbered case (MySQL treats NULLs as distinct, so it intentionally does not block multiple placeholders — the model does).

[maebeale]

🤖 From Claude: Auto-advances requested↔paid to track real payments, but only from those two states — a later admin issued/unawarded is never clobbered. Driven from Allocation after_create, so reversals (negative allocations) revert paid→requested too.

[maebeale]

🤖 From Claude: Integrity guard: the license must belong to the registrant, otherwise one person's CE could be billed against another's license.

[maebeale]

🤖 From Claude: Mirrors validate_event_registration_cost, but caps allocations at the CE registration's own amount_cents (= hours × rate). With two licenses billed once, a single Payment allocates across both CE registrations and each is capped independently here.

[jmilljr24]

Just the cost calculation is the only thing that gives me pause. Thoughts?

[jmilljr24]

I don't think this aligns with the stakeholders new requirements for CE payments.

Prior to the last meeting, yes it was a direct correlation of ce_hour * hourly_rate but they currently the want essential a flat rate. If you want CE credits you pay $120 for this event (how they come up with that number is irrelevant). No refunds. If you only complete 6 hours, you only get credit for 6 hours.

I'm thinking a column on event for ce_cost. This avoids have a hard coded constant and no math involved.

[maebeale]

yes, i was thinking same on event ce_hour_cost, but was going to keep our math stuff, just have it all end up with the same math.

[jmilljr24]

I'm not hard pressed on this, but I guess my concern is that we are adding an additional step and logic that isn't needed. On the flip side if they change their mind in the future this would open up that ability. But then again that's just guessing and they may come up with some other formula for cost.

[maebeale]

yeah totally fair. what i'm hearing is there's a fixed cost for training events. and i've also heard about them doing future kinds of events that aren't training events. so going forward it's a toss-up. but i know in the past they captured partial amounts and payments. since this system needs to accommodate historical data too, i was thinking keep this data structure underneath and have the calculation logic just run in the background to get the current fixed cost handled.

[jmilljr24]

Good point on the filemaker data. I wasn't thinking of that.

Maybe a typo on "event"? They are dong a fixed cost for "CE Hours".

I took a look at the filemarker data. There are 167 records on CE hours. The are all a simple payment recording on an "CE hours event". 99% are $120 with a note saying 12 hours.

The handful of outliers I see in notes are:

11 hours - 120 paid
10 hours - 100 paid
30 hours - 30 paid
12 hours - waived
fee comped - no mention of hours
120 paid - did not attented

The only other odd two are a combined payment for a training event and CE hours.

With that said, there is no column for cost_per_hour. So I think as far as filemaker data goes it will be easiest to keep it the 1:1 , payments = X and CE_hours = X. It seems roundabout and brittle to take those two datapoints, divide them to get the hour rate, then take the original hour times the calculated rate to get back the payment we started with.

[maebeale]

ok @jmilljr24 cost calculations removed. i extracted the registration interface (payments & certificate) from event_registration into a registerable concern so it can be shared exactly with continuing_education_registration, and added certificate_sent_at for both since it's my understanding they issue those for both (and i wanted to keep them as mirrors of each other)

[jmilljr24]

Maybe in a decorator in part 2? I don't recall what pattern we've been using the most for stuff like this.

[maebeale]

We don't really have a pattern. A better name is prob name.

[jmilljr24]

Suggested change

	def paid?
	paid_in_full?
	end

I personally would just keep one consistent method name if it's exactly the same.

[jmilljr24]

We may have been using this pattern other places, it just caught my eye in this.

[jmilljr24]

Suggested change

return unless ce_reg.is_a?(ContinuingEducationRegistration)

nbd but this is redudant to

validate :validate_ce_registration_cost, if: -> { allocatable_type == "ContinuingEducationRegistration" }

[jmilljr24]

Suggested change

	# explicitly. Both are plain stored values — no per-hour rate is multiplied out.
	# explicitly.

[jmilljr24]

I don't know the naming convention we've been using but I feel like this might bite us at some point. cost_cents is explicit. Does hours_cost mean dollars or cents. I can't tell unless I go to this method.

Then in registerable.rb we have

def remaining_cost

which returns cents.

[jmilljr24]

Looks like event "cost" is also passed into the controller as dollars and saved as cents so this consistent with that. Just makes me think it could be easy to mix up.

[maebeale]

yeah we have a little pattern going that cost is dollars and user-facing cost_cents is what is stored. i've tried a couple options at various times/models and this seems best split of the difference 🤷‍♀️

[jmilljr24]

Looking good! Nice idea on registerable.

[maebeale]

ooo, great points! will do those before merge.