knowledge(data-modeling): cover prepayment, service line and ExclTax helper in Prices Including VAT article

Extend the community article on sales/purchase line prices following the
header's Prices Including VAT:

- Group the line fields: fields that follow the header flag (Unit Price,
  Direct Unit Cost, Line Amount, discounts, Prepmt. Line Amount,
  Prepmt. Amt. Inv., Prepmt Amt to Deduct, Prepmt Amt Deducted) versus
  fields with a fixed basis (Amount, VAT Base Amount, Prepayment Amount
  are net; Amount Including VAT, Prepmt. Amt. Incl. VAT,
  Prepmt. Amount Inv. Incl. VAT are gross).
- Add the rule to combine only fields of the same group, with BaseApp's
  UpdatePrepmtAmounts as the correct example.
- Add the misleading-name case: CalculateOutstandingAmountExclTax on
  Sales Line and Purchase Line is based on Line Amount and includes VAT
  on a Prices Including VAT document. BaseApp pairs it only with
  Prepmt. Line Amount (same basis); extension code that treats it as net
  is wrong.
- Mention that Service Line uses the same caption switch and
  UpdateVATAmounts split for Unit Price and Line Amount.
- Samples: add GetOutstandingNetAmount (bad: trusts the helper's name;
  good: takes the uninvoiced share of Amount).
- al-data-modeling-review: widen the scope and the worklist rule to
  service lines, the extra prepayment fields and
  CalculateOutstandingAmountExclTax, and exclude code that only combines
  fields of the same group.

Verified against BCApps W1 BaseApp (SalesLine, PurchaseLine, ServiceLine,
SalesHeader, Sales Line CaptionClass Mgmt).

Refs #151

community/knowledge/data-modeling/document-line-prices-follow-prices-including-vat.bad.al

@@ -16,6 +16,13 @@ codeunit 50641 "Sales Doc. VAT Basis Bad"
             until SalesLine.Next() = 0;
     end;
 
+    procedure GetOutstandingNetAmount(SalesLine: Record "Sales Line"): Decimal
+    begin
+        // Wrong: despite its name, CalculateOutstandingAmountExclTax is based on "Line Amount"
+        // and therefore includes VAT on a Prices Including VAT document.
+        exit(SalesLine.CalculateOutstandingAmountExclTax());
+    end;
+
     procedure SetUnitPriceFromNetSourcePrice(var SalesLine: Record "Sales Line"; NetSourcePrice: Decimal)
     begin
         // Wrong: on a Prices Including VAT document this net price is read as a gross price,

community/knowledge/data-modeling/document-line-prices-follow-prices-including-vat.good.al

@@ -14,6 +14,22 @@ codeunit 50640 "Sales Doc. VAT Basis Good"
         GrossTotal := SalesLine."Amount Including VAT";
     end;
 
+    procedure GetOutstandingNetAmount(SalesLine: Record "Sales Line"): Decimal
+    var
+        SalesHeader: Record "Sales Header";
+        Currency: Record Currency;
+    begin
+        if SalesLine.Quantity = 0 then
+            exit(0);
+        SalesHeader.Get(SalesLine."Document Type", SalesLine."Document No.");
+        Currency.Initialize(SalesHeader."Currency Code");
+        // Amount is net after line and invoice discounts on every document, so the
+        // uninvoiced share needs no VAT conversion.
+        exit(Round(
+            SalesLine.Amount * (SalesLine.Quantity - SalesLine."Quantity Invoiced") / SalesLine.Quantity,
+            Currency."Amount Rounding Precision"));
+    end;
+
     procedure SetUnitPriceFromNetSourcePrice(var SalesLine: Record "Sales Line"; NetSourcePrice: Decimal)
     var
         SalesHeader: Record "Sales Header";

community/knowledge/data-modeling/document-line-prices-follow-prices-including-vat.md

@@ -1,44 +1,49 @@
 ---
 bc-version: [all]
 domain: data-modeling
-keywords: [prices-including-vat, unit-price, line-amount, direct-unit-cost, prepmt-line-amount, amount-including-vat, sales-line, purchase-line, net-gross]
+keywords: [prices-including-vat, unit-price, line-amount, direct-unit-cost, prepmt-line-amount, amount-including-vat, sales-line, purchase-line, service-line, net-gross]
 technologies: [al]
 countries: [w1]
 application-area: [all]
 ---
 
-# Sales and purchase line prices follow the header's Prices Including VAT
+# Sales, purchase, and service line prices follow the header's Prices Including VAT
 
 > Contributions welcome — open a PR to refine or extend this article.
 
 ## Description
 
-Line prices are gross or net depending on the header's `Prices Including VAT`. When the flag is set, `Unit Price` (sales), `Direct Unit Cost` (purchase), `Line Amount`, `Line Discount Amount`, `Inv. Discount Amount`, and `Prepmt. Line Amount` all include VAT; when it is cleared they exclude it. Only `Amount` (always net), `Amount Including VAT` (always gross), and `VAT Base Amount` keep a fixed basis. Code that reads or writes the price fields without looking at the header flag is wrong for every document whose customer or vendor uses the other setting.
+Line prices are gross or net depending on the header's `Prices Including VAT`. When the flag is set, `Unit Price` (sales, service), `Direct Unit Cost` (purchase), `Line Amount`, `Line Discount Amount`, `Inv. Discount Amount`, and the prepayment fields `Prepmt. Line Amount`, `Prepmt. Amt. Inv.`, `Prepmt Amt to Deduct`, and `Prepmt Amt Deducted` all include VAT. When it is cleared they exclude it. Only `Amount`, `VAT Base Amount`, and `Prepayment Amount` (always net) and `Amount Including VAT`, `Prepmt. Amt. Incl. VAT`, and `Prepmt. Amount Inv. Incl. VAT` (always gross) keep a fixed basis. Code that mixes the two groups without looking at the header flag is wrong for every document whose customer or vendor uses the other setting.
 
 ## Best Practice
 
 When code needs a known basis — exports, integrations, KPIs, custom totals, commission or margin calculations — read `Amount` for net and `Amount Including VAT` for gross. Both are already reduced by line and invoice discounts and are maintained by the line's VAT calculation, so no VAT arithmetic is needed.
 
-When code writes a price from an external source whose basis is known (an EDI price list, an API payload, a web-shop order), get the document header and convert the source price into the header's basis before validating `Unit Price` or `Direct Unit Cost`, using the line's `VAT %` and the currency's `Unit-Amount Rounding Precision`. Alternatively, set `Prices Including VAT` on the header to match the source before the first line is created. Toggling it later on a header with priced lines asks the user to confirm a recalculation. Without a UI session, or when validation dialogs are hidden, BaseApp converts all line prices without asking.
+When code combines fields, pair fields of the same group. BaseApp's `UpdatePrepmtAmounts` sets `Prepmt. Line Amount` from `Line Amount` minus `Inv. Discount Amount`. This is correct because all three follow the header flag. `Prepmt. Amt. Inv.` pairs with `Prepmt. Line Amount`; `Prepmt. Amount Inv. Incl. VAT` pairs only with other gross values.
+
+When code writes a price from an external source whose basis is known (an EDI price list, an API payload, a web-shop order), get the document header and convert the source price into the header's basis before validating `Unit Price` or `Direct Unit Cost`, using the line's `VAT %` and the currency's `Unit-Amount Rounding Precision`. Alternatively, set `Prices Including VAT` on the header to match the source before the first line is created. Toggling it later on a sales header with priced lines asks the user to confirm a recalculation. Without a UI session, or when validation dialogs are hidden, BaseApp converts all line prices without asking.
 
 The standard price calculation already converts a `Price List Line` whose `Price Includes VAT` differs from the document's setting, so a price it returns is in the document's basis and must not be converted a second time.
 
-The same rule applies to the purchase mirror fields. On purchase lines, `Unit Cost` and `Unit Cost (LCY)` are derived from `Direct Unit Cost` with VAT removed, so they stay net.
+On purchase lines, `Unit Cost` and `Unit Cost (LCY)` are derived from `Direct Unit Cost` with VAT removed, so they stay net. Service lines follow the same rule for `Unit Price` and `Line Amount`: they share the caption switch and the `UpdateVATAmounts` split of the sales line.
 
 See sample: [`document-line-prices-follow-prices-including-vat.good.al`](document-line-prices-follow-prices-including-vat.good.al).
 
 ## Anti Pattern
 
-Treating `Unit Price`, `Direct Unit Cost`, or `Line Amount` as net by default. Typical signals: summing `Line Amount` as a document's net total, computing VAT as `Line Amount * "VAT %" / 100`, putting a known net or gross external price straight into `Unit Price` or `Direct Unit Cost`, or comparing a line price with `Item."Unit Price"` or `Item."Last Direct Cost"` — all without reading the header's `Prices Including VAT`. For a gross-price customer at 19 % VAT, a net total built from `Line Amount` is 19 % too high, and a net price of 100 imported unconverted yields a net revenue of only 84.03. A variable or procedure name ending in `ExclVAT` or `Net` that is fed from `Line Amount` is a strong signal of this mistake. BaseApp's own `CalculateOutstandingAmountExclTax` shows that the name alone guarantees nothing: it returns a value based on `Line Amount`.
+Treating `Unit Price`, `Direct Unit Cost`, or `Line Amount` as net by default. Typical signals: summing `Line Amount` as a document's net total, computing VAT as `Line Amount * "VAT %" / 100`, putting a known net or gross external price straight into `Unit Price` or `Direct Unit Cost`, or comparing a line price with `Item."Unit Price"` or `Item."Last Direct Cost"` — all without reading the header's `Prices Including VAT`. For a gross-price customer at 19 % VAT, a net total built from `Line Amount` is 19 % too high, and a net price of 100 imported unconverted yields a net revenue of only 84.03.
 
-Do not report code that reads the header flag, uses `Amount` or `Amount Including VAT`, or only passes values between two lines of the same document (same basis on both sides).
+Trusting a name instead of the source fields. The public procedure `CalculateOutstandingAmountExclTax` on `Sales Line` and `Purchase Line` returns `Line Amount` minus `Inv. Discount Amount` for the uninvoiced quantity, so its result includes VAT on a `Prices Including VAT` document despite its name. BaseApp only combines it with `Prepmt. Line Amount`, which has the same basis. Extension code that uses it as a net outstanding amount — compared with `Amount`, exported as net, or used to compute VAT — has this defect. The same applies to any variable or procedure named `ExclVAT`, `ExclTax`, or `Net` that is fed from a header-dependent field.
+
+Do not report code that reads the header flag, uses only fixed-basis fields, or only combines fields of the same group (for example, prepayment amounts derived from `Line Amount`, or values copied between two lines of the same document).
 
 See sample: [`document-line-prices-follow-prices-including-vat.bad.al`](document-line-prices-follow-prices-including-vat.bad.al).
 
 ## References
 
 - [BCApps: Sales Header `Prices Including VAT` OnValidate recalculates line prices](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Sales/Document/SalesHeader.Table.al).
-- [BCApps: Sales Line `UpdateVATAmounts` derives `Amount` from `Line Amount` per basis](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Sales/Document/SalesLine.Table.al).
+- [BCApps: Sales Line `UpdateVATAmounts`, `UpdatePrepmtAmounts`, and `CalculateOutstandingAmountExclTax`](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Sales/Document/SalesLine.Table.al).
 - [BCApps: `Sales Line CaptionClass Mgmt` switches captions to Incl./Excl. VAT](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Sales/Document/SalesLineCaptionClassMgmt.Codeunit.al).
 - [BCApps: Purchase Line `UpdateUnitCost` removes VAT from `Direct Unit Cost`](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Purchases/Document/PurchaseLine.Table.al).
+- [BCApps: Service Line `GetCaptionClass` and `UpdateVATAmounts`](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Service/Document/ServiceLine.Table.al).
 - [BCApps: `Price Calculation Buffer Mgt.` `ConvertAmountByTax`](https://github.com/microsoft/BCApps/blob/main/src/Layers/W1/BaseApp/Pricing/Calculation/PriceCalculationBufferMgt.Codeunit.al).