feat&fix: 完善半成品/序列号闭环流转逻辑

1. 调整物料编码字段为可空，优化注释说明
2. 修复Vite构建自动清空产物目录冲突问题
3. 优化前端提示文案与表单占位符
4. 为各前端项目添加内联SVG图标
5. 重构MES半成品流转逻辑，不再静默吞掉WMS错误并记录日志
6. 生成并添加空的WMS客户端静态文件
7. 完善Ent ORM模型的空值支持与查询谓词
8. 优化半成品入库接口，支持doneProcessCodes数组格式，新增SN反查物料编码逻辑
9. 更新帮助文档与操作手册

bj_power_wms/internal/handler/misc.go

@@ -3,6 +3,8 @@ package handler
 import (
 	"encoding/json"
 	"net/http"
+	"strconv"
+	"strings"
 
 	"bj_power_wms/ent"
 	"bj_power_wms/ent/ordermaterialledger"
@@ -15,11 +17,15 @@ import (
 // 半成品 / 包装 / 台账 相关（盘点见 stocktake.go）
 
 // semiInboundHandler 半成品入库（携带已完成工序）
+// 与 MES 闭环：MES 工位报工暂存退库时调用本接口，把半成品 SN 入 WMS 库。
+// 为保持两系统解耦，materialCode 不强制要求——优先用请求传入，
+// 其次按 SN 反查 WMS 序列号台账，都没有则留空（SN 本身即追溯锚点）。
 func semiInboundHandler(ctx *svc.ServiceContext) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		var req struct {
 			Sn               string `json:"sn"`
 			MaterialCode     string `json:"materialCode"`
+			DoneProcessCodes []int  `json:"doneProcessCodes"`
 			CompletedProcess string `json:"completedProcess"`
 			ZoneCode         string `json:"zoneCode"`
 			OrderNo          string `json:"orderNo"`
@@ -29,8 +35,8 @@ func semiInboundHandler(ctx *svc.ServiceContext) http.HandlerFunc {
 			fail(w, http.StatusBadRequest, "参数错误")
 			return
 		}
-		if req.Sn == "" || req.MaterialCode == "" {
-			fail(w, http.StatusBadRequest, "sn 和 materialCode 必填")
+		if req.Sn == "" {
+			fail(w, http.StatusBadRequest, "sn 必填")
 			return
 		}
 
@@ -46,10 +52,29 @@ func semiInboundHandler(ctx *svc.ServiceContext) http.HandlerFunc {
 			return
 		}
 
+		// 已完成工序：MES 传 doneProcessCodes([]int) 优先，否则用 completedProcess 字符串
+		completed := req.CompletedProcess
+		if len(req.DoneProcessCodes) > 0 {
+			parts := make([]string, 0, len(req.DoneProcessCodes))
+			for _, c := range req.DoneProcessCodes {
+				parts = append(parts, strconv.Itoa(c))
+			}
+			completed = strings.Join(parts, ",")
+		}
+
+		// 物料编码：优先请求传入，其次按 SN 反查序列号台账
+		materialCode := req.MaterialCode
+		if materialCode == "" {
+			if snRec, e := ctx.EntClient.SerialNumber.Query().
+				Where(serialnumber.SnCodeEQ(req.Sn)).Only(ctx0()); e == nil {
+				materialCode = snRec.MaterialCode
+			}
+		}
+
 		rec, err := ctx.EntClient.SemiFinished.Create().
 			SetSn(req.Sn).
-			SetMaterialCode(req.MaterialCode).
-			SetNillableCompletedProcess(strPtr(req.CompletedProcess)).
+			SetNillableMaterialCode(strPtr(materialCode)).
+			SetNillableCompletedProcess(strPtr(completed)).
 			SetNillableZoneCode(strPtr(req.ZoneCode)).
 			SetStatus("在库").
 			SetNillableOrderNo(strPtr(req.OrderNo)).
@@ -59,10 +84,10 @@ func semiInboundHandler(ctx *svc.ServiceContext) http.HandlerFunc {
 			return
 		}
 
-		// 同时记入 SN 台账（半成品也是精密件）
+		// 同时记入 SN 台账（半成品也是精密件，便于按 SN 追溯）
 		ctx.EntClient.SerialNumber.Create().
 			SetSnCode(req.Sn).
-			SetMaterialCode(req.MaterialCode).
+			SetNillableMaterialCode(strPtr(materialCode)).
 			SetStatus("在库").
 			SetNillableCurrentZone(strPtr(req.ZoneCode)).
 			SaveX(ctx0())