fix(landms): payment-term allocation, sync circular-cancel, lifecycle automation

Payment sync: build PE reference rows per SI payment-term so ERPNext
updates each schedule row's paid_amount. Previously only SI outstanding
moved — per-row paid stayed 0, so contract advance/completion never fired.

Cancellation: back-reference Link fields (SO <-> SI, Plot Application,
Plot Contract, Plot Handover) now stored as Data. Frappe only walks Link
fields during cancel, so the circular dependency that blocked cancellation
is gone. Migration patch rewrites existing rows in place.

Lifecycle: Sales Order is auto-created on application-fee payment; TCB
registration runs inline for immediate control-number feedback; PEs from
TCB are named by transaction_id for audit trace; Plot Handover Draft is
created automatically on contract completion.

Other: application fee item sourced from LandMS Settings; Plot Master
Stock Entry pins expense_account to Land Under Development so plot
creation doesn't inherit the item's delivery-side COGS default.

Author: BeautifulPixelsTech

landms/landms/doctype/landms_settings/landms_settings.json

@@ -99,6 +99,14 @@
    "fieldtype": "Section Break",
    "label": "Application Fee"
   },
+  {
+   "fieldname": "application_fee_item",
+   "fieldtype": "Link",
+   "label": "Application Fee Item",
+   "options": "Item",
+   "reqd": 1,
+   "description": "Service item used on the application fee Sales Invoice"
+  },
   {
    "fieldname": "application_fee_amount",
    "fieldtype": "Float",

landms/landms/doctype/plot_application/plot_application.js

@@ -25,42 +25,6 @@ frappe.ui.form.on('Plot Application', {
             }, __('Actions'));
         }
 
-        // Create Sales Order — only on Paid applications
-        if (frm.doc.docstatus === 1 && frm.doc.status === 'Paid' && !frm.doc.sales_order) {
-            frm.add_custom_button(__('Create Sales Order'), () => {
-                frappe.call({
-                    method: 'create_sales_order',
-                    doc: frm.doc,
-                    args: { notify: 1 },
-                    freeze: true,
-                    freeze_message: __('Creating Sales Order...'),
-                    callback(r) {
-                        if (!r.exc) frm.reload_doc();
-                    },
-                });
-            }, __('Actions'));
-        }
-
-        // Cancel Application — manual cancellation for Submitted or Paid
-        if (frm.doc.docstatus === 1 && ['Submitted', 'Paid'].includes(frm.doc.status)) {
-            frm.add_custom_button(__('Cancel Application'), () => {
-                frappe.confirm(
-                    __('Are you sure you want to cancel this Plot Application? The plot will be released and any linked Sales Order will be cancelled.'),
-                    () => {
-                        frappe.call({
-                            method: 'frappe.client.cancel',
-                            args: { doctype: 'Plot Application', name: frm.doc.name },
-                            freeze: true,
-                            freeze_message: __('Cancelling...'),
-                            callback(r) {
-                                if (!r.exc) frm.reload_doc();
-                            },
-                        });
-                    }
-                );
-            }, __('Actions'));
-        }
-
         // Jump to the linked Sales Order
         if (frm.doc.sales_order) {
             frm.add_custom_button(__('View Sales Order'), () => {
@@ -148,7 +112,7 @@ function open_fee_payment_dialog(frm) {
                         reference_no: values.reference_no || '',
                     },
                     freeze: true,
-                    freeze_message: __('Recording payment...'),
+                    freeze_message: __('Recording payment & creating Sales Order...'),
                     callback(r) {
                         if (!r.exc) {
                             d.hide();

landms/landms/doctype/plot_application/plot_application.json

@@ -155,17 +155,15 @@
   },
   {
    "fieldname": "sales_invoice",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Sales Invoice",
-   "options": "Sales Invoice",
    "read_only": 1,
    "description": "Sales Invoice created for the application fee"
   },
   {
    "fieldname": "payment_entry",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Payment Entry",
-   "options": "Payment Entry",
    "read_only": 1,
    "description": "Payment Entry that settled the application fee SI"
   },
@@ -177,9 +175,8 @@
   },
   {
    "fieldname": "sales_order",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Sales Order",
-   "options": "Sales Order",
    "read_only": 1,
    "description": "ERP Sales Order created after application fee payment"
   },

landms/landms/doctype/plot_application/plot_application.py

@@ -258,6 +258,9 @@ def record_fee_payment(self, payment_date, bank_account=None, reference_no=None)
 		self._validate_receiving_account(bank_account, settings.company)
 
 		# --- Sales Invoice ---
+		if not settings.application_fee_item:
+			frappe.throw("Application Fee Item is not configured in LandMS Settings.")
+
 		si = frappe.get_doc({
 			"doctype":      "Sales Invoice",
 			"customer":     self.customer,
@@ -266,8 +269,7 @@ def record_fee_payment(self, payment_date, bank_account=None, reference_no=None)
 			"company":      settings.company,
 			"remarks":      f"Application fee for Plot {self.plot} — Application {self.name}",
 			"items": [{
-				"item_name":      "Application Fee",
-				"description":    f"Plot application fee — {self.name} / Plot {self.plot}",
+				"item_code":      settings.application_fee_item,
 				"qty":            1,
 				"rate":           fee_amount,
 				"income_account": settings.application_fee_income_account,
@@ -313,11 +315,12 @@ def record_fee_payment(self, payment_date, bank_account=None, reference_no=None)
 		frappe.db.set_value("Plot Master", self.plot, "status", "Pending Advance")
 		self._sync_land_acquisition_summary()
 
+		so_name = self.create_sales_order(notify=0)
+
 		frappe.msgprint(
 			f"Application fee of TZS {fee_amount:,.0f} recorded. "
-			f"Plot {self.plot} is now Pending Advance until {expiry}. "
-			f"Sales Invoice {si.name} settled via Payment Entry {pe.name}. "
-			"Next: create the Sales Order and collect the first advance within the validity window.",
+			f"Sales Order <b>{so_name}</b> created for Plot {self.plot}. "
+			f"Reservation valid until {expiry}.",
 			indicator="green",
 			alert=True,
 		)

landms/landms/doctype/plot_contract/plot_contract.json

@@ -137,8 +137,8 @@
    "fieldname": "apply_auto_cancellation",
    "fieldtype": "Check",
    "label": "Apply Auto-Cancellation",
-   "default": "1",
-   "description": "Inherited from Sales Order. Uncheck to allow payment beyond deadline."
+   "read_only": 1,
+   "description": "Inherited from Sales Order. Change it on the Sales Order to update this value."
   },
   {
    "fieldname": "control_number",
@@ -264,16 +264,14 @@
   },
   {
    "fieldname": "sales_order",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Sales Order",
-   "options": "Sales Order",
    "read_only": 1
   },
   {
    "fieldname": "plot_application",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Plot Application",
-   "options": "Plot Application",
    "read_only": 1
   },
   {
@@ -282,24 +280,21 @@
   },
   {
    "fieldname": "booking_fee_invoice",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Plot Sales Invoice",
-   "options": "Sales Invoice",
    "read_only": 1
   },
   {
    "fieldname": "government_fee_entry",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Government Fee Journal Entry",
-   "options": "Journal Entry",
    "read_only": 1,
    "depends_on": "eval:doc.government_fee_entry"
   },
   {
    "fieldname": "forfeiture_entry",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Forfeiture Journal Entry",
-   "options": "Journal Entry",
    "read_only": 1,
    "depends_on": "eval:doc.forfeiture_entry"
   },

landms/landms/doctype/plot_contract/plot_contract.py

@@ -333,6 +333,7 @@ def sync_payment_status(self):
 		invoice_name = self._get_plot_invoice_name()
 		if not invoice_name:
 			self._sync_header_from_sales_order(so_doc)
+			self._persist_payment_sync_state()
 			return
 
 		si_doc = frappe.get_doc("Sales Invoice", invoice_name)
@@ -346,24 +347,21 @@ def sync_payment_status(self):
 		if len(self.payment_schedule or []) != len(si_doc.payment_schedule or []) and self.docstatus == 0:
 			self._rebuild_schedule_from_invoice(si_doc)
 
+		self._sync_header_from_sales_order(so_doc, invoice_name=si_doc.name)
+		self._sync_schedule_rows_from_invoice(si_doc, paid_dates)
+		self.total_contract_value = flt(si_doc.grand_total)
+		self.total_paid = total_paid
+		self.total_outstanding = total_outstanding
+		self.payment_progress = self._derive_payment_progress(total_paid, total_outstanding, si_doc=si_doc)
+		self._persist_payment_sync_state()
+
 		advance_met = self._is_advance_installment_met(si_doc)
 
-		# Only auto-submit the contract once the full advance is covered.
+		# Only auto-submit once the synced draft state is already safely saved.
 		if advance_met and self.docstatus == 0:
 			self.submit()
 			self.reload()
 
-		self._sync_header_from_sales_order(so_doc, invoice_name=si_doc.name)
-		self._sync_schedule_rows_from_invoice(si_doc, paid_dates)
-		self.db_set("total_contract_value", flt(si_doc.grand_total), update_modified=False)
-		self.db_set("total_paid", total_paid, update_modified=False)
-		self.db_set("total_outstanding", total_outstanding, update_modified=False)
-		self.db_set(
-			"payment_progress",
-			self._derive_payment_progress(total_paid, total_outstanding, si_doc=si_doc),
-			update_modified=False,
-		)
-
 		if so_doc.get("plot_application"):
 			app_status = frappe.db.get_value("Plot Application", so_doc.plot_application, "status")
 			if advance_met and app_status == "Paid":
@@ -372,38 +370,47 @@ def sync_payment_status(self):
 					so_doc.plot_application,
 					"status",
 					"Converted",
+					update_modified=True,
 				)
+				frappe.clear_document_cache("Plot Application", so_doc.plot_application)
 
 		if total_outstanding <= 0 and self.docstatus == 1:
-			self.db_set("contract_status", "Completed", update_modified=False)
+			self.contract_status = "Completed"
 			plot_status = frappe.db.get_value("Plot Master", self.plot, "status")
 			if plot_status not in ("Delivered", "Title Closed"):
-				frappe.db.set_value("Plot Master", self.plot, "status", "Ready for Handover")
+				frappe.db.set_value("Plot Master", self.plot, "status", "Ready for Handover", update_modified=True)
+				frappe.clear_document_cache("Plot Master", self.plot)
 			self._sync_land_acquisition_summary()
 
+			# Persist the submitted contract state before posting linked entries.
+			self._persist_payment_sync_state()
 			settings = frappe.get_single("LandMS Settings")
 			self.reload()
 			je_name = self._post_completion_entries(settings)
+			handover_name = self._ensure_handover_draft()
 
 			msg = f"Contract fully paid. Plot {self.plot} marked as Ready for Handover."
 			if je_name:
 				msg += f" Government fee posted — Journal Entry: {je_name}."
+			if handover_name:
+				msg += f" Plot Handover <b>{handover_name}</b> created (Draft) — fill the handover parties and submit."
 			frappe.msgprint(msg, indicator="green", alert=True)
+			return  # already saved above
 
 		elif advance_met and self.docstatus == 1:
-			self.db_set("contract_status", "Ongoing", update_modified=False)
+			self.contract_status = "Ongoing"
 			if frappe.db.get_value("Plot Master", self.plot, "status") == "Pending Advance":
-				frappe.db.set_value("Plot Master", self.plot, "status", "Reserved")
+				frappe.db.set_value("Plot Master", self.plot, "status", "Reserved", update_modified=True)
+				frappe.clear_document_cache("Plot Master", self.plot)
 				self._sync_land_acquisition_summary()
 
+		self._persist_payment_sync_state()
+
 	def _sync_header_from_sales_order(self, so_doc, *, invoice_name: str | None = None):
-		updates = {
-			"plot_application": so_doc.get("plot_application") or "",
-			"control_number": so_doc.get("control_number") or "",
-			"booking_fee_invoice": invoice_name or so_doc.get("plot_sales_invoice") or "",
-			"payment_deadline": so_doc.get("payment_deadline"),
-		}
-		frappe.db.set_value("Plot Contract", self.name, updates, update_modified=False)
+		self.plot_application = so_doc.get("plot_application") or ""
+		self.control_number = so_doc.get("control_number") or ""
+		self.booking_fee_invoice = invoice_name or so_doc.get("plot_sales_invoice") or ""
+		self.payment_deadline = so_doc.get("payment_deadline")
 
 	def _rebuild_schedule_from_invoice(self, invoice):
 		# Compute expected from the original grand_total * invoice_portion,
@@ -450,21 +457,39 @@ def _sync_schedule_rows_from_invoice(self, invoice, paid_dates):
 			status = self._derive_installment_status(source.due_date, expected, outstanding, today_date=today_date)
 			paid_date = paid_dates.get(idx) if outstanding <= 0 else None
 
-			frappe.db.set_value(
-				"Plot Contract Payment",
-				target.name,
-				{
-					"description": source.description or self._default_installment_label(idx),
-					"due_date": source.due_date,
-					"expected_amount": expected,
-					"paid_amount": paid_amount,
-					"outstanding_amount": outstanding,
-					"paid_date": paid_date,
-					"sales_invoice": invoice.name,
-					"status": status,
-				},
-				update_modified=False,
-			)
+			target.description = source.description or self._default_installment_label(idx)
+			target.due_date = source.due_date
+			target.expected_amount = expected
+			target.paid_amount = paid_amount
+			target.outstanding_amount = outstanding
+			target.paid_date = paid_date
+			target.sales_invoice = invoice.name
+			target.status = status
+			if self.docstatus == 1 and target.name:
+				target.db_update()
+
+	def _persist_payment_sync_state(self):
+		if self.docstatus == 0:
+			self.save(ignore_permissions=True)
+			return
+
+		frappe.db.set_value(
+			"Plot Contract",
+			self.name,
+			{
+				"plot_application": self.plot_application or "",
+				"control_number": self.control_number or "",
+				"booking_fee_invoice": self.booking_fee_invoice or "",
+				"payment_deadline": self.payment_deadline,
+				"total_contract_value": flt(self.total_contract_value),
+				"total_paid": flt(self.total_paid),
+				"total_outstanding": flt(self.total_outstanding),
+				"payment_progress": self.payment_progress or "",
+				"contract_status": self.contract_status or "Draft",
+			},
+			update_modified=True,
+		)
+		frappe.clear_document_cache("Plot Contract", self.name)
 
 	def _derive_installment_status(self, due_date, expected, outstanding, *, today_date=None):
 		today_date = today_date or getdate(today())
@@ -585,6 +610,31 @@ def _post_completion_entries(self, settings):
 		self.db_set("government_fee_entry", je.name)
 		return je.name
 
+	def _ensure_handover_draft(self):
+		existing = frappe.db.get_value(
+			"Plot Handover",
+			{"contract": self.name, "docstatus": ["!=", 2]},
+			"name",
+		)
+		if existing:
+			return existing
+
+		handover = frappe.get_doc({
+			"doctype": "Plot Handover",
+			"contract": self.name,
+			"handover_date": today(),
+			"customer": self.customer,
+			"plot": self.plot,
+			"acquisition_name": self.get("acquisition_name") or "",
+			"land_acquisition": self.get("land_acquisition") or "",
+			"contract_date": self.get("contract_date"),
+			"selling_price": flt(self.selling_price),
+		})
+		handover.flags.ignore_permissions = True
+		handover.flags.ignore_mandatory = True
+		handover.insert()
+		return handover.name
+
 	def _post_termination_journal_entry(self, settings):
 		if self.forfeiture_entry:
 			return None

landms/landms/doctype/plot_handover/plot_handover.json

@@ -39,9 +39,8 @@
   },
   {
    "fieldname": "delivery_note",
-   "fieldtype": "Link",
+   "fieldtype": "Data",
    "label": "Delivery Note",
-   "options": "Delivery Note",
    "read_only": 1,
    "description": "Created automatically on submit to reduce serialized plot stock"
   },