Skip to content

Last amended: 2026-07-30 Audience: product, accounting, developer

ADR 0022: Reviewable Accounting File Intake

Context

BooksPlus needs a manual file-intake path before provider-specific external adapters. A representative development CSV is the standard Dolibarr accounting export structure and contains mixed opening-balance, income, expense/payable, inventory, receipt/payment, duplicate, conflict, and reversal-like records. Production exports are expected to use the same structure with more rigorous source data.

ADR 0007 requires provider-agnostic import boundaries, durable source identity, idempotency, source-world dates, BooksPlus acceptance time, and explicit change type. ADR 0020 requires manual and reviewable file intake before system-specific adapters and places external adapters last in the development sequence.

The Summary Accounting batch is workflow staging, but one mixed file may contain facts for several workflow owners. BooksPlus needs a durable intake boundary that does not force the entire file into one summary type or discard unselected records.

Decision

BooksPlus should introduce a company-scoped AccountingImportRun as the durable record of one reviewable file-intake attempt.

An import run should preserve:

  • id, company id, and importing actor id;
  • source system supplied by the user or calling boundary;
  • import profile key and version;
  • source file name, content hash, and raw-payload reference;
  • BooksPlus acceptance time;
  • default currency only when the profile verifies the file is single-currency;
  • import-run correlation id;
  • parse and review status;
  • counts by workflow classification and issue severity;
  • normalized transaction candidates and their source row references;
  • resulting summary-batch or owning-workflow references when created;
  • created and updated timestamps.

The import run is intake and review history. It is not source-document identity, summary-batch identity, a journal entry, or formal report truth.

Import Profile Boundary

Step 7 should implement a versioned, reviewable accounting-journal CSV profile for the known column structure. The import session should explicitly identify the source system, such as dolibarr, without embedding Dolibarr business rules in the provider-agnostic contract.

A packaged Dolibarr adapter or custom extract integration remains external adapter work under ADR 0020. It should later emit the same normalized contract.

Profile versions must define:

  • required and optional headers;
  • field parsing and date/decimal culture;
  • transaction grouping rule;
  • source row identity;
  • required import-session constants;
  • redundant-field consistency checks;
  • how missing or ambiguous values become validation issues.

Changing a mapping that can change normalized meaning requires a new profile version.

Source and Idempotency Identity

Normalized candidates should identify source events with:

  • source system;
  • source object type;
  • external object id;
  • external event or version id when the source supplies one;
  • explicit change type: original, correction, or reversal;
  • related original external identity for correction or reversal.

The recommended idempotency key is a stable source-issued event/version identity, scoped by company and source system. File name, physical row number, posting amount, description, and content hash alone are not durable event identity.

The file content hash detects exact file replay and supports evidence. It does not replace transaction-level idempotency because different files may contain the same events and one corrected file may reuse a name.

When the standard file structure does not provide stable event/version or change identity, the profile must:

  • obtain it through a documented deterministic mapping to production source identifiers;
  • require it as reviewed import metadata; or
  • hold the candidate and recommend a custom source extract.

BooksPlus must not manufacture durable identity from descriptive text.

Mixed-Workflow Routing

Parsing should normalize every transaction group before workflow filtering. Each candidate should have one routing outcome:

  • sales_and_receivables_summary;
  • purchasing_and_payables_summary;
  • inventory_summary;
  • banking_and_finance_summary;
  • opening_balances;
  • correction_or_reversal;
  • unclassified.

Routing must be based on explicit source type or a reviewed profile mapping. Account ranges, journal codes, descriptions, and subaccount formats may support validation or a proposed classification, but they must not silently establish canonical workflow meaning.

One import run may create multiple child workflow records. During Step 7, only Sales and Receivables Summary child batches may be created. Other candidates remain visible in the import run and are routed to implemented owning workflows or held until their step is available. Opening balances use the existing setup path. Corrections and reversals remain held until their related-original identity resolves. They may then enter the distinct Accounting Correction workflow, where target-journal, evidence, line, reconciliation, period, authorization, and protected-posting rules still apply.

Replay and Conflict Rules

  • Reimporting the same file should be visible as an import-run replay and must not duplicate accepted child batches.
  • The same source event and idempotency key with the same normalized meaning should link to the existing accepted workflow record.
  • The same source event or idempotency key with different normalized meaning must be rejected or held for review.
  • A different source event with coincidentally identical accounting amounts is not automatically a replay.
  • Duplicate-meaning candidates with different source identities should be flagged for review without being silently merged.
  • Accepted import history and raw evidence must not be overwritten by a later file.

Source Dates and Currency

Posting date, source-document date, source activity date/range, and BooksPlus acceptance time are distinct meanings and must not silently substitute for one another.

The import boundary may accept a file-level currency only when the profile and user review establish that every candidate line uses that currency. Otherwise, currency is required per candidate or line.

Security, Audit, and UX

Staging an import run requires the stable protected action accounting_import_run.stage. It requires ordinary authorization and audit but not step-up confirmation because staging creates review records and no ledger effects. Creating workflow batches continues to use their own protected actions. Posting continues to require the existing summary and central Accounting protected actions.

A versioned, reviewed mapping may use journal codes as source-type evidence. Journal codes must not silently establish canonical workflow or accounting meaning by themselves.

Each normalized event has one owning workflow and at most one ordinary posting result. Cross-workflow references do not authorize duplicate posting.

A correction candidate is owned by the Accounting Correction workflow rather than a Summary workflow. Initial machine and file corrections target accepted original events; corrections of prior corrections remain held for later contract extension.

Import-run mutations should emit append-only audit events with company, actor, action, target, result, source file reference, and correlation context.

The review experience should show file identity, profile version, counts, routing outcomes, duplicates, conflicts, blocked change types, validation issues, and resulting batch references before consequential actions occur.

Consequences

  • One mixed file can be reviewed without losing non-selected records.
  • File evidence and transaction idempotency remain distinct.
  • The same manual intake path can later support a Dolibarr adapter, a custom extract, and other providers.
  • Production data rigor improves automation but does not weaken validation or identity requirements.
  • A small import-run persistence model is required in addition to Summary Accounting batches.

Alternatives Considered

Treat each file as one Summary Accounting batch

Rejected because a mixed file may contain several workflow owners and change types.

Use the file hash as the idempotency key

Rejected because it detects identical files, not repeated source events across different exports.

Build a Dolibarr-specific adapter in Step 7

Rejected because ADR 0020 places provider-specific external adapters after the manual file path and workflow contracts are proven.

Drop records excluded by the selected workflow filter

Rejected because it would conceal source completeness and make later workflow reconciliation unreliable.

Acceptance Record

Accepted with these confirmations:

  • AccountingImportRun is persisted.
  • Exact file replay returns the prior import run with a replay result. A linked new attempt is created only when audit policy requires it.
  • accounting_import_run.stage is the protected action. It uses ordinary authorization and audit without step-up confirmation.
  • Reviewed, versioned mappings may use journal codes as source-type evidence, but journal codes alone do not become canonical workflow meaning.
  • Candidates for workflows not yet implemented remain in import-run review history without creating premature child domain records.

Amended on 2026-07-30 to hand resolved correction and reversal candidates to the Accounting Correction workflow without treating identity resolution, import routing, or provider fields as posting authority.

  • ../../accounting/summary-accounting.md
  • ../../contracts/summary-accounting-batch.contract.md
  • ../../contracts/security/audit-event-contract.md
  • 0007-provider-agnostic-import-boundaries.md
  • 0014-append-only-security-audit-events.md
  • 0020-initial-release-scope-and-financial-workflow-taxonomy.md
  • 0024-operational-summary-workflow-boundaries-and-purchasing-facts.md
  • ../../contracts/accounting-correction.contract.md