flow-center-service/src/main/java/com/yunhai/flowcenter/model/OapiModels.java

package com.yunhai.flowcenter.model;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import lombok.Data;

import java.util.List;
import java.util.Map;

/**
 * /oapi/flow/** 契约模型（出入参字段与 svc-hall FlowCenterClient 逐字对齐，
 * 契约锚点：《流程中心M1开工说明.md》§5——两侧已编码，改动须双向同步）。
 */
public final class OapiModels {

    private OapiModels() {
    }

    /** 流程摘要（list 元素 / {flowGuid} 详情） */
    @Data
    @JsonIgnoreProperties(ignoreUnknown = true)
    public static class FlowSummaryVo {
        private String flowGuid;
        private String name;
        private Integer version;
        private String nodeSummary;
    }

    /** 代发起请求体（POST /oapi/flow/apply；formData 为 JSON 对象透传） */
    @Data
    @JsonIgnoreProperties(ignoreUnknown = true)
    public static class ApplyBody {
        private String flowGuid;
        private String bizType;
        private String bizId;
        private String bizTitle;
        private String bizUrl;
        /** 业务摘要 JSON 快照（字符串或对象均可，统一落字符串） */
        private Object bizSnapshot;
        private Integer submitterId;
        private String submitterName;
        /** 表单数据对象（业务方编辑页产出，无表单模式不传） */
        private Map<String, Object> formData;
    }

    /** 代发起响应（biz uk 幂等：重复代发起 HTTP 200 + duplicated:true 返回既有办件） */
    @Data
    public static class ApplyResultVo {
        private Long instanceId;
        private boolean duplicated;
    }

    /** 按业务键查办件响应（对账兜底；traceJson 含 assigneeId 轨迹供办理人放行判定） */
    @Data
    public static class InstanceVo {
        private Long instanceId;
        private Integer status;
        private Integer version;
        private String nodeSummary;
        private String traceJson;
        private List<Integer> assigneeIds;
        private String currentNodes;
        private String bizTitle;
        private Integer submitterId;
        private String submitterName;
        private String submitTime;
        private String finishTime;
    }

    /** 回调注册请求体（POST /oapi/flow/callback/reg） */
    @Data
    @JsonIgnoreProperties(ignoreUnknown = true)
    public static class CallbackRegBody {
        private String flowGuid;
        private String callbackUrl;
        /** 订阅事件逗号分隔，空=全部 */
        private String eventTypes;
        /**
         * 接收方 context-path / 网关前缀（可选，形如 /notice；无则空）。
         * 推送时按 AppSignInterceptor 的既有约定从 URL path 中剥离后再签 X-Signature，
         * 与接收方 AppAuthFilter 用 request.contextPath 剥离后的 path 对齐——配置错会 401。
         */
        private String basePath;
    }

    /** 回调注册响应（secret 注册时生成下发） */
    @Data
    public static class CallbackRegResultVo {
        private String secret;
    }

    /**
     * 办件进度（结构化轨迹，2026-09-16 用户拍板：SDK 对外提供图3/图4时间线数据源）。
     * steps 按 nodeId 任务到达顺序聚合（同人多任务行保留原始顺序），发起申请固定为第 0 步。
     * SDK DTO com.yunhai.platform.openapi.flow.model.FlowProgress 与本契约逐字对齐。
     */
    @Data
    public static class ProgressVo {
        private Long instanceId;
        private String bizType;
        private String bizId;
        private String bizTitle;
        /** 办件状态：10 审批中 / 20 已完成 / 30 已拒绝 / 40 已撤回 */
        private Integer status;
        private String currentNodes;
        private Integer submitterId;
        private String submitterName;
        private String submitTime;
        private String finishTime;
        private List<ProgressStepVo> steps;
    }

    /** 进度步骤（同一节点全部任务行聚合为一步，b 会签时 assignees 多行） */
    @Data
    public static class ProgressStepVo {
        private String nodeId;
        private String nodeName;
        /** 步骤标签：发起申请/待审核/已同意/已拒绝/已退回/已移交/失效（任务状态汇总口径见 FlowProgress.stage） */
        private String label;
        /** 节点当前是否在办 */
        private boolean active;
        private List<ProgressTaskVo> assignees;
    }

    /** 进度步骤内的办理人行（多人步骤每人一条；状态取自该行任务真实状态） */
    @Data
    public static class ProgressTaskVo {
        private Long taskId;
        private Integer userId;
        private String userName;
        /** 任务状态：0 待办 / 1 同意 / 2 拒绝 / 3 失效 / 4 已退回 / 5 已移交 */
        private Integer status;
        private String statusLabel;
        private String opinion;
        private String arriveTime;
        private String handleTime;
        /** 多出口节点办理时所选出口名 */
        private String edgeName;
    }

    /** 流程图图片流换图响应（token 换图模式：imgUrl 可直接放 <img src>，免 app-sign） */
    @Data
    public static class DiagramUrlVo {
        /** 免签图片端点相对路径（?token=xxx），消费方可拼到本服务的对外网关地址后 */
        private String imgUrl;
        /** 相对 token 有效期（秒） */
        private long expiresIn;
    }

    /** 待办任务行（tasks/todo 元素）：审批列表页数据源，带办件定位与快照 */
    @Data
    public static class TodoTaskVo {
        private Long taskId;
        private Long instanceId;
        /** 办件当前版本（办理前对账用） */
        private Integer instanceVersion;
        private String bizType;
        private String bizId;
        private String bizTitle;
        /** 办件快照原文（JSON 字符串，发起时未传则 null） */
        private String bizSnapshot;
        private String nodeId;
        private String nodeName;
        private Integer assigneeId;
        private String assigneeName;
        private String arriveTime;
    }

    /** 办件行（instances 元素）：应用侧列表/对账数据源 */
    @Data
    public static class InstanceItemVo {
        private Long instanceId;
        private Integer status;
        private Integer version;
        private String bizType;
        private String bizId;
        private String bizTitle;
        private String bizUrl;
        private String submitterName;
        private String submitTime;
        private String finishTime;
        private String currentNodes;
    }

    /** 办理入参（approve/reject 请求体；opinion 可空，拒绝侧服务层强制必填） */
    @Data
    public static class HandleBody {
        private String opinion;
        /** 多出口节点办理时所选出口名（单出口可省） */
        private String edgeName;
    }
}