7.2 KiB

Originale Blame Cronologia

MTMS (FPSMS) ↔ M18 資料對照手冊

本文件說明 MTMS / FPSMS 與 M18 之間的主檔與交易對應、同步方向，以及已知陷阱。

區塊	維護方式
本手冊（說明、流程、陷阱）	人手維護
`docs/generated/` 對照表	腳本產生（見下方）

重新產生自動表（改完 enum / mapping 後請跑）：

python scripts/generate_m18_mapping_docs.py

匯出 Word / Excel（給非技術閱讀；需已安裝 python-docx、openpyxl）：

pip install python-docx openpyxl
python scripts/export_m18_mapping_office.py

產出：

docs/exports/MTMS_M18_DATA_MAPPING.docx
docs/exports/MTMS_M18_DATA_MAPPING.xlsx

1. 系統與名詞

名稱	說明
MTMS / FPSMS	本後端 `FPSMS-backend` + 前端 `FPSMS-frontend`
M18	外部 ERP／主檔與採購／送貨來源系統
Pull	M18 → MTMS（product / vendor / unit / currency / BOM / business unit / PO / DO）
Push	MTMS → M18（例如 GRN、BOM for shop）

設定入口：m18/M18Config.kt（m18.config.*）、scheduler 見 application.yml / application-prod.yml（scheduler.m18Sync、scheduler.m18Grn）。

主程式目錄：src/main/java/com/ffii/fpsms/m18/。

2. Master API 類型（`StSearchType`）

完整表見自動產生檔：

→ generated/m18-stsearch-types.md

摘要：

M18 `stSearch`	MTMS 落點
`pro`	`items`
`ven`	`shop`（`type=supplier`）
`virDept`	`shop`（`type=shop`）
`unit`	`uom_conversion`（+ cunit）
`cur`	`currency`
`udfbomforshop`	`bom` / materials

實作：M18MasterDataService。

3. 貨品類型（最常查）

3.1 同步規則（自動表）

→ generated/m18-item-type-mapping.md

程式：M18MasterDataService.saveProduct / saveProducts 依 pro.udfProducttype：

Consumable Material     → consumables
Non-consumable Material → non-consumables
Product                 → fg
WIP                     → sfg
Item                    → item
(其他，含 CMB)          → mat   ← default

Enum 定義：modules/master/web/models/NewItemRequest.kt（ItemType、M18ItemType）。

3.2 UI 顯示（存貨）

存貨 Type 欄：t(itemType)，翻譯在 FPSMS-frontend/src/i18n/zh/inventory.json。

`items.type`	存貨頁（zh）
`mat`	原料
`fg`	成品
`sfg` / `wip`	半成品
`consumables` / `cmb`	消耗品
`non-consumables` / `nm`	非消耗品／雜項

系統沒有「產品」這個 items.type。M18 的 Product 對應 MTMS fg（成品）。

3.3 可手動改嗎？

可以：Settings → Items → Edit → Type（ProductDetails.tsx：fg / wip / mat / cmb / nm）。

注意：之後若再跑 product sync，type 會依 M18 udfProducttype 覆寫（含再次落到 mat）。

3.4 已知陷阱：`CMB`

M18 實務上可出現 "udfProducttype": "CMB"（例如蔗糖水 MG1852）。

"CMB" ≠ "Consumable Material"
也不等於前端的 cmb
→ sync 走 else → mat → 存貨顯示原料

若要顯示消耗品：需改 mapping（例如把 CMB 對到 consumables），或在 M18 改成已支援的字串；僅手動改 MTMS 可能被下次 sync 蓋掉。

4. 供應商與店鋪

方向	M18	MTMS
Pull vendors	`ven`	`shop`，`ShopType.SUPPLIER`（`supplier`）
Pull business units	`virDept`	`shop`，`ShopType.SHOP`（`shop`）

鍵：shop.m18Id、shop.code。名稱優先 descZhTW → descZhCN → desc。

ShopType：modules/master/enums/ShopType.kt。

5. 單位（UoM）

M18	MTMS
Unit master (`unit`)	`uom_conversion`（`code`、`udfudesc`、`udfShortDesc`、`m18Id`…）
Cunit 明細	`M18CunitService.replaceForUnit`

Item 級採購／庫存／銷售單位在 sync product price 時寫入 item_uom（見 M18MasterDataService product 區塊）。

PO／DO 行常同時保留：

欄位	意義
`qty` / `uomId`	MTMS 業務單位（例如採購單位換算後）
`qtyM18` / `uomIdM18`	M18 原始單位數量

PO 換算邏輯見 M18PurchaseOrderService（convertQtyToPurchaseQty）。

6. 貨幣、BOM

M18	MTMS	Service
Currency	`currency`	`saveCurrencies`
BOM (`udfbomforshop`)	`bom` / `bom_material`	`saveBoms`

Shop BOM 回寫 M18：M18BomForShopService（push）。

7. 交易文件（摘要）

文件	方向	MTMS 主表	筆記
PO	M18 → MTMS	`purchase_order` / `purchase_order_line`	`m18Id` / data log；qty 可能換算
DO	M18 → MTMS	`delivery_order` / `delivery_order_line`	含 `qtyM18`、`uomIdM18`
GRN	MTMS → M18	stock-in → M18 GRN API	部分 `m18CreatedUId` 不送 GRN（見下）

GRN 略過規則

m18/M18GrnRules.kt：

M18 PO `createUid`	備註	行為
`2569`	legato	不 post GRN
`2676`	xtech	不 post GRN

8. Config 鍵（對照時常用）

見 M18Config / application-*.yml：

m18.config.seriesId.pp|pf|sc|se|sf|sr
m18.config.beId.pp|pf|toa
m18.config.supplier-not.material-po
m18.config.supplier.shop-po / oem-po
scheduler.m18Sync.enabled
scheduler.m18Grn.createEnabled

9. 驗證用 SQL 範例

-- 某貨品目前 type（決定存貨顯示）
SELECT code, name, type, m18Id, m18LastModifyDate
FROM items
WHERE deleted = 0 AND code = 'MG1852';

-- 統計 type 分佈
SELECT type, COUNT(*) AS cnt
FROM items
WHERE deleted = 0
GROUP BY type
ORDER BY cnt DESC;

若 M18 回傳 udfProducttype 可與上表比對；對不上表中「exact string」者皆會變 mat。

10. 維護約定

改 mapping：先改 Kotlin enum / when，再跑 python scripts/generate_m18_mapping_docs.py，把 docs/generated/* 一併 commit。
改說明／陷阱：只改本檔，勿手改 docs/generated/。
給營運／開會用：跑 python scripts/export_m18_mapping_office.py，打開 docs/exports/*.docx / *.xlsx。
新發現的 M18 值（如新的 udfProducttype）：記入 generated 腳本的 KNOWN_UNMAPPED_M18_VALUES，或補正式 mapping 後重生。
PR 若動到 NewItemRequest.kt / M18MasterDataService product type 分支，review 應檢查 generated docs 是否已更新。

11. 相關程式索引

主題	路徑
Item / M18 type enums	`modules/master/web/models/NewItemRequest.kt`
Product sync	`m18/service/M18MasterDataService.kt`
StSearch	`m18/model/M18MasterDataRequest.kt`
Shop type	`modules/master/enums/ShopType.kt`
GRN skip	`m18/M18GrnRules.kt`
PO sync	`m18/service/M18PurchaseOrderService.kt`
DO sync	`m18/service/M18DeliveryOrderService.kt`
BOM→M18	`m18/service/M18BomForShopService.kt`
存貨 Type 顯示	`InventoryTable.tsx` + `i18n/zh/inventory.json`
物品 Type 下拉	`CreateItem/ProductDetails.tsx`

7.2 KiB Originale Blame Cronologia