Epic: Member manager bulk actions (select + bulk mark/end/email)

[jorisjonkers-dev-agents]

Bulk actions on selected users in the Member Manager. Design settled via a grilling session; this epic is the authoritative spec. Delivered as a stack of PRs (see sub-issues).

Feature summary

Checkboxes per row (house-styled) + a "select all displayed" header checkbox. A vertical triple-dot menu at the top-right of the members table exposes bulk actions applied to the current selection:

1. Mark as paid
2. Mark as unpaid
3. Send contribution reminder (email)
4. Send incasso notification (email)
5. End membership (end all active memberships as of today)

Locked design decisions

1. Two-phase preview→execute. Frontend POSTs selected userIds + params to a backend preview endpoint; backend resolves member types/fees/exclusions/warnings and returns a structured summary. The confirm dialog renders exactly that. On confirm, frontend calls execute with the same params + the (possibly corrected) per-user amounts + dates. All business logic lives on the backend.
2. Per-action endpoint pairs, domain-aligned, sharing ONE preview response envelope (counts + per-user rows + warnings) so the frontend uses a single reusable confirm dialog. No per-user PUT/POST spam — one request per action.
3. Fee resolution (both emails). The period stores halfYearFee, fullYearFee, alumniFee. A "half-year cutoff date" input: regular members whose membership started on/after it resolve to the half-year fee, otherwise full-year; alumni → alumni fee; honorary → excluded. Backend preview computes the suggested per-user amount; the dialog lets the treasurer correct each user's amount before executing; execute carries the final per-user amounts.
4. Honorary: hard-excluded from both fee emails, shown red in the summary with a warning (they don't pay). Not overridable.
5. Incasso mismatch: users without the incasso flag selected for the incasso email are flagged (amber) and excluded by default; the treasurer can opt specific users back in.
6. Already-paid: members already marked paid for the period are excluded by default from reminder and incasso; opt-in to re-include.
7. Audit + re-send: every send writes an audit row (reuse ContributionReminder; add a parallel IncassoNotification entity). Preview shows "last sent on " + warns for prior sends this period, but re-send is allowed.
8. Selection: persistent Set<userId> that survives search/filter/sort changes. Header checkbox toggles only currently-displayed rows (checked/indeterminate). Always-visible "N selected" chip + Clear. Confirm dialog lists every selected user by name.
9. Authorization: BOARD-level (matches existing Contribution/ContributionReminder writes; TREASURER/ADMIN inherit).
10. All five actions use preview→execute + the shared dialog. Non-email previews show counts + skip reasons (already-paid, no active membership, etc.).
11. Period anchor: period-relative actions (paid/unpaid/reminder/incasso + already-paid checks) target the member manager's currently-selected contribution period; end-membership is period-independent (effective today). Actions disabled when no period is selected.
12. End-membership: ends all active memberships (endDate == null) of each selected user, effective today; users with no active membership are skipped/flagged; already-ended memberships untouched.

Date inputs per email action

• Contribution reminder: payment-due date (shown in mail) + half-year cutoff date (fee resolution).
• Incasso notification: expected incasso date (shown in mail) + half-year cutoff date (fee resolution).

Open decision (to confirm before PR2/PR3)

• System-test depth for emails: recommended = assert rendered body content (resolved amount per member type, correct date, honorary excluded, exclusions/opt-ins, per-user overrides) + recipients + audit, not just counts.

Existing infrastructure to build on

• Mail: Thymeleaf + Markdown, async outbox, per-domain EmailContent builders; InMemoryEmailClient for tests. POST /contributionReminders/batch + ContributionReminder entity already exist.
• MemberType: ALUMNI, HONORARY, REGULAR, NONE. Fees on ContributionPeriod.
• "Paid" = a Contribution row for (userId, periodId).
• incasso boolean on the active Membership; endMembership exists per-membership (need bulk).
• System tests: @SpringBootTest + MockMvc in the integrationTest sourceset.

Delivery (stacked PRs — see sub-issues)

1. Backend: bulk mark paid/unpaid + end-membership (preview+execute) + system tests.
2. Backend: bulk contribution reminder (fee resolution, honorary/already-paid exclusion, per-user override, audit) + system tests.
3. Backend: new incasso-notification domain (entity, email builder, endpoints, incasso-mismatch, exclusions, override, audit) + system tests.
4. Frontend: selection UI (house-styled checkboxes, persistent set, select-all-displayed, N-selected chip + clear), triple-dot menu, shared confirm dialog wired to all endpoints, per-user fee edit, date inputs, warnings/red honorary + e2e.

Note: endpoint/DTO changes require openapi.json + client regen, which needs a DB env (not available in the sandbox) — flag per PR.

[jorisjonkers-dev-agents]

Specification — Member manager bulk actions

Status: Draft (authored with Spec Kit, spec-driven). Scope: epic #414. Milestone: Member manager bulk actions.

Board members currently act on one member at a time in the Member Manager. This feature lets them select many members and apply one action to all of them at once, with a backend that does the work in a single request and a confirmation step that shows exactly what will happen before it happens.

User Scenarios & Testing

User Story 1 — Select members (Priority: P1)

A board member ticks checkboxes next to rows, or ticks the header box to select everyone currently displayed, and sees a running "N selected" count. The selection is theirs to build up across searches/filters.

Why P1: Nothing else in this feature works without a selection. It is the foundation and independently demonstrable (select → count updates → clear).

Independent Test: Tick rows and the header box; change the search/filter; confirm the selection count persists and the header box shows checked/indeterminate/empty correctly; Clear resets it.

Acceptance Scenarios:

1. Given the members table, When a row checkbox is ticked, Then the "N selected" count increments and a Clear control appears.
2. Given a filtered list, When the header "select all displayed" box is ticked, Then every currently-visible row is selected and the header box shows checked.
3. Given an existing selection, When the search or filters change, Then previously-selected users remain selected even if no longer visible.
4. Given some displayed rows selected, When not all displayed are selected, Then the header box shows an indeterminate state.

User Story 2 — Bulk mark paid / unpaid (Priority: P1)

For the currently-selected contribution period, a board member marks all selected members as paid (or unpaid) in one action, after a confirmation that shows how many will change and how many are skipped (already in that state).

Why P1: Highest-frequency treasury task; simplest action; proves the select → preview → execute loop end-to-end.

Independent Test: Select a mix of paid/unpaid members, choose Mark paid, confirm the preview counts (will-change vs already-paid), execute, and verify paid status updates for exactly the right users.

Acceptance Scenarios:

1. Given selected members and a selected period, When Mark as paid is chosen, Then a preview shows "X will be marked paid, Y already paid (skipped)".
2. Given the preview, When confirmed, Then all not-yet-paid selected members become paid for that period in a single request, and already-paid members are untouched.
3. Given no contribution period is selected, When the menu is opened, Then the period-relative actions are disabled.

User Story 3 — Bulk end membership (Priority: P2)

A board member ends the membership of all selected members effective today, after a preview showing who has an active membership and who is skipped.

Why P2: Common end-of-year / graduation operation; independent of periods and emails.

Independent Test: Select members with and without active memberships, choose End membership, confirm the preview, execute, and verify every active membership's end date is set to today and members without an active membership are untouched.

Acceptance Scenarios:

1. Given selected members, When End membership is chosen, Then the preview shows "X memberships will end today, Y have no active membership (skipped)".
2. Given the preview, When confirmed, Then all active memberships of the selected members get an end date of today, in a single request.

User Story 4 — Bulk contribution reminder (Priority: P2)

A board member emails a contribution reminder to selected members who still owe for the selected period. The system resolves each member's fee by type, excludes those who shouldn't be emailed, lets the treasurer correct amounts, and records who was reminded.

Why P2: The first of the two "important and complicated" emails; delivers the core member-type-aware logic.

Independent Test: Select regular, alumni, honorary, and already-paid members; set a half-year cutoff date and a payment-due date; confirm the preview resolves each fee, excludes honorary (red) and already-paid, allows an amount correction, and on execute the right members receive an email quoting the corrected amount and due date, with audit rows written.

Acceptance Scenarios:

1. Given a mixed selection and a half-year cutoff date, When the reminder is previewed, Then each regular member shows the half-year fee if their membership started on/after the cutoff, otherwise the full-year fee; alumni show the alumni fee.
2. Given an honorary member in the selection, When previewed, Then they are shown in red, excluded from sending, with a warning that honorary members do not pay.
3. Given already-paid members in the selection, When previewed, Then they are excluded by default with the option to re-include.
4. Given the preview, When the treasurer edits a member's amount and confirms, Then the sent email quotes the edited amount and the chosen payment-due date.
5. Given a member reminded earlier this period, When previewed, Then a "last reminded on DATE" note is shown, but re-sending is still allowed.

User Story 5 — Bulk incasso notification (Priority: P3)

A board member notifies selected incasso members of an upcoming automatic debit for the selected period, with the same member-type fee resolution, plus a warning + default exclusion for members without an incasso mandate.

Why P3: Most complex, greenfield (new email type + audit entity); builds directly on US4's mechanics.

Independent Test: Select incasso and non-incasso members (incl. honorary and already-paid); set a half-year cutoff and an expected-incasso date; confirm non-incasso members are warned + excluded by default (re-includable), honorary excluded (red), already-paid excluded; on execute the right members receive an incasso email stating the resolved amount and incasso date, with audit rows written.

Acceptance Scenarios:

1. Given selected members without an incasso mandate, When the incasso notification is previewed, Then they are flagged with a warning and excluded by default, with an option to re-include specific users.
2. Given an expected-incasso date and cutoff, When confirmed, Then each included member receives an email stating the resolved (or corrected) amount and the incasso date.
3. Given honorary or already-paid members, When previewed, Then honorary are excluded (red) and already-paid are excluded by default.

Edge Cases

• No contribution period selected → period-relative actions (paid/unpaid/reminder/incasso) are disabled; end-membership remains available.
• A selected member has multiple active memberships → all are ended.
• A selected member has no email address → surfaced as a skip/warning in the email previews.
• A regular member has no membership start date resolvable against the cutoff → flagged for the treasurer to set the amount.
• Everyone in the selection is excluded (all honorary / all already-paid) → execute is blocked with a clear message.
• Double-submit of the confirm action → must not double-apply.
• Members selected then filtered out of view → still acted upon; the confirm dialog lists every selected member by name so nothing hidden is a surprise.

Requirements

Functional Requirements

• FR-001: The members table MUST provide a per-row selection checkbox and a header "select all displayed" checkbox that reflects checked / indeterminate / empty over the currently-displayed rows.
• FR-002: The selection MUST be a set of member identities that persists across search, filter, and sort changes, with an always-visible selected count and a Clear control.
• FR-003: The table MUST expose a bulk-actions menu (vertical triple-dot, top-right of the table) offering: Mark as paid, Mark as unpaid, Send contribution reminder, Send incasso notification, End membership.
• FR-004: Every action MUST follow a two-phase flow — a preview that returns a per-user summary + counts + warnings, then an execute — so the operator sees exactly what will happen before committing.
• FR-005: All action business logic (fee resolution, exclusions, end-dating, membership resolution) MUST live on the backend; the client only collects the selection + inputs and renders the preview.
• FR-006: Each action MUST be applied in a single backend request per action (no per-member request fan-out).
• FR-007: Period-relative actions (mark paid/unpaid, reminder, incasso, and the already-paid checks) MUST target the member manager's currently-selected contribution period; end-membership MUST be period-independent and effective today.
• FR-008: Mark paid MUST create a paid record for each not-yet-paid selected member for the period and skip those already paid; Mark unpaid MUST remove it and skip those not paid.
• FR-009: End membership MUST set the end date of every active membership of each selected member to today, skipping members with no active membership.
• FR-010: For both email actions, the fee MUST be resolved per member type: regular → full-year fee, or half-year fee if the member's membership started on/after a treasurer-supplied "half-year cutoff date"; alumni → alumni fee; honorary → excluded.
• FR-011: Honorary members MUST be excluded from both email actions (not sendable), shown red in the summary with a warning.
• FR-012: Members already marked paid for the period MUST be excluded by default from both email actions, with an option to re-include specific members.
• FR-013: For the incasso notification, members without an incasso mandate MUST be flagged with a warning and excluded by default, with an option to re-include specific members.
• FR-014: The preview MUST let the treasurer correct each included member's resolved amount before sending; execute MUST use the corrected amounts.
• FR-015: The contribution reminder MUST include a treasurer-supplied payment-due date; the incasso notification MUST include a treasurer-supplied expected-incasso date; both dates appear in the email body.
• FR-016: Every email send MUST write an audit record per (member, period); the preview MUST surface a "last sent on DATE" note for prior sends this period and still allow re-sending.
• FR-017: All bulk actions MUST require board-level authorization.
• FR-018: The confirm dialog MUST show counts, a per-member summary (name + member type), colour-coded exclusions (honorary red, warnings amber), re-include controls, editable amounts, and the required date inputs.
• FR-019: Execute MUST return a summary of what was applied (changed / skipped / queued counts) for operator feedback, and MUST be safe against accidental double-submit.

Key Entities

• Member selection: a set of member identities held on the client for the duration of the operation; not persisted.
• Contribution: the "paid" marker for a (member, period); created/removed by mark paid/unpaid.
• Membership: has a member type, an incasso flag, and start/end dates; end-membership sets its end date.
• Contribution period: carries the half-year, full-year, and alumni fees used for resolution.
• Reminder / Incasso-notification audit record: one per (member, period) recording that an email was sent and when.

Success Criteria

• SC-001: A board member can apply any bulk action to N selected members with exactly one backend request per action.
• SC-002: For any email action, no honorary member is ever emailed and no already-paid/non-incasso member is emailed unless explicitly re-included.
• SC-003: The amount and date shown in the confirm dialog exactly match the amount and date in the sent email (no drift between preview and result).
• SC-004: Every email send is recorded, so "who was contacted for this period, and when" is answerable from data.
• SC-005: The operator can always review the full per-member outcome (including hidden/filtered members) before any irreversible send.

Assumptions

• Actions operate on the member manager's currently-selected contribution period; when none is selected, period-relative actions are disabled.
• The existing mail templating/outbox and the existing ContributionReminder audit are reused; a parallel incasso-notification audit is added.
• Emails are English, matching the existing member-facing mail tone.
• Fees are read from the contribution period (half-year / full-year / alumni); there is no separate incasso amount.
• Send delivery is asynchronous (queued); execute reports what was queued, not final delivery status.

[jorisjonkers-dev-agents]

Implementation Plan — Member manager bulk actions

Spec: see the spec comment on this epic. Delivered as a stack of 4 PRs (sub-issues #415–#418).

Technical Context

• Backend: Spring Boot 4 (Kotlin), services/api. CQRS-style command handlers + permission evaluators (hasPermission('Domain','action'), BOARD). Mail = Thymeleaf + Markdown via per-domain EmailContent builders, async outbox, InMemoryEmailClient in tests.
• Frontend: Vue 3 + TS + Vuetify, services/frontend, MemberManager.vue + composables; hand-rolled v-table; generated OpenAPI client.
• Storage: existing entities — Contribution (paid marker, (userId, periodId)), ContributionPeriod (halfYearFee, fullYearFee, alumniFee), Membership (memberType, incasso, startDate, endDate), ContributionReminder (audit). New: IncassoNotification (audit).
• Testing: @SpringBootTest + MockMvc system tests in the integrationTest sourceset; Vitest unit + Playwright e2e on the frontend.

Architecture — shared two-phase contract

Every action is a domain-aligned preview + execute pair sharing one response envelope so the frontend uses a single confirm dialog:

BulkPreviewResponse {
  action, periodId?,
  counts: { selected, willApply, skipped, excluded, warned },
  rows: [ { userId, name, memberType,
            state: INCLUDED | SKIPPED | EXCLUDED_HONORARY | EXCLUDED_ALREADY_PAID | WARN_NO_INCASSO | WARN_NO_MEMBERSHIP | ... ,
            amount?, lastSentOn?, note? } ]
}

Execute takes the same selection + params, plus per-user overrides for the email actions:

BulkExecuteRequest { userIds, periodId?, dates?, includedUserIds?, amountOverrides? : {userId: amount} }
BulkExecuteResult  { applied, skipped, queued }

Rules enforced server-side (never on the client): fee resolution (cutoff vs membership start), honorary/already-paid/non-incasso exclusion, end-dating, membership resolution, audit writes, authorization.

Endpoints (domain-aligned, BOARD-gated)

Action	Preview	Execute
Mark paid/unpaid	POST /contributions/bulk/preview	POST /contributions/bulk/execute (op=paid|unpaid)
End membership	POST /memberships/bulk/end/preview	POST /memberships/bulk/end/execute
Contribution reminder	POST /contributionReminders/bulk/preview	POST /contributionReminders/bulk/execute
Incasso notification	POST /incassoNotifications/bulk/preview	POST /incassoNotifications/bulk/execute

The shared BulkPreviewResponse envelope is introduced in PR1 and reused by PR2/PR3.

Data model change

• New IncassoNotification audit entity mirroring ContributionReminder: composite (userId, contributionPeriodId) + timestamps. New EmailContent builder + async job type for the incasso email.

Testing strategy

• System tests (backend) per PR, asserting DB effects and — for emails — rendered body content via InMemoryEmailClient: resolved amount per member type (regular half vs full by cutoff, alumni), the correct due/incasso date, honorary get NO email, exclusions + opt-in behaviour, per-user overrides reflected in the body, audit rows written, and authorization (non-board rejected).
• Frontend: unit tests for the selection composable (persistent set, header checkbox tri-state) and the preview→dialog mapping; a Playwright e2e for select → menu → preview → confirm with mocked endpoints.

Phasing (stack)

1. PR1 (Bulk actions PR1 (backend): mark paid/unpaid + end-membership endpoints #415) — shared envelope + contributions/bulk (paid/unpaid) + memberships/bulk/end, preview+execute, system tests. No email/fee logic.
2. PR2 (Bulk actions PR2 (backend): bulk contribution reminder with fee resolution + exclusions + audit #416) — contributionReminders/bulk with fee resolution (cutoff), honorary + already-paid exclusion, per-user override, payment-due date, audit reuse, system tests asserting body content.
3. PR3 (Bulk actions PR3 (backend): incasso notification domain (entity + email + endpoints) #417) — IncassoNotification domain (entity, email builder, job) + incassoNotifications/bulk, incasso-mismatch warn+exclude, honorary + already-paid exclusion, per-user override, expected-incasso date, audit, system tests.
4. PR4 (Bulk actions PR4 (frontend): selection UI + triple-dot menu + shared confirm dialog #418) — frontend: house-styled checkboxes + select-all-displayed, persistent selection set + count/clear, triple-dot menu, shared confirm dialog wired to all endpoints (per-user amount edit, re-include toggles, date inputs, red honorary / amber warnings, SubmitButton progress), e2e.

Constitution check

No project constitution is established yet (Spec Kit constitution intentionally not vendored). Governing conventions applied: business logic backend-side (explicit here), Jakarta validation on request DTOs, board-level authorization matching existing endpoints, per-repo commits, no AI attribution.

Risks / notes

• OpenAPI regen: PR1–PR3 add endpoints/DTOs → openapi.json + TS client regen, which needs a DB env not available in the sandbox — flag on each backend PR; PR4 depends on the regenerated client.
• Async sends → execute reports queued counts, not delivery; delivery failures live in the existing outbox.
• Idempotency: rely on client submit-lock + the audit-based "last sent" warning; no hard dedupe.