# 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