Inventarsystem/Legal/GOBD_CHANGE_REPORT_2026-04-10.md

GoBD Hardening Change Report (2026-04-10)

Scope

This change set implements core hardening measures for GoBD-oriented operation:

1. Soft-delete instead of hard-delete for inventory and borrowing records.
2. Tamper-evident audit log chain for critical accounting/inventory events.
3. Invoice immutability model with correction entries instead of overwrite.

Implemented Changes

1) Tamper-evident audit chain

• New module: Web/audit_log.py
• Audit entries are chained by hash (prev_hash -> entry_hash) with monotonic chain_index.
• Canonical JSON serialization is used to make hashing deterministic.

Current fields per audit event:

• event_type
• actor
• source
• ip
• payload
• timestamp
• created_at
• prev_hash
• entry_hash
• chain_index

Integrated event writes in:

• Item soft-delete flow
• Invoice creation
• Invoice paid marking
• Invoice finalize+repair
• Invoice correction entry creation

1b) Audit operational controls (phase 2)

• Added index management in Web/audit_log.py:
  • Unique index on chain_index
  • Additional indexes on created_at and event_type
• Added chain verification function in Web/audit_log.py.
• Added CLI verification tool: Web/verify_audit_chain.py.
• Added admin verification endpoint:
  • GET /admin/audit/verify
  • Returns chain integrity result (200 if valid, 409 on mismatch).
• Added lazy index provisioning helper invoked in admin borrowing views.

2) Soft-delete conversion

Inventory items

• Deletion endpoint now marks records logically deleted:
  • Deleted: true
  • DeletedAt
  • DeletedBy
  • LastUpdated
  • Verfuegbar: false
• Item-linked borrow records are also logically deleted (Status: deleted) instead of physically removed.
• Image files are no longer physically deleted in this flow.

Borrow records

• remove_ausleihung changed to set Status: deleted + timestamps.
• Retrieval helpers now exclude deleted records by default.

Item reads

• Item helper queries now exclude Deleted: true records.
• Grouped item lookups and appointment queries also exclude deleted records.
• Code uniqueness checks ignore deleted records, allowing controlled code reuse.

3) Invoice immutability and correction flow

• Invoice creation now blocks overwrite if an invoice already exists for the borrow record.
• New lock marker on invoice creation/update path: InvoiceLocked: true.
• New correction endpoint:
  • POST /admin/borrowings/<borrow_id>/invoice/correction
  • Appends entries to InvoiceCorrections
  • Does not mutate existing InvoiceData body
  • Requires correction reason
  • Supports optional amount delta

3b) UI integration for correction flow (phase 2)

• Added correction action forms in:
  • Web/templates/admin_borrowings.html
  • Web/templates/library_borrowings_admin.html
• Added correction count display (invoice_corrections_count) in both admin tables.

Detailed File-Level Review

Web/audit_log.py

• Introduces chain-based audit persistence.
• Uses last chain entry to calculate next chain_index and hash.
• Adds explicit index provisioning and full chain verification routine.
• Tradeoff: application-level sequencing is improved by unique index, but concurrent peak writes may still require retry logic around duplicate key conflicts.

Web/verify_audit_chain.py

• New CLI operational tool for manual/cron verification.
• Returns non-zero exit code on chain mismatch.

Web/app.py

• Added _append_audit_event(...) helper and integrated it at critical event boundaries.
• Inventory API routes now hide soft-deleted items.
• delete_item changed from destructive deletion to soft-delete semantics.
• Invoice route now rejects overwrite and requires correction route for changes.
• Added correction route with immutable invoice core.
• Added admin audit verification route and lazy audit index initialization helper.

Behavioral impact:

• Deleted items no longer disappear from DB; they are hidden from normal views.
• Existing UI actions for delete continue to work, but now preserve evidence.
• Invoice re-creation attempts now return warning and redirect.

Web/items.py

• Introduced _active_record_query(...) and applied it across item retrieval APIs.
• Converted remove_item to soft-delete update.
• Updated maintenance reset (unstuck_item) to status updates instead of delete_many.

Behavioral impact:

• Item-level DB history is preserved.
• Legacy scripts relying on hard delete semantics may need adaptation.

Web/ausleihung.py

• Converted remove_ausleihung to soft-delete by status.
• Default retrieval paths now exclude deleted records.

Behavioral impact:

• Borrowing history remains in DB for traceability.

Validation Performed

• Static diagnostics reported no errors in modified files:

  • Web/app.py
  • Web/items.py
  • Web/ausleihung.py
  • Web/audit_log.py

• Additional phase-2 checks:

  • python3 -m py_compile Web/app.py Web/audit_log.py Web/verify_audit_chain.py
  • No syntax errors
  • Template diagnostics:
    • Web/templates/admin_borrowings.html no errors
    • Web/templates/library_borrowings_admin.html no errors

Residual Risks / Open Points

1. Concurrency hardening for audit chain:

   • Current chain append may produce collisions under parallel writes.
   • Recommendation: transaction or optimistic retry with unique index on chain_index.

2. Broader query coverage:

   • Some direct Mongo queries outside helper paths may still need explicit Deleted != true filters.

3. Formal GoBD process requirements beyond code:

   • Verfahrensdokumentation must be updated.
   • WORM/immutable storage for exported archives should be enforced externally.
   • Operational controls (RBAC review, periodic reconciliation, restore drills) should be documented.

Recommended Next Steps

1. Add retry strategy for audit write conflicts:

   • Retry append_audit_event on duplicate chain_index key errors.

2. Add admin UI page for chain status and recent audit events:

   • Human-readable inspection view on top of /admin/audit/verify.

3. Add policy enforcement tests:

   • Ensure invoice overwrite is blocked.
   • Ensure soft-deleted records are hidden in APIs.
   • Ensure deletion endpoints never call physical delete operators.

4. Infrastructure-level immutability:

   • Push periodic audit snapshots and invoice archives to immutable/WORM storage.