ERP-core/docs/DUAL_APPROVAL_PLAN.md

Dual Approval Plan — Stock Adjustments & Price Adjustments

Status: implemented 2026-10-12 with the §8 recommended defaults (counts go through approval; initial prices on a new item need none; no Admin bypass; thresholds configurable, default "always two"; selling prices only; no future effective dates; no auto-expiry). Deviations: the approval doc type for price adjustments is PADJ (not PRICE); count-variance serial moves are recorded against the adjustment rather than the count; the Approvals inbox is open to every signed-in user (it lists only what they may approve and their own requests). Details in Backend/PROGRESS.md and Frontend/PROGRESS.md. Goal: a stock adjustment or a selling-price change only takes effect after two different people (neither of them the person who requested it) have approved it. Reference to mirror: PurchaseOrderService — PendingApproval → Approved/Rejected, the Approve action permission, and the "you cannot approve your own document" rule. This plan extends that one-step approval to two steps and puts it in one shared place so both documents use the same rules.

---

1. Requirements

#	Requirement
1	A stock adjustment (including wastage) changes stock and posts to GL only after the second approval.
2	A selling-price change (min / max / flat price) is applied to the item only after the second approval.
3	Maker–checker: the requester can't approve. Approver 1 and approver 2 must be different people.
4	Either approver can reject with a reason. A rejected request never takes effect.
5	Everyone involved is notified: approvers when something is waiting for them, the requester when it is approved or rejected.
6	A full audit trail: who requested, who approved at each level, when, and any comments.
7	An Approvals inbox listing everything waiting for the current user.

---

2. Current state

Area	What exists	Gap
Stock adjustments	AdjustmentService.CreateAsync posts immediately: it moves stock, posts GL and writes the ledger in one transaction. AdjustmentStatus already has Draft, PendingApproval and Posted, but only Posted is ever used.	No approval step at all.
Wastage	/stock/wastage records adjustments with wastage reason codes through the same path.	Same: posts immediately.
Stock counts	CountService.PostAsync creates a variance StockAdjustment and posts it immediately.	A count is effectively an adjustment, so it bypasses any approval added to adjustments (see §8, decision 3).
Selling prices	Item.SellingMinPrice / SellingMaxPrice / SellingFlatPrice are edited directly in the item Edit dialog and saved instantly. SalesPricingService reads them.	No price-change document, no history, no approval.
Approval pattern	Purchase orders: one approver, Admin only, not your own PO. RolePermissionAction.Approve exists and NavPolicies.ApproveAction is used on PO endpoints.	Only one level, and it's built into the PO service.
Notifications	INotificationService.RaiseAsync broadcasts to all active users (in-app only).	No way to notify only approvers or only the requester.

---

3. Design overview

Requester ──create──► PendingApproval (level 1)
                          │ approve (user A ≠ requester)
                          ▼
                     PendingSecondApproval (level 2)
                          │ approve (user B ≠ requester, ≠ A)
                          ▼
                     Approved → effect applied in the same transaction
                     (stock posted + GL / prices written + history)

Reject at either level ──► Rejected (terminal; nothing applied)
Requester may Withdraw while still pending ──► Cancelled

• One shared approval engine (ApprovalService) holds the rules: who may approve, the two-person rule, and the audit rows. The two document services call it, and only apply their effect when it says "fully approved".
• Nothing changes stock or prices until the final approval. Pending documents are only requests.
• Re-check at final approval. Stock may have moved since the request. A decrease that would now make stock negative fails at approval time with a clear message, and the document stays pending.

---

4. Shared approval engine

4.1 Entity DocumentApproval (table document_approvals)

One row per decision, so the full trail is kept.

Field	Notes
DocumentApprovalId	PK
DocType	ADJ (stock adjustment) or PRICE (price adjustment)
DocId	the document's id
Level	1 or 2
Decision	Approved / Rejected
DecidedBy, DecidedAt	the user and time
Comment	optional; required when rejecting

4.2 IApprovalService

// Validates the caller may decide at the document's current level, records the row,
// and returns where the document stands now.
Task<ApprovalOutcome> DecideAsync(string docType, int docId, int requestedBy, int currentLevel,
    bool approve, string? comment, CancellationToken ct);
// ApprovalOutcome: NextLevel(2) | FullyApproved | Rejected

Task<IReadOnlyList<ApprovalStepDto>> HistoryAsync(string docType, int docId, CancellationToken ct);

Rules enforced in one place:

1. The caller has the Approve action on the document's nav code (stock.adjustments or products.price-adjustments).
2. The caller is not the requester (ApprovalForbidden, 403).
3. At level 2, the caller is not the level-1 approver (ApprovalSamePerson, 403).
4. The document is at the expected level (ApprovalNotPending, 409). This also stops two people approving the same level at once (row-version check).
5. Optional, per settings (§7): level 2 is limited to particular roles (for example, Manager or Admin).

Admin bypass: none. Even an Admin can't approve their own request or both levels (see §8, decision 5).

---

5. Stock adjustments

5.1 Status flow

AdjustmentStatus becomes: Draft, PendingApproval, PendingSecondApproval, Posted, Rejected, Cancelled. Existing rows stay Posted.

5.2 Changes to StockAdjustment

• Add RequestedBy (the existing CreatedBy), ApprovedLevel1By/At, ApprovedLevel2By/At, RejectedBy/At, RejectReason.
• Add PostedAt. Today the ledger and GL use the creation time; they will use the posting time.
• Inbound serials: today, new serials are created at once from SerialNos. While a request is pending, the typed serial numbers are stored on the line (new StockAdjustmentLineSerialNo rows or a JSON column) and the serial records are created only when it posts.
• Outbound serials are validated when the request is made and re-validated at posting. A serial sold in the meantime fails the approval with a message naming that serial.

5.3 AdjustmentService

Method	Behaviour
CreateAsync	Validates as today (reason code, items, serials), saves the header and lines as PendingApproval. No stock movement and no GL. Notifies approvers.
ApproveAsync(id, comment)	ApprovalService.DecideAsync. On level 1: status becomes PendingSecondApproval and level-2 approvers are notified. On full approval: in one transaction, run today's posting code (IStockMutator.ApplyAsync, serial moves, PostAdjustmentJournalAsync), then set Posted and notify the requester. If posting fails (for example, negative stock), nothing is saved and the status stays PendingSecondApproval.
RejectAsync(id, reason)	Records the rejection, sets Rejected and notifies the requester.
CancelAsync(id)	Requester only, while pending: sets Cancelled.

The posting code moves into a private PostAsync(StockAdjustment) so that create, approve and stock counts (§8, decision 3) all share it.

5.4 API (/api/v1/stock-adjustments)

Method	Route	Permission
POST	/	stock.adjustments with Create (now creates a request)
POST	/{id}/approve	stock.adjustments with Approve
POST	/{id}/reject	stock.adjustments with Approve
POST	/{id}/cancel	stock.adjustments (requester only, checked in the service)
GET	/{id}	now also returns the approval history and pending level
GET	/	new status filter

---

6. Price adjustments (new document)

6.1 Entities

PriceAdjustment (price_adjustments): PriceAdjustmentId, DocNo (PADJ-…), Reason, EffectiveDate (defaults to the approval date), Status (same flow as §5.1), the requested/approved/rejected stamps, RowVersion.

PriceAdjustmentLine: ItemId, plus the old values (snapshot when the request is made) and the new values for SellingMinPrice, SellingMaxPrice and SellingFlatPrice.

ItemPriceHistory (item_price_history): one row per applied change. It holds the item, old and new values, the PriceAdjustmentId, the date applied, and both approvers. This answers "what was the price on day X, and who approved it?"

6.2 Rules

• Validation when the request is made: each item exists and is active; min ≤ flat ≤ max where given; at least one value differs from the current price.
• One pending request per item: a second pending request for the same item is rejected (PriceAdjustmentItemPending), so two requests can't overwrite each other.
• At final approval, in one transaction:
  • If an item's current price no longer matches the request's "old" snapshot (someone changed it in between), that approval fails with PriceAdjustmentStale, and the requester raises a new request.
  • Otherwise, write the new prices to Item and add an ItemPriceHistory row.
• Effective date in the future (optional, §8 decision 6): the request is approved but applied by a daily job on that date.

6.3 Closing the direct-edit route

Selling prices in the item Edit dialog become read-only, with a "Request price change" button that opens the price-adjustment form pre-filled for that item. On the backend, ItemService.UpdateAsync stops changing price fields: it rejects a change with PriceChangeRequiresApproval, or ignores the price fields (see §8, decision 4). Prices set when an item is first created do not need approval (§8, decision 4).

6.4 API (/api/v1/price-adjustments)

List, get (with history), create, approve, reject and cancel, using the same permission pattern as §5.4 on a new nav code products.price-adjustments.

There is also GET /api/v1/items/{id}/price-history.

---

7. Approval settings

A singleton ApprovalConfig, edited under Settings → Approvals:

Setting	Default	Purpose
StockAdjustment.Levels	2	0 = post immediately (today's behaviour), 1 = single approval, 2 = dual approval
StockAdjustment.Level2ThresholdValue	0	Adjustments whose absolute stock value is below this need only one approval (0 = always two)
PriceAdjustment.Levels	2	as above
PriceAdjustment.Level2ThresholdPercent	0	Changes smaller than this % need only one approval (0 = always two)
Level2Roles	empty	When set, only these roles can give the second approval

---

8. Open decisions

#	Question	Recommended default
1	Who can approve: anyone with the Approve action on the screen, or fixed roles?	Anyone with Approve, with Level2Roles (§7) available to restrict level 2 to managers.
2	Thresholds: dual approval for every adjustment, or only above a value?	Always two by default; thresholds configurable (§7).
3	Stock counts: should posting a count also go through dual approval? It creates an adjustment.	Yes. A count post creates its variance adjustment as PendingApproval, otherwise counts become a way around approval.
4	Item edit and item creation: block price edits in the Edit dialog? Do initial prices on a new item need approval?	Block in the Edit dialog (use "Request price change"). Initial prices on creation don't need approval.
5	Admin bypass: can an Admin approve their own request, or both levels?	No. The two-person rule applies to everyone.
6	Future effective dates for price changes?	Not in v1. A change applies when it is approved.
7	Price adjustment scope: selling prices only, or also stock cost (inventory revaluation)?	Selling prices only. Cost revaluation touches FIFO layers and GL and should be its own document.
8	Expiry: should a request still pending after N days be cancelled automatically?	No auto-expiry. The Approvals inbox shows its age.

---

9. Notifications

INotificationService gets a targeted method next to the broadcast one:

Task NotifyUsersAsync(IEnumerable<int> userIds, string moduleKey, string title, string message, string? entityType, int? entityId, CancellationToken ct);

New modules (in-app on by default, through a seed migration like EnableLowStockAlerts):

Key	Sent to
approval.pending	users who can approve at the document's current level (excluding the requester and the level-1 approver)
approval.approved	the requester, when fully approved
approval.rejected	the requester, with the reason

---

10. Frontend

• Approvals inbox (/dashboard/approvals, a sidebar badge with the count):
  • Lists pending stock and price adjustments waiting for me, with their age, level (1/2) and requester.
  • Approve / Reject (reject asks for a reason).
• Stock → Adjustments: status badges (Pending 1/2, Posted, Rejected, Cancelled); the detail page shows the approval timeline and Approve / Reject / Cancel buttons by role. The New form's button reads "Submit for approval".
• Wastage: the same status badges; recorded wastage shows "Pending approval" until posted.
• Products → Price Adjustments (new):
  • The list.
  • The new form: pick items, see current prices, enter new prices, reason.
  • The detail page with the timeline.
• Item page: the prices in the Edit dialog are read-only, with "Request price change"; a new "Price history" panel.
• Settings → Approvals: the §7 settings.

---

11. Migration & rollout

• Migration AddDualApproval:
  • Creates the document_approvals, price_adjustments, price_adjustment_lines, item_price_history and approval_config tables.
  • Adds the new columns on stock_adjustments.
  • Seeds the nav item and permission for products.price-adjustments and the notification modules.
• Existing adjustments stay Posted, with no approval rows.
• Roll-out safety: ship with Levels defaulting to 2, but tell admins to grant the Approve action to at least two users per branch before deploying. Otherwise nothing can ever be approved.

---

12. Phases

1. Approval engine: DocumentApproval, ApprovalService, targeted notifications, ApprovalConfig.
2. Stock adjustments: status flow, deferred posting (including inbound serials), approve/reject/cancel endpoints; wastage and counts on the same path.
3. Price adjustments: entities, service, endpoints, price history, item-edit lock.
4. Frontend: Approvals inbox, adjustment/wastage updates, Price Adjustments pages, Settings → Approvals.
5. Tests and docs (§13), plus PROGRESS.md updates.

---

13. Verification

Backend tests:

• Approval engine:
  • The requester can't approve.
  • The same person can't approve both levels.
  • A user without Approve is refused.
  • Approving the wrong level is refused.
  • A rejection needs a reason.
• Stock adjustments:
  • Nothing moves until the second approval.
  • After full approval, the ledger, GL and serials match today's immediate posting.
  • An approval that would make stock negative fails and the adjustment stays pending.
  • A rejected adjustment never posts.
  • The value threshold drops it to one level.
• Price adjustments:
  • Prices change only after the second approval, and a history row is written.
  • The stale-price check works.
  • A second pending request for the same item is refused.
  • The item edit can no longer change prices.
• Counts: posting a count creates a pending adjustment, not a posted one.

Manual checks: a full two-user approval in the UI for each document, the notification for each step, and the Approvals inbox count.