package com.ruoyi.jarvis.service;

import com.alibaba.fastjson2.JSONObject;
import com.ruoyi.jarvis.domain.JDOrder;

import java.util.List;

/**
 * 腾讯文档服务接口
 * 
 * @author system
 */
public interface ITencentDocService {
    
    /**
     * 获取授权URL
     * 
     * @return 授权URL
     */
    String getAuthUrl();
    
    /**
     * 通过授权码获取访问令牌
     * 
     * @param code 授权码
     * @return 访问令牌信息
     */
    JSONObject getAccessTokenByCode(String code);
    
    /**
     * 刷新访问令牌
     * 
     * @param refreshToken 刷新令牌
     * @return 新的访问令牌信息
     */
    JSONObject refreshAccessToken(String refreshToken);
    
    /**
     * 将物流信息上传到腾讯文档表格
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param sheetId 工作表ID
     * @param orders 订单列表
     * @return 上传结果
     */
    JSONObject uploadLogisticsToSheet(String accessToken, String fileId, String sheetId, List<JDOrder> orders);
    
    /**
     * 将单个订单的物流信息追加到表格
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param sheetId 工作表ID
     * @param order 订单信息
     * @return 上传结果
     */
    JSONObject appendLogisticsToSheet(String accessToken, String fileId, String sheetId, Integer startRow, JDOrder order);
    
    /**
     * 读取表格数据
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param sheetId 工作表ID
     * @param range 范围
     * @return 表格数据
     */
    JSONObject readSheetData(String accessToken, String fileId, String sheetId, String range);
    
    /**
     * 写入表格数据
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param sheetId 工作表ID
     * @param range 范围，例如 "A1"
     * @param values 要写入的数据，二维数组格式
     * @return 写入结果
     */
    JSONObject writeSheetData(String accessToken, String fileId, String sheetId, String range, Object values);
    
    /**
     * 获取文件信息
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @return 文件信息
     */
    JSONObject getFileInfo(String accessToken, String fileId);
    
    /**
     * 获取工作表列表
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @return 工作表列表
     */
    JSONObject getSheetList(String accessToken, String fileId);

    /**
     * 获取指定工作表的行数（优先返回 rowCount-实际有数据的行数，其次 rowTotal）
     * 用于替代 Redis 上次记录的行数，决定批量填充的操作范围
     *
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param sheetId 工作表ID
     * @return rowCount/rowTotal，未找到或解析失败返回 0
     */
    int getSheetRowTotal(String accessToken, String fileId, String sheetId);
    
    /**
     * 获取用户信息
     * 
     * @param accessToken 访问令牌
     * @return 用户信息
     */
    JSONObject getUserInfo(String accessToken);
    
    /**
     * 批量更新表格（batchUpdate API）
     * 
     * @param accessToken 访问令牌
     * @param fileId 文件ID
     * @param requestBody batchUpdate 请求体，包含 requests 数组
     * @return 更新结果
     */
    JSONObject batchUpdate(String accessToken, String fileId, JSONObject requestBody);
}