package com.yunhai.svchall.service;

import com.yunhai.svchall.model.svc.SvcModels;

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

/**
 * 流程中心客户端接缝（V2.0 Part B.4）：Notice 同款托管模式的出站面。
 * 默认实现经共享 IDHttp（出站自动签名，yh.app-auth 身份）调 flow-center /oapi/flow/**。
 * enabled=false（本地未部署 flow-center）时所有方法抛业务异常，消费方按需降级
 * （事项不绑流程=纯指南，不经过本接口）。
 *
 * <p>纪律（2026-09-16 治理）：<b>用户面动作一律由本接缝中转</b>，前端不得直连
 * flow-center——浏览器直调外部应用的 /api/flow/** 依赖跨应用 CAS 票据与 CORS，既是
 * 票据外溢面，也让"谁能撤"落在前端。前端只认 /api/** 同源接口（CAS 保护）。
 */
public interface FlowClient {

    /** 流程中心是否已接入（未接入时管理端选择器降级提示，事项绑 flow_guid 校验跳过） */
    boolean enabled();

    /** 已发布流程列表（事项编辑页"办理流程"选择器数据源） */
    List<SvcModels.FlowSummaryVo> listFlows(Long schId);

    /** 流程详情回显（节点与办理科室摘要） */
    SvcModels.FlowSummaryVo getFlow(Long schId, String flowGuid);

    /**
     * 代发起（POST /oapi/flow/apply，V2.0 B.4#3）。
     *
     * @return {instanceId, duplicated}（duplicated=true 表示命中 uk 幂等返回既有办件）
     */
    ApplyResult apply(Long schId, String flowGuid, String bizType, String bizId, String bizTitle,
                      String bizUrl, String bizSnapshot, Integer submitterId, String submitterName,
                      String formDataJson);

    /** 按业务键查办件（对账兜底；返回 {instanceId,status,version,nodeSummary,traceJson}，查不到返回 null） */
    Map<String, Object> getInstanceByBiz(Long schId, String bizType, String bizId);

    /** 注册回调（POST /oapi/flow/callback/reg）→ 下发 secret */
    String registerCallback(Long schId, String flowGuid, String callbackUrl, String eventTypes);

    /**
     * 撤回（提交人本人；仅审批中且尚无任务被办理）。
     * submitterId 由调用方按其办件归属传入，对端与办件提交人复核——应用签名不替代身份。
     */
    void withdraw(Long schId, Long instanceId, Integer submitterId);

    /**
     * 办件进度（结构化轨迹，时间线数据源）：instanceId 优先，否则按 bizType+bizId 定位。
     * 对端只校验 schId，<b>调用方必须先做可见性守卫</b>（本人/管理员/办理人）。
     */
    SvcModels.FlowProgressVo progress(Long schId, Long instanceId, String bizType, String bizId);

    /**
     * 流程示意图（PNG 字节）：本接缝内完成"取 token → 取图"两步，浏览器只拿同源
     * <code>/api/**</code> 图片流——免签 token 不落前端，前端也不需要知道 flow-center 地址。
     *
     * @param instanceId 办件口径（带运行时状态）与 flowGuid 定义口径二选一
     */
    byte[] diagramImage(Long schId, Long instanceId, String flowGuid, String mode);

    /** 代发起结果 */
    class ApplyResult {
        private final Long instanceId;
        private final boolean duplicated;

        public ApplyResult(Long instanceId, boolean duplicated) {
            this.instanceId = instanceId;
            this.duplicated = duplicated;
        }

        public Long getInstanceId() {
            return instanceId;
        }

        public boolean isDuplicated() {
            return duplicated;
        }
    }
}