G3N Retail Stack Story

Appearance

Accounting / ERP Readiness ​

Status: Implemented (export events + batch/schedule metadata + lineage/reconcile + storage usage ledger + storage usage sweep + storage usage reconcile endpoint + daily usage rollups; cross-service event ingestion + export execution pipeline implemented).

Purpose ​

Accounting/ERP Readiness defines exportable financial event views and traceability requirements so downstream accounting systems can reconcile activity by org, facility, and channel.

Goals ​

  • Ensure every financial-impacting event is traceable to its originating business record.
  • Provide consistent, auditable export views for ERP integration.
  • Preserve ownership vs possession and cost-centre attribution in every event.

Non-goals ​

  • This module does not replace external ERP systems.
  • This module does not define operational transaction workflows (owned by SCM/PCM/ICS).

Scope and gating ​

  • All accounting readiness views are org-scoped.
  • Facility and channel context must be preserved in every exportable event.

Request context checklist ​

  • Org: required for all exportable events.
  • Facility and channel: required for every exportable event.
  • Actor + role: required for adjustments, overrides, and approvals.
  • Cost-centre: optional attribution for billing and audit.

Core business entities and relationships ​

  • Exportable events for sales, refunds, inventory movements, procurement liabilities, consignment settlements, loyalty liabilities, and influencer commissions.
  • Tax liabilities and adjustments for sales and refunds.
  • Export schedules (recurring cadence + time window) and export runs (batches).
  • Export batches carry audit evidence metadata (manifest references, counts, checksums).
  • Storage usage records capture logical bytes by org/cost-centre across record and object storage resources.
  • Daily usage rollups summarize API/event delivery activity by org/service/surface, with optional cost-centre attribution.
  • Lineage mappings linking events back to source transactions.

Lifecycle and status model (described in words) ​

  • Exportable events are generated as transactions occur.
  • Corrections and reversals are recorded as new events with references.
  • Export schedules move between active and suspended states.
  • Export batches move through ready → sent (or failed), with repair batches created for retries.
  • Storage usage sweep records windowed usage measurements without blocking operational flows.
  • Usage rollup job aggregates daily API/event delivery usage by org/service/surface for billing ledgers.

End-to-end workflows ​

Happy paths ​

  • Generate exportable events from sales, procurement, and inventory operations.
  • Create export schedules that define cadence and time windows.
  • A scheduled sweep job evaluates active schedules, creates an export run + initial batch for due windows, and advances last_run_at/next_run_at with idempotency protections.
  • Produce export batches with evidence metadata and mark them sent once delivered to ERP.
  • Create tax audit export runs that filter by jurisdiction or policy version and include tax components per event for audit.

Exceptions and edge cases ​

  • Corrections for pricing or cost adjustments are recorded with references.
  • Reversals (returns, chargebacks) are linked to original events.
  • Failed export batches create repair batches with new evidence metadata.
  • Storage usage reconciliation can reprocess windowed usage when sweep coverage is incomplete.

Configuration and defaults ​

  • The platform is enterprise-grade by default; applications may hide complexity via defaults.
  • Export policies include required fields, grouping rules, and settlement cadence.
  • Export schedules define cadence (interval or cron) and export windows.

Omnichannel requirements ​

  • Exports must preserve channel context for every transaction.
  • Cross-channel returns and settlements remain traceable.

Performance requirements ​

  • Export generation must not block operational flows.
  • Export queries must be efficient for high-volume retailers.

Tax reporting and compliance ​

  • Tax events are reportable by jurisdiction, tax type, and effective rate.
  • Tax-on-tax ordering and inclusivity are preserved for audit.
  • Exemptions are recorded with customer certificate references and expiry.
  • Luxury and excise taxes are reported separately where required.

Operational resilience checklist ​

  • Operations are idempotent and retry-safe; duplicate submissions do not double-apply.
  • Event emission is non-blocking; operational actions do not wait on analytics pipelines.
  • Out-of-order events are tolerated; reconciliation uses timestamps and source references.
  • Exceptions generate actionable inbox items and can be retried or reversed with audit trails.
  • Long-running workflows are resumable with explicit state checkpoints.
  • Repair workflows create a new export batch and reference the failed batch for audit.

Training and change management ​

  • Policy and workflow changes include training notes and operational checklists.
  • Critical changes use staged rollout with rollback guidance to reduce operational risk.
  • Support runbooks cover common reconciliation failures, export disputes, and adjustments.

BI and KPI expectations ​

  • COGS and inventory valuation by facility, channel, and category.
  • Revenue and margin by channel and time bucket.
  • Tax collected vs refunded by jurisdiction.
  • Liability balances for gift cards, store credit, loyalty, and influencer payouts.
  • Traceability coverage: percent of financial events linked to source records.

KPI readiness checklist ​

  • Financial events include source references and timestamps.
  • Cost, tax, and liability components are captured per event.
  • Export runs capture success, failure, and exception reasons.
  • Adjustments and reversals reference originating events.

Rebalancing and recalibration ​

  • Rebalance export cadences and settlement windows to keep reconciliation within policy.
  • Adjust exception thresholds to reduce operational noise without hiding risk.
  • Calibrate liability reserve policies as gift card, loyalty, and influencer balances shift.

Downstream accounting and integration capture ​

Each exportable event must include, at minimum:

  • Org, facility, channel, and location (including virtual/external) with optional cost-centre attribution.
  • Ownership vs possession context.
  • Customer, vendor, or influencer references as applicable.
  • SKU, qty, unit cost/price, taxes, timestamps.
  • Source transaction references and reason codes.
  • Events include optional cost-centre attribution for billing and audit.
  • Export batches include evidence metadata (manifest refs, counts, checksums) for audit.
  • Storage usage records include resource references, logical bytes, and attribution for billing.
  • Usage rollups provide daily totals for API calls, event deliveries, and bandwidth by service/surface.

Comments and inbox ​

  • Export runs and exceptions support comments, threads, and attachments with revision history.
  • Exceptions generate team inbox notifications.
  • Endpoints: POST /accounting/comment|comment/get|comment/list|comment/revise|comment/status|comment/report and POST /accounting/inbox/create|get|list|status|state.

Governance and roles ​

  • Org roles for export administration and finance audit visibility (acct_* roles, finance_audit).
  • Primary owner controls export and settlement policies.
  • Role grants can be permanent, time-bounded, or scheduled.

Relationships and data flow ​

  • SCM, PCM, ICS, CRM/Loyalty, and Influencer modules produce source events.
  • Accounting readiness assembles exportable views without mutating source records.

Example scenarios and acceptance criteria ​

Scenario 1: Sales export with refunds ​

  • A sale and subsequent return occur in different channels.
  • Export includes both events with references and reversal linkage.
  • Acceptance: ERP can reconcile sale and refund with full traceability.

Scenario 2: Inventory valuation adjustment ​

  • A cost adjustment is recorded in inventory.
  • Export captures adjustment with reason and source reference.
  • Acceptance: valuation changes are auditable and traceable.

Scenario 3: Loyalty liability settlement export ​

  • Loyalty earn and redeem activity occurs across locations.
  • Export includes liability balances and home-store settlement positions.
  • Acceptance: finance can reconcile liability movements with policy references.

Scenario 4: Influencer payout with clawback ​

  • An influencer earns commission that is later partially clawed back on returns.
  • Export includes earned, payable, paid, and clawback entries.
  • Acceptance: payout and clawback are traceable to the originating orders.

Scenario 5: Export batch repair ​

  • A scheduled export batch fails to deliver to ERP.
  • A repair batch is created referencing the failed batch and new evidence is captured.
  • Acceptance: ERP can reconcile the original batch and repair batch with full audit linkage.