FranklinWH-Toolbox/service/agentmcp/tools/faultrecord.go

package tools

import (
	"context"
	"time"

	"github.com/mark3labs/mcp-go/mcp"

	"fwh-toolbox-server/agentmcp/kit"
	"fwh-toolbox-server/repositories"
)

// deviceTypeDesc 故障录波设备类型说明
const deviceTypeDesc = "deviceType：0 aPower-PE、1 aGate/MCA、2 aPower-MPPT、3 aHub"

// ---- cloud_fault_record_list ----

type faultRecordListArgs struct {
	SN    string `json:"sn" jsonschema:"站点 SN（aGate 序列号）"`
	From  string `json:"from" jsonschema:"开始时间，yyyy-MM-dd HH:mm:ss"`
	To    string `json:"to" jsonschema:"结束时间，同上；与开始时间相差不超过 92 天"`
	Limit int    `json:"limit,omitempty" jsonschema:"最多返回条数，1～300，默认 100"`
}

var CloudFaultRecordList = kit.Def[faultRecordListArgs]{
	Name:  "cloud_fault_record_list",
	Title: "查询云平台故障录波记录",
	Description: "查询站点在一段时间内由 FWH 云平台记录的故障录波日志（云平台通道，与 ToolBox 直连设备的 fault_record_* 是两套数据）。返回字段：id（录波记录 ID，用于 cloud_fault_record_detail）、" + deviceTypeDesc +
		"、apowerId / powerlinkId（对应设备 SN）、gatewayId、triggerType（1 手动、2 自动）、触发时间与状态等（以实际返回为准）。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a faultRecordListArgs) (*mcp.CallToolResult, error) {
		sn, err := kit.Required("sn", a.SN)
		if err != nil {
			return kit.Fail(err), nil
		}
		from, to, err := kit.ParseRange(a.From, a.To, 92*24*time.Hour)
		if err != nil {
			return kit.Fail(err), nil
		}
		items, err := repositories.QueryFaultRecordList(sn, from.Format(kit.DateTimeLayout), to.Format(kit.DateTimeLayout))
		if err != nil {
			return kit.Upstream("FWH 平台故障录波接口", err), nil
		}
		return kit.List(items, -1, kit.Limit(a.Limit, 100, 300), "结果已截断，请缩短时间范围"), nil
	},
}

// ---- cloud_fault_record_detail ----

type faultRecordDetailArgs struct {
	FaultID int64 `json:"faultId" jsonschema:"故障录波记录 ID（cloud_fault_record_list 返回的 id）"`
}

var CloudFaultRecordDetail = kit.Def[faultRecordDetailArgs]{
	Name:  "cloud_fault_record_detail",
	Title: "查询云平台故障录波子记录",
	Description: "查询一条故障录波记录下的子记录（各设备的录波文件）。返回字段：id、faultId、" + deviceTypeDesc +
		"、apowerId、gatewayId、fileName（不含后缀）、文件状态与时间等（以实际返回为准）。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a faultRecordDetailArgs) (*mcp.CallToolResult, error) {
		if a.FaultID <= 0 {
			return kit.Failf("参数 faultId 必填且为正整数"), nil
		}
		items, err := repositories.QueryFaultRecordSubList(a.FaultID)
		if err != nil {
			return kit.Upstream("FWH 平台故障录波接口", err), nil
		}
		return kit.List(items, -1, 200, ""), nil
	},
}

// ---- cloud_fault_record_callable ----

type faultRecordCallableArgs struct {
	SN         string `json:"sn" jsonschema:"设备 SN（aGate / aPower / MPPT / aHub）"`
	DeviceType *int   `json:"deviceType,omitempty" jsonschema:"设备类型：0 aPower、1 aGate（默认）、2 MPPT、3 aHub"`
}

var CloudFaultRecordCallable = kit.Def[faultRecordCallableArgs]{
	Name:  "cloud_fault_record_callable",
	Title: "查询云平台可召唤的故障录波",
	Description: "查询设备上可召唤（尚未上传）的自动故障录波数据列表（FWH 平台）。" +
		"返回字段：idx / indexNumber（数据序号）、failureTime（故障时间）、paramVersionNumber（故障信息）、triggerSourceCode（故障码）。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a faultRecordCallableArgs) (*mcp.CallToolResult, error) {
		sn, err := kit.Required("sn", a.SN)
		if err != nil {
			return kit.Fail(err), nil
		}
		devType := 1
		if a.DeviceType != nil {
			devType = *a.DeviceType
		}
		if devType < 0 || devType > 3 {
			return kit.Failf("参数 deviceType 取值 0～3"), nil
		}
		items, err := repositories.QueryFaultRecordCallableList(devType, sn)
		if err != nil {
			return kit.Upstream("FWH 平台故障录波接口", err), nil
		}
		if len(items) == 0 {
			return kit.Empty("该设备没有可召唤的故障录波数据。"), nil
		}
		return kit.List(items, -1, 200, ""), nil
	},
}

// ---- cloud_fault_record_call_history ----

type faultRecordCallHistoryArgs struct {
	Page int `json:"page,omitempty" jsonschema:"页码，默认 1"`
	Size int `json:"size,omitempty" jsonschema:"每页条数，1～100，默认 20"`
}

var CloudFaultRecordCallHistory = kit.Def[faultRecordCallHistoryArgs]{
	Name:  "cloud_fault_record_call_history",
	Title: "查询云平台故障录波召唤记录",
	Description: "分页查询 FWH 平台上全部站点的故障录波召唤记录（手动召唤的历史），按时间倒序。" +
		"返回字段与 cloud_fault_record_list 相同。查看单个站点的录波请用 cloud_fault_record_list。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a faultRecordCallHistoryArgs) (*mcp.CallToolResult, error) {
		size := kit.Limit(a.Size, 20, 100)
		items, err := repositories.QueryFaultRecordCallRecordPage(kit.Page(a.Page), size)
		if err != nil {
			return kit.Upstream("FWH 平台故障录波接口", err), nil
		}
		return kit.List(items, -1, size, "可用 page 翻页"), nil
	},
}