Add manual override to referral fees calculation

[Aryan20]

Description

This pull request introduces several enhancements and fixes to the affiliate referral and sales invoice handling logic, as well as updates to the data model and event hooks. The main improvements include more robust affiliate referral management, better handling of returns, and improved data consistency for affiliate tracking.

Affiliate Referral and Sales Invoice Logic Improvements:

• Added a new API function insert_manual_affiliate_referral in affiliate_referral.py to allow manual creation of affiliate referrals with validation for positive amounts and valid affiliates.
• Refactored the apply_referral_fee_rules function in sales_invoice.py to accept an optional sales_partner parameter, improving flexibility and code clarity. [1] [2]
• Enhanced return handling by adding an on_submit event in sales_invoice.py that voids affiliate referrals associated with returned invoices.

Data Model and Fixtures Updates:

• Added a new custom_affiliate link field to the Subscription doctype, allowing subscriptions to be directly associated with affiliates.
• Updated the position of the First Cost field in the Subscription doctype for better UI consistency.
• Set the title_field and enabled show_title_field_in_link for the Sales Partner doctype, improving display and selection in the UI.
• Included the is_manual field in the list of fields for Affiliate Referral to ensure proper tracking of manually created referrals.

Event Hooks and Business Logic Integration:

• Registered new event hooks for on_submit in Sales Invoice and before_insert in Subscription to ensure custom business logic is executed at appropriate lifecycle stages.
• Modified the invoice creation logic in subscription_override.py to assign the linked affiliate from the subscription to the generated invoice, ensuring accurate affiliate attribution.

Relevant Technical Choices

Testing Instructions

Additional Information:

Screenshot/Screencast

Checklist

• I have carefully reviewed the code before submitting it for review.
• This code is adequately covered by unit tests to validate its functionality.
• I have conducted thorough testing to ensure it functions as intended.
• A member of the QA team has reviewed and tested this PR (To be checked by QA or code reviewer)

[Copilot]

Pull request overview

This PR adds a manual override capability to the referral fees calculation by introducing an optional sales_partner parameter to the apply_referral_fee_rules function. This allows callers to specify a different sales partner than the one attached to the invoice document.

Key changes:

• Added optional sales_partner parameter to apply_referral_fee_rules function signature
• Modified the logic to use the override parameter when provided, falling back to doc.sales_partner otherwise

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The early return check on line 26 does not account for the new sales_partner parameter override. When a manual override is provided via the sales_partner parameter, this check should evaluate the override value instead of only checking doc.sales_partner. This creates inconsistent behavior where the function could return early even when a valid sales_partner override is passed.

[Copilot]

The ternary expression logic is inverted. It currently reads "use doc.sales_partner if sales_partner parameter is falsy, otherwise use sales_partner parameter", which means it only uses the override when it's truthy. However, the condition 'if not sales_partner' evaluates to True when sales_partner is None/empty, so the expression should be 'sales_partner if sales_partner else doc.sales_partner' to properly prioritize the override parameter when it's provided.