adamsaghy commented on code in PR #6143: URL: https://github.com/apache/fineract/pull/6143#discussion_r3703825646
########## fineract-doc/src/docs/en/chapters/features/working-capital-charge-off.adoc: ########## @@ -0,0 +1,240 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// + += Working Capital Loan Charge-Off + +This documentation describes the Charge-Off feature for Working Capital Loans. + +Charge-off marks a loan account as charged off for accounting purposes. In the Working Capital Loan +module it is modeled as a *pure accounting tag with no portfolio impact*: the loan stays `ACTIVE`, its +schedule and balance are unchanged, and all other actions and calculations behave exactly as they do on +a loan that is not charged off. This differs from the Term Loan implementation, whose charge-off carries +interest-recalculation behaviour — Working Capital Loans have no interest concept, so that machinery does +not apply here. + +[NOTE] +==== +Charge-off is an accounting treatment only. It does not change the schedule, balance or delinquency +data returned by the existing Working Capital Loan APIs; the loan resource only gains the charged-off +state fields (see <<wc-charge-off-read-model>>). The loan remains `ACTIVE` until its balance is cured, and the +charged-off tag is never removed automatically — even if the loan is subsequently paid off. It is +cleared only by an explicit undo. +==== + +== Charge-Off a Loan + +Marks the loan account as charged off and creates a non-monetary charge-off transaction. + +* *Endpoint*: `POST /working-capital-loans/{loanId}/transactions?command=chargeOff` +* *Permission*: `CHARGEOFF_WORKINGCAPITALLOAN` + +=== Supported Fields + +==== Mandatory Fields + +* `transactionDate` +** The charge-off date. It may be backdated but must not be in the future, and must not be earlier than +the last transaction date. + +* `locale` + +* `dateFormat` + +==== Optional Fields + +* `chargeOffReasonId` +** Code value id from the `ChargeOffReasons` code. + +* `note` +** Free-text note (up to 1000 characters). + +* `externalId` +** External identifier for the charge-off transaction (up to 100 characters). + +=== Behaviour + +* A non-monetary `CHARGE_OFF` transaction is created for the charge-off amount, which is the outstanding +balance as of the charge-off date. Because the charge-off date cannot precede the last transaction, the +current outstanding balance equals the as-of-date balance. +* The transaction does *not* move the loan balance and is excluded from transaction replay. +* The loan is flagged as charged off (`chargedOff = true`) and remains `ACTIVE`. +* Repayments and payment, waiver or adjustment of *existing* charges remain allowed afterwards, so the +balance can still be cured. While the loan is charged off, those credits are recognized as recovery +income and discount-fee amortization is routed to the charge-off expense (see <<wc-charge-off-accounting>>). +* Goodwill credit and payout refund are not supported while the loan is charged off; posting either one +is rejected. + +.Charge-off request/response flow +[plantuml,format=svg] +.... +@startuml +actor User +participant "Transactions API" as API +participant "ChargeOff Write Service" as SVC +participant "Accounting Processor" as ACC +database "m_wc_loan" as DB + +User -> API : POST .../transactions?command=chargeOff +API -> SVC : chargeOff(loanId, command) +SVC -> SVC : validate (active, not already charged off, date rules) +SVC -> DB : mark loan charged off + create CHARGE_OFF txn +SVC -> ACC : post charge-off journal entries +SVC --> User : transaction id +@enduml +.... + +== Undo Charge-Off + +Reverses a charge-off that was applied in error. + +* *Endpoint*: `POST /working-capital-loans/{loanId}/transactions?command=undoChargeOff` +* *Permission*: `UNDOCHARGEOFF_WORKINGCAPITALLOAN` + +Undo removes the charged-off tag, reverses the charge-off transaction and reverses its journal entries. +It is only allowed when no monetary transaction has been posted after the charge-off — non-monetary and +system transactions (for example discount-fee amortization) do not block undo. Review Comment: Same restriction should be applied as with progressive loans -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
