FPSMS-backend/docs/deploy/20260819_po-m18id-remap.md

Deploy note — PO line m18Id rematch (recode)

Date: 2026-08-19 Branch / build: uncommitted (QA before prod) Author: agent + QA

Summary

• PO/DO sync failed when M18 recoded a product (proId changed, item code unchanged), e.g. PFP002PO26080303 lines 20022 / 20023 / 20024.
• Sync now links the new M18 id onto the existing local item (same code + type) and does not rebuild/delete item_uom.

Scope

• Backend: ItemsService.saveItem, M18MasterDataService.saveProduct / saveProducts, remap helper
• Frontend: none
• DB / Liquibase: none
• Config / ops: none (use existing GET /m18/test/po-by-code)

Commits

• (not committed yet)

Safety rules (what this deploy will / will not do)

Situation	Behaviour
Local item already has that m18Id	Unchanged: normal product/PO update
Same code + type, new unused m18Id	Update items.m18Id only. No UOM delete/rebuild, no QC/name wipe
New m18Id already on another item	Refuse (keep old mapping)
Same code, different type	Will not auto-link (same as before for type mismatch)
Brand-new M18 product, no local code	Creates item + UOMs as before
Scheduled product sync of already-mapped items	Unchanged full product/UOM sync
Local PO status not PENDING	PO resync is skipped (existing rule)

Pre-check SQL (prod or staging, before resync)

-- 1) Failed PO lines for this PO
SELECT d.id, d.m18Id AS m18_line_id, d.status, d.dataLog, d.createDate
FROM m18_data_log d
WHERE d.refType = 'Purchase Order Line'
  AND d.status = 'FAIL'
  AND d.dataLog LIKE '%PFP002PO26080303%'
ORDER BY d.id DESC
LIMIT 20;

-- 2) Local PO must be PENDING
SELECT id, code, status, m18Id
FROM purchase_order
WHERE code = 'PFP002PO26080303' AND deleted = 0;

-- 3) After you know the 3 M18 product codes, confirm one local row each
SELECT id, code, name, type, m18Id
FROM items
WHERE deleted = 0 AND code IN ('CODE1', 'CODE2', 'CODE3');

Confirm each of the three codes has exactly one local row, and its current m18Id is not already 20022/20023/20024 on a different item:

SELECT id, code, m18Id FROM items
WHERE deleted = 0 AND m18Id IN (20022, 20023, 20024);

Expected before fix: no rows (or only unrelated items — if any, do not auto-resync; fix mapping manually).

Test plan

#	Steps (who / where / data)	Expected result
1	Staging first. Snapshot items.m18Id + item_uom counts for the 3 item codes.	Baseline recorded
2	Confirm M18 products 20022/20023/20024 still have the same codes as local items.	Codes match; types still map to the same FPSMS type
3	Confirm local PO PFP002PO26080303 status is PENDING.	If not pending, stop — resync will skip the whole PO
4	Call GET /m18/test/po-by-code?code=PFP002PO26080303 (auth as ops).	HTTP 200; totalFail for those 3 lines is 0 (or success list includes the PO)
5	SQL: items.m18Id for the 3 codes is now 20022/20023/20024. item_uom row count and ids unchanged. QC category / shelf life unchanged.	Remap-only; no UOM wipe
6	UI: PO workbench / PO detail for PFP002PO26080303 shows 6 lines (previously 3 missing).	Failed lines created
7	Regression: pick a normal mapped item, run scheduled or GET /m18/product/{existingM18Id}.	Item still updates as before; UOMs still sync
8	Confirm no new PO_LINE FAIL email for this PO after resync.	Alert not re-sent for these 3 proIds

Out of scope / not tested

• Recoded products whose item code also changed (will not auto-link)
• Non-PENDING PO overwrite (by design skipped)
• DO with the same recode (same resolveLocalItemId path; spot-check only if a DO uses these 3 items)
• Live M18 UOM id change on the recoded product (PO qty conversion still uses existing purchase UOM)

Rollback

• Revert backend deploy (no Liquibase, no frontend).
• If only items.m18Id was updated, restore previous m18Id from the pre-check snapshot. PO lines already inserted stay; delete/fix only if QA rejects the PO.
• Do not run a full product resync on the new proIds expecting to undo UOMs — this path does not rewrite UOMs.