SMTMS 技術分享：從 AI Coding Agent 開發到資料一致性，打造供應商品質與材料追溯系統
一、為什麼要做 SMTMS？
在製造業的供應商品質管理中，管理供應商、物料與進料檢驗只是基本需求。真正困難的地方，是當物料發生品質異常時，系統能否提供足夠的資料，說明物料從哪裡來、經過哪些檢驗，以及目前處於什麼狀態。
例如，一批物料收到工廠後，會經過收料、內部批次拆分與 IQC（Incoming Quality Control，進料品質檢驗）等流程。如果後續發現品質問題，就必須能夠回頭查明來源，而不是只找到一筆孤立的檢驗紀錄。
因此，我以 SMTMS（Supplier Material Traceability Management System）作為專案，嘗試整合供應商管理、物料管理、進料作業、品質檢驗、異常處理與追溯相關功能。
這個專案的重點不是單純完成 CRUD，而是思考如何讓系統中的資料具有可追溯性、業務規則具有一致性，以及權限控制不會因為 AI 生成程式碼而被忽略。
二、技術架構與選型
SMTMS 採用前後端分離的架構，後端負責業務規則、資料驗證與 API，前端負責操作介面與資料呈現。
| 技術 | 用途 |
|---|---|
| FastAPI | 後端 API 與請求處理 |
| SQLAlchemy 2.x | ORM 與資料存取 |
| Alembic | 資料庫結構版本管理 |
| MySQL | 業務資料儲存 |
| Redis | JWT Token 撤銷等相關狀態管理 |
| React 19 + TypeScript | 前端介面 |
| Vite | 前端開發與建置 |
| Tailwind CSS | 介面樣式 |
| Docker Compose | 開發環境服務編排 |
| Nginx | 前端與服務入口相關配置 |
| JWT + RBAC | 身分驗證與角色權限控制 |
| uv | Python 依賴管理 |
資料庫使用既有的外部 MySQL，Redis 則透過 Docker Compose 提供開發環境服務。這樣的安排也讓資料庫與應用程式容器的生命週期可以分開管理。
在資料存取層，使用 SQLAlchemy 管理 ORM 與資料庫操作，透過 Alembic 管理 Schema 變更，避免開發過程中只修改程式模型，卻忘記同步資料庫結構。
三、核心設計：資料關聯必須反映真實業務流程
在材料追溯系統中，最重要的不是能查出多少筆資料，而是查詢結果是否有實際紀錄支持。
SMTMS 的核心資料關係包含：
Supplier Lot → Material Receipt → Internal Material Lot → IQC Record
各個環節分別代表供應商批次、實際收料、工廠內部批次，以及進料檢驗紀錄。
這些關係必須透過實際建立的資料與關聯取得，不能只依照物料編號或 BOM（Bill of Materials，物料清單）推測某批物料實際使用在哪裡。
這個設計原則可以歸納為：
資料關聯必須有明確來源。
批次與收料紀錄必須保持一致。
檢驗結果與批次放行狀態必須符合業務規則。
缺少實際紀錄時，系統應明確反映資料不足，而不是自行推論。
這些原則比單純增加查詢畫面更重要，因為它們決定了系統提供的資訊能否被信任。
四、資料一致性：不能只依賴前端驗證
在收料與批次管理中，數量錯誤可能直接影響後續的品質管理與庫存資料。
例如，假設某次收料的數量為 100 件，系統允許建立內部批次時拆分數量，但所有拆分數量的總和不能超過實際可分配的收料數量。
如果只在前端檢查數量，使用者仍可能透過直接呼叫 API、重複送出請求，或同時執行多筆操作，造成資料不一致。
因此，這類規則必須在後端進行驗證，並根據操作的資料依賴關係設計交易與併發控制。
在開發過程中，我特別關注以下問題：
收料與內部分批之間的數量限制。
同一物料與供應商批次之間的關聯一致性。
IQC 檢驗結果與放行狀態的同步。
多筆資料更新失敗時，是否可能留下部分完成的結果。
重複請求或併發操作是否可能突破既有驗證。
這些問題不能只靠增加欄位驗證解決，還需要檢查資料庫約束、交易邊界及實際的資料更新順序。
尤其在併發情境下，單元測試通過不代表真實 MySQL 多連線操作一定安全。涉及資料競爭的功能，仍需要適當的整合測試與併發測試，才能進一步確認其正確性。
五、權限設計：驗證身分不等於授權成功
SMTMS 使用 JWT 進行身分驗證，並透過 RBAC（Role-Based Access Control）管理角色與權限。
除了確認使用者是否登入，還必須判斷使用者能否執行特定操作，以及是否有權存取指定供應商的資料。
例如，供應商使用者不應只因為知道其他供應商的資料 ID，就能讀取或修改對方的品質紀錄。
因此，權限檢查不能只存在於前端選單或按鈕。即使前端隱藏了某個功能，後端 API 仍然必須獨立驗證權限與資料範圍。
在這個架構中，需要分別考慮：
Authentication： 確認使用者身分。
Authorization： 確認使用者是否具有所需權限。
Data Isolation： 確認使用者只能存取被授權的資料範圍。
Token Revocation： 在登出等情境下，透過 Redis 等機制管理已撤銷的 Token。
這些概念彼此相關，但不能互相取代。通過登入驗證，不代表自動擁有所有 API 的存取權限。
六、品質異常管理：讓異常處理成為可追蹤流程
品質異常管理不只是建立一筆異常紀錄，還涉及調查、處置、確認與結案等不同階段。
如果系統只保留異常描述與目前狀態，卻沒有記錄處置內容或操作歷程，就很難理解異常是如何被處理的。
因此，品質異常相關設計需要考慮：
異常紀錄及其關聯資料。
調查與處置內容。
狀態變更及歷程。
附件上傳、下載與刪除。
使用者的操作權限與供應商資料隔離。
附件也不只是檔案上傳問題。系統必須確認檔案與業務紀錄的關聯、存取權限，以及刪除操作的授權範圍。
不過，品質異常管理與完整 CAPA（Corrective and Preventive Action，矯正與預防措施）並不是同一件事。若尚未具備根因分析、矯正措施、預防措施及有效性驗證等完整流程，就不應把一般異常處理功能描述成已完成的 CAPA 系統。
七、AI Coding Agent：開發速度之外，更重要的是限制錯誤
這個專案的另一個重點，是使用 AI Coding Agent 協助開發。
AI 可以協助建立 API、整理 ORM、撰寫前端頁面、補充測試與處理錯誤，但產出程式碼並不代表業務邏輯一定正確。
尤其當需求涉及資料一致性、批次關聯或權限隔離時，AI 可能產生語法正確、卻違反業務規則的實作。
因此，我採取的開發思路不是讓 Agent 自由擴大功能，而是盡可能明確定義修改範圍與驗證條件。
1. 先理解現有實作，再修改程式
面對既有程式或錯誤訊息，先確認實際執行流程、資料表結構、API 路由與相關測試，再判斷問題出在哪裡。
不應只根據錯誤訊息就直接新增欄位、服務類別或抽象層。
2. 明確定義不可違反的業務規則
例如：
收料數量不可超過允許範圍。
內部分批總數不可超過可分配數量。
供應商資料不可跨租戶或授權範圍存取。
IQC 檢驗結果與放行狀態必須一致。
追溯結果必須由實際資料關聯取得。
這些規則應該成為 Agent 修改程式時的明確限制，而不是依賴模型自行猜測。
3. 控制修改範圍
採取 KISS 與最小修改原則，優先重用既有的程式模式，避免為了單一需求就引入不必要的 DTO、Service、Helper 或新的抽象層。
修改範圍越大，回歸測試與理解成本通常也越高。
4. 讓驗證結果有明確依據
透過自動化測試、型別檢查、Lint、Migration 檢查與前端建置，確認修改至少符合已定義的技術條件。
但也必須區分測試通過與功能完整：測試只能證明已覆蓋的情境，不能自動證明所有業務規則都正確。
八、為什麼要拆分規格文件？
隨著專案功能增加，單一 spec.md 容易同時包含需求、目前實作、已知缺陷、資料表結構、測試結果與未來規劃。
這會讓 AI Coding Agent 難以判斷哪些是必須遵守的規則、哪些只是目前的程式行為，以及哪些功能尚未實作。
因此，SMTMS 的文件整理方向是將不同責任分開：
01_SRS.md：系統應該提供什麼功能。02_DOMAIN_RULES.md：業務上不能違反的規則。03_ADR.md：架構與技術決策。04_API_CONTRACT.md：API 契約。05_DATABASE_SCHEMA.md：資料庫結構。06_CURRENT_STATE.md：目前的實作狀態與已知限制。07_ACCEPTANCE.md：如何驗證功能是否符合需求。08_ROADMAP.md：未來的開發順序與優先級。
這樣的拆分不只是文件管理，而是把原本依賴開發者記憶的知識，轉換成 Agent 可以明確引用的工程約束。
九、目前仍需持續驗證的部分
SMTMS 的開發不能只以功能頁面是否存在作為完成標準。
後續仍需要針對以下項目持續確認：
真實 MySQL 多連線下的併發正確性。
所有關鍵業務規則是否都有負向測試。
追溯查詢是否能完整呈現實際存在的關聯鏈。
品質異常是否具備完整的稽核歷程與 CAPA 流程。
報表與匯出是否符合完整資料集的需求。
部署、安全性與效能是否經過實際環境驗證。
這些項目必須依照實際完成的實作與測試逐步確認，不應因為規格已經列出，就認定功能已經完成。
十、結語
SMTMS 對我而言，不只是練習 FastAPI、React 或資料庫操作的專案，更是一個思考 AI 輔助工程開發方式的實例。
AI Coding Agent 可以加速程式碼產出，但工程上的責任並沒有因此消失。資料是否正確、交易是否一致、權限是否完整，以及系統是否真正符合業務規則，仍然需要透過明確的設計、可驗證的測試與持續的人工判斷來確保。
我認為 AI 輔助開發最有價值的地方，不是讓 AI 一次寫出大量程式碼，而是讓它在明確的規則與邊界下完成工作，並讓每一次修改都能被理解、被驗證，也能在出問題時被追查。
這也是 SMTMS 希望呈現的工程方向：以 AI 提升開發效率，以領域規則控制風險，以測試與證據確保系統的可信度。
