package com.cmvr.edge.client.service;

import cmvr.api.ArmCommand;
import cmvr.api.Common;
import com.cmvr.edge.client.model.EdgeCommonVO;

/**
 * 边缘系统机械臂服务
 *
 * @author cmvr-iot
 * @since 2026-07-01
 */
public interface EdgeArmService {

    /**
     * 关闭力矩（命令码：torqueOff）
     * 关闭机械臂的力矩控制，使机械臂进入自由拖动模式
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 操作结果
     */
    Common.CommandHeader.Feedback torqueOff(EdgeCommonVO edgeCommonVO);

    /**
     * 开启力矩（命令码：torqueOn）
     * 开启机械臂的力矩控制，使机械臂进入受控状态
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 操作结果
     */
    Common.CommandHeader.Feedback torqueOn(EdgeCommonVO edgeCommonVO);

    /**
     * 清除机械臂故障状态。
     *
     * @param edgeCommonVO 边缘设备通用参数，包含 terminalId 和 deviceId
     * @return 机器人终端返回的通用反馈
     */
    Common.CommandHeader.Feedback clearFault(EdgeCommonVO edgeCommonVO);

    /**
     * 关节空间运动（命令码：moveJ）
     * 控制机械臂通过关节空间插值运动到目标关节位置
     *
     * @param edgeCommonVO 边缘通用参数
     * @param target 目标关节位置数组（6个关节角度，单位：弧度）
     * @param velocity 运动速度（单位：m/s，可选）
     * @param acceleration 加速度（单位：m/s²，可选）
     * @param blendRadius 融合半径（单位：m，可选）
     * @param jointVelocityLimits 关节速度限制数组（可选）
     * @param asynchronous 是否异步执行（可选）
     * @return 运动结果
     */
    ArmCommand.MoveJ.Response moveJ(EdgeCommonVO edgeCommonVO, double[] target, Double velocity, 
                                     Double acceleration, Double blendRadius, 
                                     double[] jointVelocityLimits, Boolean asynchronous);

    /**
     * 笛卡尔空间直线运动（命令码：moveL）
     * 控制机械臂在笛卡尔空间中沿直线运动到目标位姿
     *
     * @param edgeCommonVO 边缘通用参数
     * @param x X轴坐标（单位：米）
     * @param y Y轴坐标（单位：米）
     * @param z Z轴坐标（单位：米）
     * @param rx RX旋转角度（单位：弧度）
     * @param ry RY旋转角度（单位：弧度）
     * @param rz RZ旋转角度（单位：弧度）
     * @param frame 坐标系类型（BASE/TOOL/WORLD/USER）
     * @param velocity 运动速度（单位：m/s，可选）
     * @param acceleration 加速度（单位：m/s²，可选）
     * @param blendRadius 融合半径（单位：m，可选）
     * @return 运动结果
     */
    ArmCommand.MoveL.Response moveL(EdgeCommonVO edgeCommonVO, double x, double y, double z,
                                     double rx, double ry, double rz, String frame,
                                     Double velocity, Double acceleration, Double blendRadius);

    /**
     * 关节速度控制（命令码：speedJ）
     * 控制机械臂各关节以指定速度运动
     *
     * @param edgeCommonVO 边缘通用参数
     * @param velocities 关节速度数组（6个关节速度，单位：rad/s）
     * @param acceleration 加速度（单位：rad/s²，可选）
     * @param duration 持续时间（单位：秒，可选）
     * @return 控制结果
     */
    ArmCommand.SpeedJ.Response speedJ(EdgeCommonVO edgeCommonVO, double[] velocities, 
                                       Double acceleration, Double duration);

    /**
     * 笛卡尔速度控制（命令码：speedL）
     * 控制机械臂末端以指定笛卡尔速度运动
     *
     * @param edgeCommonVO 边缘通用参数
     * @param vx X轴速度（单位：m/s）
     * @param vy Y轴速度（单位：m/s）
     * @param vz Z轴速度（单位：m/s）
     * @param wx RX角速度（单位：rad/s）
     * @param wy RY角速度（单位：rad/s）
     * @param wz RZ角速度（单位：rad/s）
     * @param frame 坐标系类型（BASE/TOOL/WORLD/USER）
     * @param acceleration 加速度（单位：m/s²，可选）
     * @param duration 持续时间（单位：秒，可选）
     * @return 控制结果
     */
    ArmCommand.SpeedL.Response speedL(EdgeCommonVO edgeCommonVO, double vx, double vy, double vz,
                                       double wx, double wy, double wz, String frame,
                                       Double acceleration, Double duration);

    /**
     * 伺服关节控制（命令码：servoJ）
     * 实时控制机械臂关节位置，用于高频控制场景
     *
     * @param edgeCommonVO 边缘通用参数
     * @param target 目标关节位置数组（6个关节角度，单位：弧度）
     * @return 控制结果
     */
    ArmCommand.ServoJ.Response servoJ(EdgeCommonVO edgeCommonVO, double[] target);

    /**
     * 停止运动（命令码：stopMotion）
     * 立即停止机械臂当前正在执行的所有运动
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 停止结果
     */
    Common.CommandHeader.Feedback stopMotion(EdgeCommonVO edgeCommonVO);

    /**
     * 获取关节状态（命令码：getJointState）
     * 获取机械臂当前各关节的位置、速度和力矩信息
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 关节状态信息
     */
    ArmCommand.JointResponse getJointState(EdgeCommonVO edgeCommonVO);

    /**
     * 获取末端位姿（命令码：getPose）
     * 获取机械臂末端执行器相对于基座的笛卡尔位姿
     *
     * @param edgeCommonVO 边缘通用参数
     * @param baseLink 基座连杆名称（可选，默认为base）
     * @param eeLink 末端执行器连杆名称（可选，默认为tool0）
     * @return 末端位姿信息
     */
    ArmCommand.GetPose.Response getPose(EdgeCommonVO edgeCommonVO, String baseLink, String eeLink);

    /**
     * 标定零点（命令码：calibrateZeroQ）
     * 对指定关节进行零点标定
     *
     * @param edgeCommonVO 边缘通用参数
     * @param jointName 关节名称（可选，为空则标定所有关节）
     * @return 标定结果
     */
    ArmCommand.CalibrateZeroQ.Response calibrateZeroQ(EdgeCommonVO edgeCommonVO, String jointName);

    /**
     * 获取位姿矩阵（命令码：getPoseMatrix）
     * 获取机械臂末端执行器相对于基座的4x4变换矩阵
     *
     * @param edgeCommonVO 边缘通用参数
     * @param baseLink 基座连杆名称（可选，默认为base）
     * @param eeLink 末端执行器连杆名称（可选，默认为tool0）
     * @return 位姿矩阵信息
     */
    ArmCommand.GetPoseMatrix.Response getPoseMatrix(EdgeCommonVO edgeCommonVO, String baseLink, String eeLink);

    /**
     * 计算正向运动学（命令码：computeForwardKinematics）
     * 根据给定的关节位置计算末端执行器的位姿矩阵
     *
     * @param edgeCommonVO 边缘通用参数
     * @param joints 关节位置数组（6个关节角度，单位：弧度）
     * @param baseLink 基座连杆名称（可选，默认为base）
     * @param eeLink 末端执行器连杆名称（可选，默认为tool0）
     * @return 正向运动学计算结果（4x4变换矩阵）
     */
    ArmCommand.ComputeForwardKinematics.Response computeForwardKinematics(EdgeCommonVO edgeCommonVO, 
                                                                            double[] joints, 
                                                                            String baseLink, 
                                                                            String eeLink);
}
