Design — driver layer and azh §302

01 · The four layers

The rule, unchanged: a driver knows nothing — not the domain, not the provider, not where the password came from. It moves bytes and reports what happened.

02 · The driver contract

maptara_san_provider_base/models/provider_driver.py — an AbstractModel, the declared version of today's getattr(self, f'_{op}_{provider_type}') convention. Roughly 200 lines.

class ProviderDriver(models.AbstractModel):
    _name = 'maptara.provider.driver'
    _description = 'Contract every provider plugin implements'

    # ---- capability declaration ----------------------------------
    def _capabilities(self):
        """Return a dict the UI and the cron can interrogate.
        Replaces 'call it and see if getattr returned None'."""
        return {
            'send_estimate': False, 'resend_estimate': False,
            'poll_state':    False, 'fetch_decision':  False,
            'fetch_documents': False, 'send_message':  False,
            'submit_batch':  False,
            'appendix_mimetypes': (),      # was a constant in the BASE
            'inbound': (),                 # reserved — see below
        }

    # ---- probe ---------------------------------------------------
    def probe(self, config):
        """-> {'ok': bool, 'stage': 'config'|'endpoint'|'credentials',
               'url': str, 'message': str}
        Never raises. Creates no Vorgang. Safe against production."""
        raise NotImplementedError

    # ---- outbound, per record ------------------------------------
    def send_estimate(self, activity, documents=(), mdm_attachments=()):
        """Attachments are ARGUMENTS. Today they are smuggled through
        two undocumented context keys and silently default to empty."""
        raise NotImplementedError

    def resend_estimate(self, activity, documents=(), mdm_attachments=()):
        raise NotImplementedError

    def poll_state(self, activity):
        """-> bool: True iff the insurance decision moved.
        The only return value any caller consumes."""
        raise NotImplementedError

    def fetch_decision(self, activity):     raise NotImplementedError
    def fetch_documents(self, activity):    raise NotImplementedError
    def send_message(self, activity, subject, body):  raise NotImplementedError

    # ---- outbound, per batch  (new — azh §302) -------------------
    def submit_batch(self, batch):
        """-> maptara.provider.activity. One submission, many invoices."""
        raise NotImplementedError

    # ---- inbound: declared, not implemented ----------------------
    # fetch_orders()    Direktauftrag        ticket #1274
    # fetch_requests()  Versorgungsanfrage   ticket #1276
    # fetch_messages()  inbound messages     ticket #1275
    # Blocked on a product decision, NOT on this design. The hole is
    # declared so adding them later is not a second pass at the contract.

03 · ConnectionConfig

Plain Python in the driver module. No ORM. That is what makes drivers testable with no database.

@dataclass(frozen=True)
class ConnectionConfig:
    host: str                 # or full endpoint URL for SOAP/REST
    port: int = 22
    username: str = ''
    secret: str = ''          # password or key material
    key_path: str = ''
    timeout: int = 30
    retries: int = 3
    dry_run_dir: str = ''     # write locally instead of transmitting

    @classmethod
    def resolve(cls, env, param_key, env_var, **kw):
        """Endpoint precedence, promoted out of the egeko module:
              explicit argument  >  environment variable  >  ir.config_parameter  >  REFUSE
        There is NO default. A staging DB restored from production
        would otherwise file real claims with real Krankenkassen."""

Credentials are built by the caller from whatever model it owns — maptara.service.provider for ECE, vdms.backend for VDMS. The driver never runs a search(). The moment it owns a credential model it has an opinion about who is calling it and stops being reusable.

04 · SftpDriver

maptara_driver_sftp, depends: ['base'], external_dependencies: {'python': ['paramiko']} — declared honestly, which would be a first in this repo for a transport.

05 · azh §302 — data model

The spec's Block A is a Sendung: an envelope over N invoices, generated at transmission. maptara.claim.batch already models the invoice set. So one new model, not a new subsystem.

Design question #1 from the spec — positions as sub-lines or a separate table? The spec recommends a separate position table, and it is right, but we do not need one: positions come from account.move.line, which already exists and already carries LEGS. Serialise from the invoice lines; do not copy them into a staging table that can drift.

06 · azh §302 — the 34 fields

Straight from Kerstin's document. Every row has a source; the ✅ section confirms all of it already exists in Maptara. The XSDs — azh_HIMI_Begleitdatei_v2.4.xsd (9 elements) and azh_HIMI_Datendatei_v2.4.xsd (79 elements) — are on disk with worked examples.

07 · azh §302 — files and lifecycle

The rejection path is the one to get right. Design question #4 in the spec asks what happens on an NVD, and answers it: set the status to error, allow manual correction and resubmission. That mirrors the trap Egeko already taught us — _send_cost_estimate_egeko writes insurance_state = 'waiting' even when the send failed, so a rejected order polls forever. Do not import that bug into azh: the submission state is written from the return file, never optimistically from the send.

08 · Egeko, on the contract

The rewrite is one method plus consequences. generate_document_template — 263 lines at egeko/models/maptara_provider.py:180-442 — mixes ORM reads, VAT arithmetic, MDM downloads over a different transport, and opta data's wire vocabulary, with no intermediate representation and no payload test coverage.

Preserve verbatim, all currently guarded by tests: the four status buckets (only STATUS_DECIDED may write insurance_state); de_decimal/de_price per-field precision; net and gross both post-discount; additionalFee is Mehrkosten and not the discount; positions sorted create_date descending; and dhpIdentNumer, which stays misspelled because that is opta data's typo in their own WSDL.

09 · Open decisions

Seven from the spec's own "🔲 Noch offen" list, plus two of ours. None of them block starting; each blocks a specific piece.