01 — Product Overview (Fees Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases (contract level)
• 9. Assumptions (module)
• 10. Open questions (module-grain; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Fees module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, domain events, queue routes, permissions, and wire contracts are derived directly from src/modules/fees/**, src/modules/payments/**, src/modules/scheduler/**, src/infrastructure/bullmq/**, src/infrastructure/workers/finance.worker.ts, src/modules/rbac/permissions.constants.ts, studylyon-blueprint/04-Modules/Fees.md, and docs/IMPLEMENTATION_PLAN.md. No feature is invented — anything not present in source is flagged (planned) / (proposed) / (forward-looking) in Assumptions & Open Questions.

Heads-up: per the PRD, the mobile client is out of Phase 1; this package is the forward-looking spec the client will be built against later. Everything below is best-effort UI design on top of the current backend surface.

1. Purpose

Fees is the money lifecycle of a school: an admin defines a fee structure per class + academic term (line items such as tuition/lab/transport, a total, currency, due date, optional late fee); invoices are generated per student; payments are recorded against invoices (offline cash/mobile-money via the fees module, online gateway capture via the payments module); the system tracks dues (outstanding balances) and — via the scheduler — flags overdue invoices and enqueues payment reminders. Money rules come from studylyon-blueprint/04-Modules/Fees.md; the code is the source of truth.

2. Business goals

3. User goals

• Admin / bursar (accounts): define a term's fee structure once; generate invoices per student; see outstanding dues per invoice.
• Accountant (cashier): collect cash/mobile-money against an invoice and post a payment; never double-post (idempotency key).
• Parent / payer: see child's invoices and dues; pay online through the payments module; read receipts.
• Org admin: financial oversight (dues report, payment history).

4. Stakeholders

Org admin, bursar/accounts staff, cashier (Accountant role), parents, students, the notification/email pipeline, the scheduler (overdue + reminders), audit/compliance (event log), QA + design + engineering.

5. Why this exists

Fee collection is a money path: the backend already enforces the important invariants (one invoice per term, idempotent payments, soft-deleted structures, tenant isolation). The Client's job is to present balances and payment statuses authoritatively, never guess server state, and treat every write (payment, invoice generation, waiver (planned)) as server-confirmed.

6. Dependencies

7. Success metrics

• Invoice generation (single student) round-trip < 2 s (sync path today).
• Duplicate-invoice attempt handled as 409 100% of the time (never a crash).
• Payment replay with same idempotencyKey returns the original payment (no dup).
• Zero cross-tenant leaks in any fees list/detail (BaseRepository scope).
• Dues balance renders exact: totalAmount − paidAmount from server, not summed on the client.

8. Edge cases (contract level)

• Duplicate invoice (same student+structure+year) → 409 DUPLICATE_RESOURCE "Invoice already exists for this student and term." (fees.service.ts:107-113)
  • unique index.
• Pay on PAID/CANCELLED invoice → 409 DUPLICATE_RESOURCE "Invoice is already paid or cancelled." (fees.service.ts:155-160).
• Unknown structure / invoice → 404 RESOURCE_NOT_FOUND (fees.service.ts:71-77,101-106).
• Invalid Mongo id → CastError → 400 VALIDATION_ERROR "Invalid resource identifier." (http-exception.filter.ts:47-48,91-95).
• Delete structure is a soft delete (softDelete, base.repository.ts:68-74); invoices are not cascaded.
• Discounts reduce the invoice total (totalAmount = max(0, structureTotal − Σdisc), fees.service.ts:117-119) — invoices total never below 0; the discount is snapshotted on the invoice as discounts[].
• Overpayment has no cap server-side — @Min(0) only (record-payment.dto.ts:19); paidTotal >= totalAmount is what flips status to PAID (fees.service.ts:169-172).
• Human currency is not integer-minor-enforced in code — blueprint says minor units (Fees.md:63) but DTOs/schemas store plain Number (fee-structure.schema.ts:19-28); the client must format/dealMinor and the server should floor (gap, OQ-1).

9. Assumptions (module)

• PRD: mobile client out of Phase 1. This design is a forward-looking client-side spec; the backend is the contracts authority and the scheduler/late-fee surface is partially wired (see OQ-6/OQ-7).
• Money appears as plain numbers (Number) in every schema; the blueprint's "integer minor units" rule (Fees.md:63) is not enforced in code — treat server values as decimal units unless a conversion is established (OQ-1).
• Payment posting uses an idempotency key on the fees side (record-payment.dto.ts:31-34) but the online payments module instead uses a server-generated transactionReference (payments.service.ts:215-217) — two idempotency models.
• InvoiceIssued / PaymentCompleted → emails queue (event-queue-map.ts:41,42) → email worker; the FinanceWorker also handles these event types on invoice-generate (finance.worker.ts:49-68) but no. event is routed to that queue by the map — that branch is effectively idle today (OQ-5).
• Reminder + overdue are partially wired: repeatable cron jobs are registered (scheduler.service.ts:48-97) but OverdueScanJob.execute / FeeReminderJob.execute are not invoked anywhere, and no worker listens on payment-reminder (OQ-6).
• Late fees KML: FeeStructure.lateFee exists (fee-structure.schema.ts:33-34) but nothing consumes it — no late-fee application in code (OQ-7).
• Fees endpoints are guarded only by JwtAuthGuard (fees.controller.ts:24) — no @Permissions() metadata; only fees.collect exists in permissions.constants.ts:31 and default Accountant role has only ['fees.collect', 'student.read'] (role.schema.ts:42-48). Real RBAC is (planned) (OQ-9).

10. Open questions (module-grain; global ledger in 00-shared/12)

11. Glossary (this module)