task-h.4

docs/adr/0012-approval-signature-strategy.md

@@ -0,0 +1,63 @@
+# 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