open-accounting-accounting-integrity

name	open-accounting-accounting-integrity
description	Use when implementing or reviewing accounting-sensitive open-accounting workflows such as payment reversals, invoice paid-state changes, journal void/reopen flows, period locks, evidence blockers, or any change that could rewrite accounting history.

Open Accounting Accounting Integrity

Use this with open-accounting-development when a change touches posted accounting history, payment/invoice balances, fiscal locks, journal lifecycle, or audit evidence.

Core Rules

• Prefer auditable offsetting actions over destructive mutation. Corrections should create reversal, void, adjustment, or reopening records that preserve the original event and operator reason.
• Do not delete or silently rewrite posted ledger, payment, invoice, close, payroll, tax, or reconciliation history unless an existing domain rule explicitly permits it.
• Enforce tenant period locks on the effective accounting date for the new correction event.
• Require a non-empty reason or note for reversal, void, reopen, and other audit-sensitive correction workflows.
• Keep API, CLI, service, repository, and frontend paths on the same reusable workflow. Do not duplicate accounting correction logic per entry point.
• Use repositories and ORM-backed persistence for state changes. Raw SQL belongs in migrations or isolated repository implementation details only.

Implementation Checklist

• Add service-level validation before repository writes: entity exists, tenant matches, state permits correction, reason is present, and the correction date is allowed.
• Make the repository method atomic when it creates a correction record and marks the original record.
• Preserve links in both directions when useful, for example original reversed_by_* fields plus correction reversal_of_* fields.
• Update derived business state through existing domain services, for example invoice paid amount/status through invoicing service methods.
• Return conflict errors for already-corrected or disallowed correction attempts, not silent success.
• Update API docs, CLI docs, route coverage mappings, focused tests, and generated Swagger when adding a route.

Focused Validation

Run the focused package tests for each touched accounting surface before broader gates:

go test -count=1 ./internal/payments ./internal/invoicing ./cmd/api ./cmd/oa
go test -timeout=5m -tags=integration ./internal/payments -run TestGORMRepository_CreateReversal -count=1
make test-cli-coverage
go test -timeout=3m ./docs -count=1

For frontend exposure of a correction workflow, also load open-accounting-frontend-workflow and prove the user workflow with the focused component or demo E2E test.