Add AL documentation for PEPPOL

Bootstrap docs for the PEPPOL app using al-docs init.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Magnus Hartvig Grønbech

src/Apps/W1/PEPPOL/App/CLAUDE.md

@@ -0,0 +1,105 @@
+# PEPPOL BIS 3.0 Electronic Invoicing
+
+Export engine that transforms posted Sales and Service documents into
+PEPPOL BIS 3.0 UBL XML for European e-invoicing compliance.
+
+## What it does
+
+Reads posted invoices/credit memos (sales **and** service), validates them
+against PEPPOL business rules, then serializes to UBL 2.1 XML via
+dedicated XmlPorts. No import path exists -- this is export-only.
+
+## Architecture at a glance
+
+The entire app is built on a **strategy/interface pattern** with a single
+extensible enum (`PEPPOL 3.0 Format`) as the dispatch mechanism:
+
+```
+Setup table  -->  Enum "PEPPOL 3.0 Format"  -->  10 interfaces  -->  Codeunit implementations
+                  (Sales | Service)              (one per UBL domain)
+```
+
+The enum implements all 10 interfaces simultaneously. Each enum value
+selects different implementations for **validation** and **document
+iteration**, while sharing the same data-extraction implementations
+(the `PEPPOL30` codeunit).
+
+### Key design decisions
+
+- **Sales Header as universal buffer.** All document types (Sales Invoice,
+  Sales Cr.Memo, Service Invoice, Service Cr.Memo) are converted to
+  `Sales Header`/`Sales Line` temporary records before processing. This
+  lets the XmlPorts and data-extraction code work against a single record
+  type regardless of source. The conversion happens in `PEPPOL30 Common`.
+
+- **Facade + Impl split.** `PEPPOL30` (public facade) delegates every call
+  to `PEPPOL30 Impl.` (Access = Internal). Extend via enum + interface,
+  not by modifying these codeunits.
+
+- **No custom tables beyond setup.** The only table is `PEPPOL 3.0 Setup`
+  (singleton). All data comes from standard BC tables: Company Information,
+  Customer, Sales Header/Line, VAT Posting Setup, etc.
+
+## Object inventory
+
+| Type | Count | ID range |
+|------|-------|----------|
+| Table | 1 | 37202 |
+| Page | 1 | 37202 |
+| Enum | 1 | 37200 |
+| Interface | 10 | -- |
+| Codeunit | 15 | 37200-37220 |
+| XmlPort | 2 | 37200-37201 |
+| **Total** | **30** | **37200-37300** |
+
+## Folder map
+
+| Folder | Purpose | Score |
+|--------|---------|-------|
+| `src/Common/` | Core enum, facade, impl, converter, subscribers | **5/5** -- start here |
+| `src/Interfaces/` | All 10 interface definitions | **4/5** -- the contract layer |
+| `src/Sales/` | Sales export codeunits, validation, XmlPorts | **4/5** -- primary export path |
+| `src/Services/` | Service doc export (thin layer over Sales) | **3/5** -- delegates to Sales validation |
+| `src/Setup/` | Singleton setup table + page | **2/5** -- simple config |
+| `src/Install/` | Install + upgrade codeunits | **2/5** -- boilerplate |
+
+## Extending this app
+
+The enum is `Extensible = true`. To add a new PEPPOL format variant:
+
+1. Add a new enum value to `PEPPOL 3.0 Format`
+2. Provide implementations for `PEPPOL30 Validation` and
+   `PEPPOL Posted Document Iterator` (the two format-specific interfaces)
+3. The remaining 8 interfaces use `DefaultImplementation = "PEPPOL30"`
+   -- override only what differs
+
+Country localizations typically override validation rules and possibly
+party info providers (to handle local VAT registration formats).
+
+## Gotchas
+
+- **Denmark special case.** `UseVATSchemeID()` returns true only for
+  `DK` (ISO code). This affects VAT registration number formatting in
+  BIS billing mode. Other countries get a simpler format.
+
+- **Invoice rounding lines are excluded** from the XML line items and
+  instead appear as `PayableRoundingAmount` in the monetary totals. The
+  detection logic uses `Customer Posting Group."Invoice Rounding Account"`.
+
+- **Credit memos require Applies-to Doc.** Validation enforces that
+  credit memos reference the original invoice via `Applies-to Doc. No.`
+  when `Applies-to Doc. Type` is Invoice.
+
+- **Outside-scope VAT (category O)** is limited to a single VAT breakdown
+  per document. Multiple O-category posting setups will fail validation.
+
+- **Service documents reuse Sales validation.** The service validation
+  impl converts to Sales Header/Line and delegates entirely to the sales
+  validation codeunit. There is no separate service-specific validation.
+
+## See also
+
+- [docs/data-model.md](docs/data-model.md) -- Setup table, enum, and data sources
+- [docs/business-logic.md](docs/business-logic.md) -- Export pipeline and validation
+- [docs/extensibility.md](docs/extensibility.md) -- Interfaces and extension points
+- [docs/patterns.md](docs/patterns.md) -- Architectural patterns used

src/Apps/W1/PEPPOL/App/docs/business-logic.md

@@ -0,0 +1,139 @@
+# Business Logic
+
+## Export pipeline
+
+Every export follows the same sequence regardless of document type:
+
+```mermaid
+flowchart TD
+    A[Record Export Buffer triggers codeunit] --> B[Load Setup + resolve format enum]
+    B --> C{Validate posted document}
+    C -->|Fail| ERR[Error raised -- export aborted]
+    C -->|Pass| D[Initialize XmlPort with RecordRef + Format]
+    D --> E[XmlPort iterates headers via PEPPOL Posted Document Iterator]
+    E --> F[Convert posted record to Sales Header buffer]
+    F --> G[Extract all UBL data sections via 8 provider interfaces]
+    G --> H[XmlPort iterates lines via same iterator]
+    H --> I[Convert each posted line to Sales Line buffer]
+    I --> J[Extract line-level UBL data]
+    J --> K[Serialize to UBL XML on OutStream]
+    K --> L[Write XML to Record Export Buffer."File Content"]
+```
+
+### Entry points
+
+There are 4 export codeunits, each bound to `Record Export Buffer`:
+
+| Codeunit | Source table | Format field |
+|----------|-------------|--------------|
+| Exp. Sales Inv. PEPPOL30 (37206) | Sales Invoice Header | Sales Format |
+| Exp. Sales CrM. PEPPOL30 (37205) | Sales Cr.Memo Header | Sales Format |
+| Exp. Serv.Inv. PEPPOL30 (37212) | Service Invoice Header | Service Format |
+| Exp. Serv.CrM. PEPPOL30 (37211) | Service Cr.Memo Header | Service Format |
+
+All four follow the identical pattern: get record from buffer, validate,
+generate XML. The service codeunits reuse the same `Sales Invoice - PEPPOL30`
+XmlPort (not a typo -- service documents are converted to Sales Header
+buffers before the XmlPort sees them).
+
+### The "Sales Header as universal buffer" trick
+
+`PEPPOL30 Common.ConvertPostedHeaderToSalesHeader()` is the conversion
+hub. It uses `TransferFields` for sales documents and
+`PEPPOL30.TransferHeaderToSalesHeader()` (RecordRef field-by-field copy)
+for service documents. The document type field is explicitly set after
+transfer:
+
+- Invoice headers -> `Document Type::Invoice`
+- Credit memo headers -> `Document Type::"Credit Memo"`
+
+For service lines, `MapServiceLineTypeToSalesLineType()` maps service
+line types to their sales equivalents. Service types that have no
+direct sales match (Cost, G/L Account) map to `Sales Line Type::"G/L Account"`.
+
+## Validation
+
+Validation runs **before** XML generation and will abort the export with
+an error if any check fails.
+
+```mermaid
+flowchart TD
+    V1[ValidatePostedDocument] --> V2{Document type?}
+    V2 -->|Sales Invoice| V3[TransferFields to Sales Header]
+    V2 -->|Sales Cr.Memo| V3
+    V2 -->|Service Invoice| V4[RecRefTransferFields to Sales Header]
+    V2 -->|Service Cr.Memo| V4
+    V4 --> V3
+    V3 --> V5[CheckSalesDocument - header-level]
+    V5 --> V6[CheckSalesDocumentLine - per line]
+
+    V5 --> H1[Currency code = 3 chars]
+    V5 --> H2[Company Info: name, address, country, GLN or VAT]
+    V5 --> H3[Bill-to: name, address, city, post code, country]
+    V5 --> H4[Customer: GLN or VAT Reg No.]
+    V5 --> H5[Ship-to address complete]
+    V5 --> H6[Due date, Your Reference filled]
+    V5 --> H7[Bank: IBAN or account + branch + SWIFT]
+    V5 --> H8[Credit memo: Applies-to Doc. No. if type is Invoice]
+
+    V6 --> L1[UoM has international standard code]
+    V6 --> L2[Non-blank lines have description]
+    V6 --> L3[VAT Prod. Posting Group filled]
+    V6 --> L4[Tax Category checks]
+    V6 --> L5[Negative unit price confirmation]
+
+    L4 --> TC1{Tax Category}
+    TC1 -->|S| TC2[VAT % must be > 0]
+    TC1 -->|Z,E,AE,K,G| TC3[VAT % must be 0]
+    TC1 -->|O| TC4[VAT % = 0 + single breakdown only]
+```
+
+### Validation gotchas
+
+- **Service validation delegates to Sales.** `PEPPOL30 Serv. Validation Impl`
+  converts service records to sales records and calls the sales validation
+  impl. Shipment Date is set to Posting Date (services don't have a
+  shipment date).
+
+- **Country codes must have 2-char ISO codes.** The check reads
+  `Country/Region."ISO Code"` and errors if not exactly 2 characters.
+
+- **GLN-or-VAT is enforced** for both Company Information (supplier) and
+  Customer (buyer). Missing both is a hard error.
+
+## Tax category mapping
+
+The PEPPOL tax categories come from `VAT Posting Setup."Tax Category"`:
+
+| Code | Meaning | VAT % rule |
+|------|---------|------------|
+| S | Standard rate | Must be > 0% |
+| Z | Zero rated | Must be 0% |
+| E | Exempt from tax | Must be 0% |
+| AE | VAT reverse charge | Must be 0% |
+| K | EEA intra-community | Must be 0% |
+| G | Free export, not charged | Must be 0% |
+| O | Outside scope of VAT | Must be 0%, max 1 breakdown |
+
+## Monetary totals calculation
+
+`GetLegalMonetaryInfo` in `PEPPOL30 Impl.` computes:
+
+- **LineExtensionAmount** = VAT Base + Invoice Discount Amount (pre-discount line total)
+- **TaxExclusiveAmount** = VAT Base - Payment Discount Amount
+- **TaxInclusiveAmount** = Amount Including VAT - Payment Discount Amount
+- **AllowanceTotalAmount** = Invoice Discount Amount + Payment Discount Amount
+- **PayableRoundingAmount** = difference from rounding line (or fractional cents)
+- **PayableAmount** = Amount Including VAT + rounding - Payment Discount (rounded to 0.01)
+
+## Installation and upgrade
+
+`PEPPOL30 Initialize` (Install subtype) registers 6 electronic document
+format entries in the `Electronic Document Format` table:
+
+- Sales Invoice export, Sales Credit Memo export, Sales Validation
+- Service Invoice export, Service Credit Memo export, Service Validation
+
+The upgrade codeunit re-runs the same registration with an upgrade tag
+(`MS-121225-PEPPOL1P-APP-INSTALL`). A `Company-Initialize` event
+subscriber also ensures formats exist in new companies.

src/Apps/W1/PEPPOL/App/docs/data-model.md

@@ -0,0 +1,95 @@
+# Data Model
+
+## Own tables
+
+The app owns exactly **one** table:
+
+### PEPPOL 3.0 Setup (37202)
+
+Singleton (Code[10] primary key, never set). Stores which PEPPOL format
+enum value to use for Sales and Service document export.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| Primary Key | Code[10] | Always blank -- singleton pattern |
+| PEPPOL 3.0 Sales Format | Enum "PEPPOL 3.0 Format" | Format for sales invoice/credit memo export |
+| PEPPOL 3.0 Service Format | Enum "PEPPOL 3.0 Format" | Format for service invoice/credit memo export |
+
+The `OnInsert` trigger defaults both fields to their respective enum
+values (`PEPPOL 3.0 - Sales` and `PEPPOL 3.0 - Service`). The `GetSetup`
+method auto-creates the record on first access with feature telemetry
+logging.
+
+## Enum
+
+### PEPPOL 3.0 Format (37200)
+
+The central dispatch enum. Implements all 10 interfaces simultaneously.
+`Extensible = true` -- localizations add new values.
+
+| Value | Caption | Overrides |
+|-------|---------|-----------|
+| 0 | PEPPOL 3.0 - Sales | Validation -> Sales Validation, Iterator -> Sales Iterator |
+| 1 | PEPPOL 3.0 - Service | Validation -> Service Validation, Iterator -> Services Iterator |
+
+All 8 data-extraction interfaces use `DefaultImplementation = "PEPPOL30"`,
+so both enum values share the same data-extraction logic. Only validation
+and document iteration differ.
+
+## External data sources
+
+The app reads from (but never writes to) these BC standard tables:
+
+```mermaid
+erDiagram
+    PEPPOL_SETUP ||--|| PEPPOL_FORMAT : selects
+    PEPPOL_FORMAT ||--|{ EXPORT_CODEUNIT : dispatches
+
+    COMPANY_INFORMATION ||--o| EXPORT_CODEUNIT : "supplier party"
+    CUSTOMER ||--o| EXPORT_CODEUNIT : "customer party"
+    SALES_INVOICE_HEADER ||--o| EXPORT_CODEUNIT : "source doc"
+    SALES_CR_MEMO_HEADER ||--o| EXPORT_CODEUNIT : "source doc"
+    SERVICE_INVOICE_HEADER ||--o| EXPORT_CODEUNIT : "source doc"
+    SERVICE_CR_MEMO_HEADER ||--o| EXPORT_CODEUNIT : "source doc"
+
+    SALES_INVOICE_HEADER ||--|{ SALES_INVOICE_LINE : lines
+    SALES_CR_MEMO_HEADER ||--|{ SALES_CR_MEMO_LINE : lines
+    SERVICE_INVOICE_HEADER ||--|{ SERVICE_INVOICE_LINE : lines
+    SERVICE_CR_MEMO_HEADER ||--|{ SERVICE_CR_MEMO_LINE : lines
+
+    VAT_POSTING_SETUP ||--o| EXPORT_CODEUNIT : "tax categories"
+    VAT_AMOUNT_LINE ||--o| EXPORT_CODEUNIT : "tax totals"
+    COUNTRY_REGION ||--o| EXPORT_CODEUNIT : "ISO codes"
+    UNIT_OF_MEASURE ||--o| EXPORT_CODEUNIT : "UNECERec20 codes"
+    DOCUMENT_ATTACHMENT ||--o| EXPORT_CODEUNIT : "embedded attachments"
+    ITEM ||--o| EXPORT_CODEUNIT : "GTIN, item info"
+    ITEM_VARIANT ||--o| EXPORT_CODEUNIT : "additional properties"
+    PAYMENT_TERMS ||--o| EXPORT_CODEUNIT : "payment note"
+    RESPONSIBILITY_CENTER ||--o| EXPORT_CODEUNIT : "supplier address override"
+    SALESPERSON ||--o| EXPORT_CODEUNIT : "contact info"
+    SHIP_TO_ADDRESS ||--o| EXPORT_CODEUNIT : "delivery GLN"
+```
+
+### Key data flows
+
+**Supplier party** -- sourced from `Company Information`. If a
+`Responsibility Center` is set on the document, address fields are
+overridden from that center. GLN takes priority over VAT Registration No.
+for endpoint identification when `Use GLN in Electronic Document` is set.
+
+**Customer party** -- sourced from `Customer` (via `Bill-to Customer No.`)
+and `Sales Header` bill-to fields. Same GLN-vs-VAT priority logic.
+
+**Tax information** -- derived from `VAT Posting Setup."Tax Category"`.
+The tax category code (S, Z, E, AE, K, G, O) drives both validation
+rules and XML output. `VAT Amount Line` is built up line-by-line during
+export, not read from a persisted table.
+
+**Attachments** -- `Document Attachment` records linked to the posted
+document are base64-encoded and embedded in the XML as
+`AdditionalDocumentReference` elements. MIME type is inferred from
+file extension; unsupported types are silently skipped.
+
+**Currency** -- when `Sales Header."Currency Code"` is blank, the
+`General Ledger Setup."LCY Code"` is used. Must be a 3-character ISO
+4217 code.