alla-allaos-fullstack/docs/adr/0012-approval-signature-strategy.md

ADR 0012: Approval Signature Strategy

Status

Accepted

Context

Quotation PDF templates already contain the signature placeholders app1, app2, app3 and their position fields, but earlier tasks only seeded safe fallback values. The production document flow now needs a deterministic rule for:

• who is shown as Prepared By
• who is shown as Approved By
• who is shown as Authorized By
• how each person’s position is resolved
• how approved documents stay immutable after approval

Decision

Prepared By

• resolve from crm_quotations.salesman_id
• fallback to crm_quotations.created_by
• always render the user display name, never a raw id
• use quotation created_at as the available timestamp for the prepared block

Approved By

• resolve from live approval history in crm_approval_actions
• consider only approve actions
• choose the latest approved action whose workflow role is one of:
  • sales_manager
  • department_manager
• exclude the workflow’s final approval role from this slot

Authorized By

• resolve from the latest approved action for the workflow’s final step
• in the standard workflow this is expected to be top_manager

Position Resolution

• primary source is memberships.business_role
• display label should come from active ms_options in category crm_job_title when available
• if the master option is missing, fallback labels are:
  • sales -> Sales Engineer
  • sales_support -> Sales Support
  • sales_manager -> Sales Manager
  • department_manager -> Department Manager
  • top_manager -> General Manager

Snapshot Immutability

• preview PDF resolves signatures from live quotation and approval data
• approved snapshot stores the resolved signature block and resolved template input
• approved PDF generation prefers snapshot signature input when a snapshot already exists
• locked approved artifacts remain the immutable historical source

Consequences

• signature placeholder mapping is now explicit and organization-aware
• template output no longer depends on hardcoded placeholder text in the PDFME template
• position labels can be governed centrally through master options without changing generator code
• approved documents preserve approval identity even if user names, memberships, or master options change later