Fees setup workflow

When to do this, and who does it

This is a go-live and start-of-year job, not a daily one. Work through it after the academic year, the calendar and the class list exist, and finish it before the counter opens for the term you are billing. The whole sequence is owned by one person with fee operations access - Platform Admin, Principal, Vice Principal, Support Staff - Finance or Admin - except the last step, which needs a server administrator with shell access. Nobody outside those roles sees any of these screens, and families see only the invoices that come out of the end.

Treat the order as a dependency chain rather than a checklist. A structure needs its fee type. Late-fee, tax and reminder settings should be saved before the first invoices exist, so the first overdue cycle behaves like every later one. Generation comes last because a fee instance copies the amount and due date from the structure and then stops looking at it, so an invoice created against a wrong structure stays wrong after the structure is corrected.

Prerequisites

• An active academic year with start and end dates at /academic-year, because a structure belongs to a year and an installment due date is derived from the year start when the structure has none.
• Classes with students actively enrolled at /classes and /students. Generation matches the class a student is enrolled in first and only falls back to grade and section.
• SMTP configured and passing /settings/email-test, since receipt email and every dunning email from the second step onwards use it.
• A decision on the checkout mode, because FEES_ONLINE_PAYMENT_MODE and its NEXT_PUBLIC_ mirror are environment variables and changing them later needs a redeploy.

The sequence

1. Create fee types at /fees/fee-types - tuition, admission, lab, activity. Create the code TRN now if the school runs buses, because transport looks up that exact code and silently creates nothing when it is absent.
2. Build structures at /fees/fee-structures - amount, installment count, first due date and grace days, per class or per grade, for the active year.
3. Check the installment schedule at /fees/fee-schedule. The grid of types against grades is where a missing or duplicated structure shows up; editing remains role-gated on the same canonical screen.
4. Configure the settings: /fees/settings/late-fees for the penalty, /fees/settings/gst or /fees/settings/vat for tax lines, /fees/settings/dunning for the reminder ladder.
5. Generate at /fees/bulk-generate, or per class from /fees/setup. Start with one class. Generation is per student and only fills gaps, so re-running it later for new admissions is safe.
6. Verify /fees/class-summary against the published fee circular, then open a single student ledger to confirm the installment dates, before letting anyone take payment.
7. Have a server administrator schedule scripts/run-school-cron.sh daily with FEES_CRON_SECRET and BASE_URL set, then confirm the fees.dunning heartbeat on /ops.

What goes wrong when the order slips

Limits worth knowing before you start

• No discount rules engine. Sibling and staff-ward concessions are labels on a hand-entered waiver that a second person approves; nothing is derived from family relationships or staff status.
• The late fee is advisory. It is shown at the counter as the amount due if the family paid today and is never posted to the fee instance.
• Multi-installment structures split the amount evenly and space due dates evenly across the year.
• Fee types and structures carry no school id, so a deployment holding more than one school shares one fee catalogue.