package jnpf.bizcommon.onlyoffice.service;

import jnpf.bizcommon.onlyoffice.entity.OnlyOfficeCallbackParam;
import jnpf.bizcommon.onlyoffice.entity.OnlyOfficeConfigParam;

import java.util.Map;

/**
 * OnlyOffice 文档编辑能力。
 * 方案见 {@code tasks/onlyoffice-integration-plan.md}。
 */
public interface OnlyOfficeService {

    /**
     * 签发编辑器 config（含 HS256 JWT），前端拿去喂 {@code new DocsAPI.DocEditor(id, config)}。
     *
     * <p>过程中会落库/更新编辑会话，并做编辑锁判定——已有他人在编辑时降级为只读，
     * 因为 DS 的默认行为是同 docKey 自动协同，而协同不在本期范围。
     *
     * @param param 文件与业务上下文
     * @return 可直接序列化给前端的 config
     */
    Map<String, Object> buildEditorConfig(OnlyOfficeConfigParam param);

    /**
     * 查询文件最近一次由 Document Server 成功写回的状态。
     *
     * @param fileId jnpf-file 文件标识
     * @return version 与 lastSaveTime（毫秒时间戳）
     */
    Map<String, Object> getSaveStatus(String fileId);

    /**
     * 处理 DS 的保存回调。
     *
     * <p>该端点在网关白名单内（平台补丁 #9），匿名可达，{@code authorization} 的验签
     * 是唯一的安全边界，验不过必须抛异常而不是降级放过。
     *
     * @param param         回调体
     * @param authorization Authorization 头原文（形如 {@code Bearer xxx}）
     */
    void handleCallback(OnlyOfficeCallbackParam param, String authorization);
}