TJK: Disable user-initiated damaged stock adjustments

[gqcorneby]

📌 References

• Issue: #869ctkw25 CU-869ctkw25

Purpose

• Damaged stock currently leaves the warehouse via direct stock-adjustment flows that write straight to Transaction / TransactionEntry with no document attachment — there's no photo, no signed report, no vendor invoice. The drop in quantity is unauditable.
• Tajikistan wants damaged goods to flow through the existing stock-transfer-documents workflow (transfer into a Damaged bin with proof attached, then write off downstream) instead of the direct adjustment paths.

NOTE: Implementation does not guard against direct API calls. Flag only applies to UI selectors createDamaged page

📝 Implementation

• New config flag openboxes.custom.adjustments.damaged.enabled — enabled by default, only literal false opts out. Tajikistan (docker/openboxes.yml) sets it to false;
• New custom service CustomReasonCodeService under org.pih.warehouse.custom.damagedAdjustments — wraps ReasonCode.listInventoryAdjustmentReasonCodes() and filters DAMAGED out when the flag is disabled. Single isDamagedEnabled() getter centralizes the flag semantics.
• New custom interceptor DamagedAdjustmentInterceptor — blocks GET/POST inventory/createDamaged with a 302 redirect to errors/handleForbidden when the flag is disabled.
• Three surgical edits to upstream files route the existing UI through the custom service:
  • SelectTagLib.selectInventoryAdjustmentReasonCode / selectTransactionType → use the custom service.
  • ReasonCodeApiController ADJUST_INVENTORY branch → use the custom service.
  • _adjustStock.gsp → use <g:selectInventoryAdjustmentReasonCode> taglib (was inlining ReasonCode.listInventoryAdjustmentReasonCodes()).
  • _actions.gsp → wraps the "Create Damaged" menu link in <g:if>.
• 2 Spock specs covering both flag states (unit + integration).

✨ Description of Change

Defence-in-depth gate on the four UI chokepoints where a user can record DAMAGED as an adjustment reason:

1. Adjust Stock dialog (per-line reason code dropdown)
2. Create Transaction wizard (selectTransactionType dropdown + reason code dropdown)
3. Product → Actions menu (Create Damaged Transaction link)
4. POST /inventory/createDamaged direct URL (interceptor 302)

Out of scope (intentional):

• Programmatic creation of damaged transactions via services (e.g. a future "write-off from Damaged bin" flow). Only user-initiated paths are gated.
• No DB migration — TransactionType for "Damaged" stays in the database, so programmatic flows and historical reports keep working.

📹 Screenshots/Screen capture

2026-05-21.16-55-13.mp4

🔥 Notes to the tester

To run with the flag disabled:

cd docker && docker compose up -d db
./gradlew bootRun -Dserver.port=8081

Verify each chokepoint (flag = false):

1. Product Actions menu: open any product → Actions → no "mark as damaged" link.
2. Direct URL: GET /openboxes/inventory/createDamaged?product.id=<id> redirects (302) to /openboxes/errors/handleForbidden. Server log emits Damaged adjustment blocked for user=<username> ....
3. Adjust Stock dialog: from a stock card → Adjust Stock → Reason Code dropdown does not include "DAMAGED".
4. Create Transaction wizard: Inventory → Create Transaction → Transaction Type dropdown does not include "Damaged".
5. Reason Code API: GET /openboxes/api/reasonCodes?activityCode=ADJUST_INVENTORY response does not include DAMAGED.

Flip to enabled and re-verify (flag = true):

• Remove the custom.adjustments.damaged.enabled: false block from docker/openboxes.yml, restart, repeat the five checks — DAMAGED reappears everywhere and createDamaged returns the form normally.

Regression checks:

• Other reason codes (e.g. EXPIRED, STOLEN) and other transaction types still appear in the dropdowns with the flag disabled.
• Existing historical "Damaged" transactions still render in transaction history (the TransactionType row was never deleted).