Detailed Functional Requirements

Savings Schemes — Detailed Requirements

The deep specification for the gold savings scheme module — expanding the module summary into a full data model, testable requirements with acceptance criteria, status lifecycles, business rules, and known gaps. Customers enrol in a scheme and pay installments over a tenure; each installment is recorded as a balanced double-entry ledger pair. Bonus tiers and maturity handling are specified but not yet implemented — flagged throughout. Derived from the live scheme module.

Entities

Requirements

Concerns

Scheme products

Three types (fixed / flexible / weight-based) with a purity, tenure, and tiered bonuses.

Enrolment

A customer's plan: target amount, dates, and per-installment min/max.

Installments

Double-entry installment postings against the customer and scheme accounts.

Bonus & maturity

Tiered bonuses and maturity auto-complete — specified, not yet built.

Savings Schemes · Detailed

Data model

Three entities: the scheme product, the customer enrolment, and the installment transaction (which extends the finance ledger's account-transaction).

Scheme product

Field	Type	Notes
`name`	string (required)	Scheme name.
`type` key	enum	FIXED_AMOUNT / FLEXIBLE_AMOUNT / WEIGHT_BASED.
`purityTypeId` key	ObjectId → purity	Gold purity the scheme accrues in.
`duration`	number	Tenure (months).
`schemeAccountId` key	ObjectId → Account	GL account credited by each installment.
`cashAccountId`	ObjectId → Account	Optional cash account.
`benefits`	string[]	List of benefit lines.
`bonuses` key	SchemeBonus[]	Tiered: `{from, to, bonusType: AMOUNT/GRAM/PERCENT, bonusValue}`. not applied Defined but no calculation logic exists.

UserScheme enrolment

Field	Type	Notes
`userId`	ObjectId → User	The customer.
`schemeTypeId`	ObjectId → Scheme	The scheme product.
`status`	enum (default PENDING)	PENDING / ACTIVE / COMPLETED / CANCELLED.
`amount`	number	Total target amount for the plan.
`startDate`, `endDate`	number (unix)	Start and maturity. manual `endDate` is supplied, not derived from `duration`.
`minAmount`, `maxAmount`	number	Per-installment bounds. not enforced Stored but never validated.

UserSchemeTransaction installment

Extends the finance AccountTransaction; installments are posted as two linked rows.

Field	Type	Notes
`userSchemeId`	ObjectId → UserScheme	The enrolment being paid into.
`amount`	number	Installment amount.
`weight`, `rate`	number	Gold weight / rate — used for WEIGHT_BASED schemes.
`status`	enum (default PENDING)	PENDING / CONFIRMED / REJECTED.
`confirmedAt`, `confirmedBy`	number, ObjectId → User	Set when confirmed.
`accountId`, `type`, `kind`, `relationId`	inherited	DEBIT input account; CREDIT scheme account; `kind = SchemeTransaction`; shared `relationId` links the pair.

Savings Schemes · Detailed

Scheme products `SCH-P`

Administrators define the savings products — their type, purity, tenure, linked accounts, benefits, and bonus tiers.

FR-SCH-P01Must

The system SHALL allow administrators to create, update, soft-delete, query, and paginate scheme products, each carrying name, type, purity, duration, linked scheme/cash accounts, benefits, and tiered bonuses.

Acceptance criteria

Create requires name, type, purityTypeId, duration, and schemeAccountId.
Update is partial; delete is a soft delete.
List paginates (skip / take) with a total count.

FR-SCH-P02Must

The system SHALL support three scheme types — FIXED_AMOUNT, FLEXIBLE_AMOUNT, and WEIGHT_BASED.

Acceptance criteria

The type is stored as an enum on the product.
WEIGHT_BASED schemes capture weight and rate on their installments.

FR-SCH-P03Should

The system SHALL let a scheme define tiered bonuses as amount ranges, each with a bonus type (AMOUNT / GRAM / PERCENT) and a value.

Acceptance criteria

Each bonus tier stores from, to, bonusType, and bonusValue.
Tiers are stored on the product (their application is specified separately — see Bonuses).

Savings Schemes · Detailed

Enrolment `SCH-E`

A customer's enrolment into a scheme — the target amount, the term, and the per-installment bounds.

FR-SCH-E01Must

The system SHALL allow staff to enrol a customer with a target amount, start and end dates, and optional per-installment minimum and maximum; a new enrolment SHALL default to PENDING.

Acceptance criteria

Create requires userId, schemeTypeId, amount, startDate, endDate.
Status defaults to PENDING; minAmount / maxAmount are optional.
Listing resolves the linked customer and scheme; supports a date range filter.

FR-SCH-E02Must

The system SHALL allow an enrolment to move through PENDING → ACTIVE → COMPLETED, or to CANCELLED, administratively.

Acceptance criteria

Status is settable via update.
No state-machine guard or auto-completion is applied (see Maturity and Known gaps).

Savings Schemes · Detailed

Installment transactions `SCH-T`

Each installment is a balanced double-entry pair between the customer's account and the scheme account.

Posting

Leg	Posting	Shared
Installment	DR Customer / payment account (input) CR Scheme account (`scheme.schemeAccountId`)	same `amount`, same `relationId`, `kind = SchemeTransaction`

FR-SCH-T01Must

The system SHALL record an installment as a balanced pair of ledger entries sharing one relation id — a DEBIT to the supplied account and a CREDIT to the scheme's account — both tagged kind = SchemeTransaction.

Acceptance criteria

Creating an installment posts exactly two entries: DEBIT to the input accountId, CREDIT to scheme.schemeAccountId.
Both rows carry the same amount and the same generated relationId.
The DEBIT entry is returned to the caller.

FR-SCH-T02Must

The system SHALL validate that the enrolment and its parent scheme exist before posting, rejecting with a specific error otherwise.

Acceptance criteria

Missing/invalid userSchemeId → error "UserScheme not found".
Enrolment with no resolvable scheme → error "Scheme not found".

FR-SCH-T03Must

An installment SHALL move through PENDING → CONFIRMED (or REJECTED); confirmation SHALL record who confirmed it and when.

Acceptance criteria

A new installment defaults to PENDING.
Confirming records confirmedAt and confirmedBy.

FR-SCH-T04Should

For WEIGHT_BASED schemes, the system SHALL capture the gold weight and rate on each installment.

Acceptance criteria

weight and rate are stored on the transaction.

Savings Schemes · Detailed

Bonuses `SCH-B` not implemented

Tiered bonuses are defined on the product but their calculation and posting do not yet exist. These requirements specify the intended behaviour.

Planned — No bonus calculation or application logic is present in the codebase. The fields exist (FR-SCH-P03); the requirements below are the target.

FR-SCH-B01Shouldnot implemented

On scheme completion, the system SHALL select the bonus tier whose range contains the accumulated amount and compute the bonus by its type.

Acceptance criteria (target)

Tier = the bonus where from ≤ accumulated ≤ to.
AMOUNT → add bonusValue; PERCENT → add accumulated × bonusValue / 100; GRAM → add bonusValue grams valued at the prevailing rate.

FR-SCH-B02Shouldnot implemented

The system SHALL post the computed bonus as a credit to the customer when the scheme matures.

Acceptance criteria (target)

A bonus posting credits the customer's account at completion.
The applied bonus is recorded against the enrolment for audit.

Savings Schemes · Detailed

Maturity `SCH-M` not implemented

Tenure handling and auto-completion at the end date are specified but not built.

Planned — endDate is supplied manually rather than derived from duration, and nothing marks a scheme COMPLETED at maturity. The requirement below is the target.

FR-SCH-M01Shouldnot implemented

The system SHALL derive the maturity date from startDate + duration, and at maturity auto-complete the enrolment and trigger bonus application.

Acceptance criteria (target)

endDate is computed from startDate + duration at enrolment.
At endDate the enrolment moves to COMPLETED and bonus application (FR-SCH-B01/B02) runs.

Savings Schemes · Detailed

Statuses & key values

Scheme type

FIXED_AMOUNTFLEXIBLE_AMOUNTWEIGHT_BASED

Enrolment status

PENDINGACTIVECOMPLETEDCANCELLED

Installment status

PENDINGCONFIRMEDREJECTED

Bonus type

AMOUNTGRAMPERCENTkind: SchemeTransaction

Savings Schemes · Detailed

Business rules

Every installment is a balanced double-entry pair (DEBIT customer / CREDIT scheme account) sharing one relationId.
An installment cannot be posted unless both its enrolment and the parent scheme exist.
Deletes are soft across all three entities; all mutations are audited.
WEIGHT_BASED schemes track gold weight and rate per installment.

Savings Schemes · Detailed

Known gaps & risks

High — Bonus calculation and application are not implemented. Tiers are defined on the product but no logic computes or posts a bonus at any point (FR-SCH-B01/B02 are target).

High — The installment's two ledger legs are posted in parallel (not wrapped in a single database transaction). A failure on the CREDIT after the DEBIT succeeds can orphan one leg.

Medium — No maturity handling. endDate is supplied manually (not derived from duration), and nothing auto-completes a scheme at maturity (FR-SCH-M01 is target).

Medium — minAmount / maxAmount are stored on the enrolment but never enforced when an installment is recorded.

Medium — No status-machine guard: an enrolment can move between any states (e.g. COMPLETED → ACTIVE), and an installment can be posted against a PENDING or CANCELLED enrolment.

Low — No validation that an installment amount fits the scheme type's constraint (e.g. a fixed amount).

Savings Schemes — Detailed Requirements

Scheme products

Enrolment

Installments

Bonus & maturity

Data model

Scheme products SCH-P

Enrolment SCH-E

Installment transactions SCH-T

Posting

Bonuses SCH-B not implemented

Maturity SCH-M not implemented

Statuses & key values

Scheme type

Enrolment status

Installment status

Bonus type

Business rules

Known gaps & risks

Scheme products `SCH-P`

Enrolment `SCH-E`

Installment transactions `SCH-T`

Bonuses `SCH-B` not implemented

Maturity `SCH-M` not implemented