64 lines
2.3 KiB
Markdown
64 lines
2.3 KiB
Markdown
# 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
|