Merge remote-tracking branch 'base-version/main' into dev

zt-module-system/zt-module-system-server/src/main/java/com/zt/plat/module/system/controller/admin/integration/iwork/vo/IWorkFullSyncReqVO.java

@@ -0,0 +1,53 @@
+package com.zt.plat.module.system.controller.admin.integration.iwork.vo;
+
+import com.zt.plat.module.system.enums.integration.IWorkSyncEntityTypeEnum;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import lombok.Data;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * iWork 全量同步请求
+ */
+@Data
+public class IWorkFullSyncReqVO {
+
+    @Schema(description = "起始页码，从 1 开始", example = "1")
+    @Min(1)
+    private Integer startPage = 1;
+
+    @Schema(description = "最大处理页数，null 表示处理至 iWork 返回的末页", example = "10")
+    @Min(1)
+    private Integer maxPages;
+
+    @Schema(description = "每次分页从 iWork 拉取的记录数", example = "100")
+    @Min(1)
+    @Max(500)
+    private Integer pageSize = 100;
+
+    @Schema(description = "同步范围列表，默认同步全部。可选：subcompany、department、jobTitle、user")
+    private List<String> scopes;
+
+    @Schema(description = "是否包含已失效（canceled=1）的记录", example = "false")
+    private Boolean includeCanceled = Boolean.FALSE;
+
+    public Set<IWorkSyncEntityTypeEnum> resolveScopes() {
+        EnumSet<IWorkSyncEntityTypeEnum> defaults = EnumSet.allOf(IWorkSyncEntityTypeEnum.class);
+        if (scopes == null || scopes.isEmpty()) {
+            return defaults;
+        }
+        Set<IWorkSyncEntityTypeEnum> resolved = scopes.stream()
+                .map(IWorkSyncEntityTypeEnum::fromCode)
+                .filter(java.util.Objects::nonNull)
+                .collect(Collectors.toCollection(() -> EnumSet.noneOf(IWorkSyncEntityTypeEnum.class)));
+        if (resolved.isEmpty()) {
+            return defaults;
+        }
+        return resolved;
+    }
+}

zt-module-system/zt-module-system-server/src/main/java/com/zt/plat/module/system/controller/admin/integration/iwork/vo/IWorkFullSyncRespVO.java

@@ -0,0 +1,34 @@
+package com.zt.plat.module.system.controller.admin.integration.iwork.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * iWork 全量同步响应
+ */
+@Data
+public class IWorkFullSyncRespVO {
+
+    @Schema(description = "本次处理的总页数")
+    private Integer processedPages;
+
+    @Schema(description = "每次分页请求的条数")
+    private Integer pageSize;
+
+    @Schema(description = "分部统计信息")
+    private IWorkSyncEntityStatVO subcompanyStat = new IWorkSyncEntityStatVO();
+
+    @Schema(description = "部门统计信息")
+    private IWorkSyncEntityStatVO departmentStat = new IWorkSyncEntityStatVO();
+
+    @Schema(description = "岗位统计信息")
+    private IWorkSyncEntityStatVO jobTitleStat = new IWorkSyncEntityStatVO();
+
+    @Schema(description = "人员统计信息")
+    private IWorkSyncEntityStatVO userStat = new IWorkSyncEntityStatVO();
+
+    @Schema(description = "每个批次的详细统计")
+    private List<IWorkSyncBatchStatVO> batches;
+}

zt-module-system/zt-module-system-server/src/main/java/com/zt/plat/module/system/controller/admin/integration/iwork/vo/IWorkHrSyncRespVO.java

@@ -0,0 +1,74 @@
+package com.zt.plat.module.system.controller.admin.integration.iwork.vo;
+
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * iWork 人力同步响应。
+ */
+@Data
+@Schema(description = "iWork 人力同步响应")
+public class IWorkHrSyncRespVO {
+
+    @Schema(description = "响应码")
+    private String code;
+
+    @Schema(description = "提示信息")
+    private String message;
+
+    @Schema(description = "是否成功")
+    private boolean success;
+
+    @Schema(description = "同步结果明细")
+    private List<SyncResult> result;
+
+    @Data
+    @Schema(description = "同步结果项")
+    public static class SyncResult {
+
+        @Schema(description = "操作动作 add/update/delete")
+        @JsonProperty("@action")
+        private String action;
+
+        @Schema(description = "外部编码")
+        @JsonProperty("code")
+        private String code;
+
+        @Schema(description = "执行结果 success/fail")
+        @JsonProperty("result")
+        private String result;
+
+        @Schema(description = "是否成功")
+        @JsonProperty("success")
+        private Boolean success;
+
+        @Schema(description = "失败描述")
+        @JsonProperty("message")
+        private String message;
+
+        @JsonIgnore
+        private Map<String, Object> attributes;
+
+        @JsonAnySetter
+        public void putAttribute(String key, Object value) {
+            if (attributes == null) {
+                attributes = new LinkedHashMap<>();
+            }
+            attributes.put(key, value);
+        }
+
+        @JsonAnyGetter
+        public Map<String, Object> any() {
+            return attributes == null ? Collections.emptyMap() : attributes;
+        }
+    }
+}

zt-module-system/zt-module-system-server/src/main/java/com/zt/plat/module/system/controller/admin/integration/iwork/vo/IWorkOrgRespVO.java

@@ -1,28 +1,15 @@
 package com.zt.plat.module.system.controller.admin.integration.iwork.vo;
 
 import io.swagger.v3.oas.annotations.media.Schema;
-import lombok.Data;
-
-import java.util.Map;
 
 /**
- * 对 iWork 人力组织 REST 请求的响应封装。
+ * @deprecated 请改用强类型的 IWorkHr*RespVO，避免再引用该占位类。
  */
-@Data
-public class IWorkOrgRespVO {
+@Deprecated(forRemoval = true)
+@Schema(description = "已废弃，占位用")
+public final class IWorkOrgRespVO {
 
-    @Schema(description = "响应中的业务数据（data 字段或整体映射)")
-    private Map<String, Object> payload;
-
-    @Schema(description = "原始响应字符串")
-    private String rawBody;
-
-    @Schema(description = "是否判断为成功")
-    private boolean success;
-
-    @Schema(description = "提示信息")
-    private String message;
-
-    @Schema(description = "响应码")
-    private String code;
+    private IWorkOrgRespVO() {
+        throw new UnsupportedOperationException("Use IWorkHr*RespVO instead");
+    }
 }

zt-module-system/zt-module-system-server/src/main/java/com/zt/plat/module/system/controller/admin/integration/iwork/vo/IWorkSingleSyncReqVO.java

@@ -0,0 +1,26 @@
+package com.zt.plat.module.system.controller.admin.integration.iwork.vo;
+
+import com.zt.plat.module.system.enums.integration.IWorkSyncEntityTypeEnum;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+/**
+ * iWork 单条同步请求
+ */
+@Data
+public class IWorkSingleSyncReqVO {
+
+    @Schema(description = "同步的实体类型", requiredMode = Schema.RequiredMode.REQUIRED, example = "user")
+    @NotNull(message = "实体类型不能为空")
+    private IWorkSyncEntityTypeEnum entityType;
+
+    @Schema(description = "iWork 提供的实体主键 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "10001")
+    @NotNull(message = "实体 ID 不能为空")
+    @Min(1)
+    private Long entityId;
+
+    @Schema(description = "缺失时是否自动创建", example = "true")
+    private Boolean createIfMissing = Boolean.TRUE;
+}