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

package tools

// 故障录波（ToolBox 直连设备，经 MQTT 与设备交互；与云平台的 cloud_fault_record_* 是两套数据）。
// 操作由主服务的执行器收发 MQTT，状态保存在 Mongo（FaultRecordOperations）；本服务只提交操作、读取状态与文件。
// 设备上的操作以长任务（kit.TaskDef）执行：任务 id 携带操作 id，状态直接取自操作记录。

import (
	"context"
	"errors"
	"fmt"
	"strings"
	"time"

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

	"fwh-toolbox-server/agentmcp/kit"
	"fwh-toolbox-server/domain"
	"fwh-toolbox-server/dto"
	faultRecordFile "fwh-toolbox-server/function/FaultRecordFile"
	proto "fwh-toolbox-server/function/FaultRecordProtocol"
	mongoRepo "fwh-toolbox-server/repositories/mongo"
	"fwh-toolbox-server/services"
)

const (
	frEnvDesc        = "服务器环境：prod（生产，默认）/ test（测试）"
	frDeviceKindDesc = "设备：aGate（默认）、aPowerPE、aPowerMPPT、aHub；站点有哪些设备、是否支持见 fault_record_devices"
	frDeviceSnDesc   = "设备 SN；aGate 可不填（即站点 SN），其他设备必填（见 fault_record_devices）"
	// frSyncWait 普通调用（非任务方式）时等待设备回复的最长时间，低于单次调用 60 秒超时
	frSyncWait = 45 * time.Second
)

var frDeviceProps = map[string]map[string]any{
	"env":        {"enum": []string{"prod", "test"}},
	"deviceKind": {"enum": []string{proto.DeviceKindAGate, proto.DeviceKindAPowerPE, proto.DeviceKindAPowerMPPT, proto.DeviceKindAHub}},
}

// frStageMessages 进行中各阶段的说明（显示在平台的后台调用栏）
var frStageMessages = map[domain.FaultRecordOpStatus]string{
	domain.FaultRecordStatusPending:    "等待发送到设备",
	domain.FaultRecordStatusSent:       "已发送，等待设备确认",
	domain.FaultRecordStatusAccepted:   "设备已接受，等待结果",
	domain.FaultRecordStatusReady:      "设备已准备录波文件，等待上传",
	domain.FaultRecordStatusUploading:  "设备正在上传录波文件",
	domain.FaultRecordStatusUploaded:   "上传完成，正在下载",
	domain.FaultRecordStatusDownloaded: "文件已保存，正在解析",
}

// frFailMessages 失败终态的说明（写给模型）
var frFailMessages = map[domain.FaultRecordOpStatus]string{
	domain.FaultRecordStatusBusy:           "设备正在处理其他命令，稍后重试",
	domain.FaultRecordStatusRejected:       "设备拒绝了请求",
	domain.FaultRecordStatusTimeout:        "等待设备超时（设备可能离线或无响应）",
	domain.FaultRecordStatusUploadFailed:   "设备上传录波文件失败",
	domain.FaultRecordStatusDownloadFailed: "录波文件下载失败，可以用 fault_record_retry_download 重试下载",
	domain.FaultRecordStatusParseFailed:    "录波文件已保存但解析失败，可以用 fault_record_export 导出原始文件",
	domain.FaultRecordStatusInterrupted:    "服务重启时操作中断",
	domain.FaultRecordStatusGatewayLocked:  "该网关已有其他录波操作在进行，等它结束后再试",
	domain.FaultRecordStatusError:          "操作出错（如主服务 MQTT 不可用）",
}

type frDeviceArgs struct {
	SN         string `json:"sn" jsonschema:"站点 SN（aGate 序列号）"`
	Env        string `json:"env,omitempty" jsonschema:"服务器环境：prod（生产，默认）/ test（测试）"`
	DeviceKind string `json:"deviceKind,omitempty" jsonschema:"设备：aGate（默认）、aPowerPE、aPowerMPPT、aHub；站点有哪些设备、是否支持见 fault_record_devices"`
	DeviceSn   string `json:"deviceSn,omitempty" jsonschema:"设备 SN；aGate 可不填（即站点 SN），其他设备必填（见 fault_record_devices）"`
}

// frRequest 由设备参数构造操作请求
func frRequest(a frDeviceArgs, kind domain.FaultRecordOpKind) (dto.FaultRecordCreateOpReq, error) {
	sn, err := kit.Required("sn", a.SN)
	if err != nil {
		return dto.FaultRecordCreateOpReq{}, err
	}
	env, err := kit.Enum("env", a.Env, "prod", "prod", "test")
	if err != nil {
		return dto.FaultRecordCreateOpReq{}, err
	}
	devKind := a.DeviceKind
	if devKind == "" {
		devKind = proto.DeviceKindAGate
	}
	devType, ok := proto.DeviceKindProtocolType[devKind]
	if !ok || devType == "" {
		return dto.FaultRecordCreateOpReq{}, fmt.Errorf("不支持的设备：%s（可选 aGate、aPowerPE、aPowerMPPT、aHub）", devKind)
	}
	devSn := strings.TrimSpace(a.DeviceSn)
	if devKind != proto.DeviceKindAGate && devSn == "" {
		return dto.FaultRecordCreateOpReq{}, fmt.Errorf("%s 需要 deviceSn，可用 fault_record_devices 查看", devKind)
	}
	return dto.FaultRecordCreateOpReq{Env: env, GatewaySn: sn, DeviceType: devType, DeviceSn: devSn, Kind: string(kind)}, nil
}

// frSubmit 提交操作（由主服务执行），返回操作 id
func frSubmit(ctx context.Context, req dto.FaultRecordCreateOpReq) (string, *mcp.CallToolResult) {
	id, err := services.SubmitFaultRecordOperation(ctx, req, ServiceAccount)
	if errors.Is(err, services.ErrFaultRecordInvalid) {
		return "", kit.Fail(err)
	}
	if err != nil {
		return "", kit.Upstream("ToolBox 故障录波", err)
	}
	return id, nil
}

// frOpView 写给模型的操作结果：逐项结果，不含原始报文
func frOpView(d *dto.FaultRecordOpDetail) map[string]any {
	out := map[string]any{
		"operationId": d.ID,
		"kind":        d.Kind,
		"env":         d.Env,
		"gatewaySn":   d.GatewaySn,
		"deviceType":  d.DeviceType,
		"deviceSn":    d.DeviceSn,
		"request":     d.Summary,
		"status":      d.Status,
		"operator":    d.Operator,
		"createdAt":   fmtBeijing(d.CreatedAt),
	}
	if d.Error != "" {
		out["error"] = d.Error
	}
	if d.TimeoutStage != "" {
		out["timeoutStage"] = d.TimeoutStage
	}
	if d.ReplyDesc != "" {
		out["reply"] = d.ReplyDesc
	}
	if len(d.Items) > 0 {
		items := make([]map[string]any, 0, len(d.Items))
		for _, it := range d.Items {
			m := map[string]any{"name": it.Name, "ok": it.Ok, "result": it.ResultDesc}
			if it.Code != 0 {
				m["code"] = it.Code
			}
			if it.Id != 0 {
				m["id"] = it.Id
			}
			if it.SetVal != "" {
				m["setVal"] = it.SetVal
			}
			if it.Decoded != nil {
				m["value"] = it.Decoded
			} else if it.Raw != "" {
				m["raw"] = it.Raw
			}
			if it.DecodeErr != "" {
				m["decodeError"] = it.DecodeErr
			}
			items = append(items, m)
		}
		out["items"] = items
	}
	if d.HasFile {
		out["hasFile"] = true
		out["next"] = "录波数据：fault_record_data 查看故障信息与波形概要，fault_record_export 导出 CSV"
	}
	return out
}

// frTaskState 把操作记录翻译为任务状态
func frTaskState(d *dto.FaultRecordOpDetail) kit.TaskState {
	st := kit.TaskState{CreatedAt: d.CreatedAt}
	status := domain.FaultRecordOpStatus(d.Status)
	switch {
	case !status.Terminal():
		st.Status = mcp.TaskStatusWorking
		st.Message = frStageMessages[status]
		if st.Message == "" {
			st.Message = d.Status
		}
	case status == domain.FaultRecordStatusDone || status == domain.FaultRecordStatusItemFailed:
		// item_failed：设备已回复，但部分子项失败，逐项结果中有说明
		st.Status, st.Message = mcp.TaskStatusCompleted, "完成"
		if status == domain.FaultRecordStatusItemFailed {
			st.Message = "完成，部分子项失败"
		}
		st.Result = kit.Object(frOpView(d))
	case status == domain.FaultRecordStatusCancelled:
		st.Status, st.Message = mcp.TaskStatusCancelled, "已取消"
		st.Result = kit.Failf("故障录波操作已取消（操作 id %s）。", d.ID)
	default:
		st.Status = mcp.TaskStatusFailed
		reason := frFailMessages[status]
		if reason == "" {
			reason = d.Status
		}
		st.Message = reason
		view := frOpView(d)
		view["reason"] = reason
		st.Result = kit.Object(view)
		st.Result.IsError = true
	}
	return st
}

// frStatus 读取操作并翻译为任务状态（kit.TaskDef.Status）
func frStatus(ctx context.Context, ref kit.TaskRef) (kit.TaskState, error) {
	d, err := services.GetFaultRecordOperation(ctx, ref.Key)
	if errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) || errors.Is(err, services.ErrFaultRecordInvalid) {
		return kit.TaskState{}, kit.ErrTaskNotFound
	}
	if err != nil {
		return kit.TaskState{}, err
	}
	return frTaskState(d), nil
}

// frCancel 请求取消操作（执行器 1 秒内响应）；已结束的操作无需取消
func frCancel(ctx context.Context, ref kit.TaskRef) error {
	err := services.CancelFaultRecordOperation(ctx, ref.Key)
	if errors.Is(err, services.ErrFaultRecordInvalid) {
		return nil
	}
	return err
}

// frWait 普通调用时等待操作结束（最多 frSyncWait），未结束时返回进度与操作 id
func frWait(ctx context.Context, id string) *mcp.CallToolResult {
	deadline := time.Now().Add(frSyncWait)
	for {
		d, err := services.GetFaultRecordOperation(ctx, id)
		if err != nil {
			return kit.Upstream("ToolBox 故障录波", err)
		}
		st := frTaskState(d)
		if st.Status.IsTerminal() {
			return st.Result
		}
		if time.Now().After(deadline) {
			return kit.Object(map[string]any{"operationId": id, "status": d.Status, "message": st.Message + "；设备还没有回复完，稍后用 fault_record_operation_get 查看结果"})
		}
		select {
		case <-ctx.Done():
			return kit.Object(map[string]any{"operationId": id, "status": d.Status, "message": "等待中断，稍后用 fault_record_operation_get 查看结果"})
		case <-time.After(time.Second):
		}
	}
}

// frSubmitted 普通调用提交耗时较长的操作后立即返回
func frSubmitted(id, what string) *mcp.CallToolResult {
	return kit.Object(map[string]any{"operationId": id, "status": "pending", "message": "已提交" + what + "，由主服务与设备交互；用 fault_record_operation_get 查看进度与结果"})
}

// ---- fault_record_devices ----

type frDevicesArgs struct {
	SN  string `json:"sn" jsonschema:"站点 SN（aGate 序列号）"`
	Env string `json:"env,omitempty" jsonschema:"服务器环境：prod（生产，默认）/ test（测试）"`
}

var FaultRecordDevices = kit.Def[frDevicesArgs]{
	Name:  "fault_record_devices",
	Title: "查询站点可做故障录波的设备",
	Description: "列出站点中可以做故障录波操作的设备：aGate、各 aPower-PE、带 MPPT 的 aPower-MPPT、各 aHub，以及站点是否在线。" +
		"返回 devices：kind（设备种类，作为其他 fault_record_* 工具的 deviceKind）、sn（作为 deviceSn）、model、supported（是否可操作）、note（不可操作的原因）。" +
		"对设备做读取、召唤、设置前先用本工具确认设备与 SN。",
	ReadOnly:   true,
	Properties: map[string]map[string]any{"env": {"enum": []string{"prod", "test"}}},
	Handler: func(ctx context.Context, a frDevicesArgs) (*mcp.CallToolResult, error) {
		sn, err := kit.Required("sn", a.SN)
		if err != nil {
			return kit.Fail(err), nil
		}
		env, err := kit.Enum("env", a.Env, "prod", "prod", "test")
		if err != nil {
			return kit.Fail(err), nil
		}
		d, err := services.GetFaultRecordSiteDevices(env, sn)
		if errors.Is(err, services.ErrFaultRecordInvalid) {
			return kit.Fail(err), nil
		}
		if err != nil {
			return kit.Upstream("FWH 平台设备信息接口", err), nil
		}
		return kit.Object(d), nil
	},
}

// ---- fault_record_device_info ----

type frDeviceInfoArgs struct {
	frDeviceArgs
	Codes []int `json:"codes,omitempty" jsonschema:"要读取的信息类别：1 故障总体信息（含快照、可配通道当前值）、2 录波功能基本信息（含采样频率）、3 故障录波总目录（设备上已有的录波记录序号，召唤录波前先读）；默认全部"`
}

var FaultRecordDeviceInfo = kit.TaskDef[frDeviceInfoArgs]{
	Def: kit.Def[frDeviceInfoArgs]{
		Name:  "fault_record_device_info",
		Title: "读取设备故障录波信息",
		Description: "通过 MQTT 从设备实时读取故障录波相关信息（不修改设备）：故障总体信息、录波功能基本信息、故障录波总目录。" +
			"召唤录波（fault_record_fetch）前用类别 3 查看设备上有哪些录波记录序号。设备通常几秒到几十秒内回复；" +
			"返回 items（逐项结果，value 为解析后的内容）。设备离线时会超时失败。",
		ReadOnly:   true,
		Properties: mergeProps(frDeviceProps, map[string]map[string]any{"codes": {"items": map[string]any{"type": "integer", "enum": []int{1, 2, 3}}}}),
		Handler: func(ctx context.Context, a frDeviceInfoArgs) (*mcp.CallToolResult, error) {
			id, fail := frStartDeviceInfo(ctx, a)
			if fail != nil {
				return fail, nil
			}
			return frWait(ctx, id), nil
		},
	},
	Poll: 5 * time.Second,
	Start: func(ctx context.Context, a frDeviceInfoArgs) (kit.TaskStart, *mcp.CallToolResult) {
		id, fail := frStartDeviceInfo(ctx, a)
		return kit.TaskStart{Key: id, Flag: "op", Note: "已向设备发送读取请求，设备回复后平台会把结果发给你"}, fail
	},
	Status: frStatus,
	Cancel: frCancel,
}

func frStartDeviceInfo(ctx context.Context, a frDeviceInfoArgs) (string, *mcp.CallToolResult) {
	req, err := frRequest(a.frDeviceArgs, domain.FaultRecordOpDeviceInfo)
	if err != nil {
		return "", kit.Fail(err)
	}
	req.CodeList = a.Codes
	if len(req.CodeList) == 0 {
		req.CodeList = []int{1, 2, 3}
	}
	return frSubmit(ctx, req)
}

// ---- fault_record_param_read ----

type frParamReadArgs struct {
	frDeviceArgs
	Ids []int `json:"ids,omitempty" jsonschema:"要读取的功能码：4 设备时间、7 录波开关；默认全部。采样频率（5）、可配采样通道（6）的当前值在 fault_record_device_info 的类别 2、1 中"`
}

var FaultRecordParamRead = kit.TaskDef[frParamReadArgs]{
	Def: kit.Def[frParamReadArgs]{
		Name:  "fault_record_param_read",
		Title: "读取设备故障录波参数",
		Description: "通过 MQTT 从设备读取故障录波参数的当前值（不修改设备）：设备时间（功能码 4）、录波开关（功能码 7）。" +
			"返回 items（逐项结果，value 为解析后的值）。设备离线时会超时失败。",
		ReadOnly:   true,
		Properties: mergeProps(frDeviceProps, map[string]map[string]any{"ids": {"items": map[string]any{"type": "integer", "enum": []int{4, 7}}}}),
		Handler: func(ctx context.Context, a frParamReadArgs) (*mcp.CallToolResult, error) {
			id, fail := frStartParamRead(ctx, a)
			if fail != nil {
				return fail, nil
			}
			return frWait(ctx, id), nil
		},
	},
	Poll: 5 * time.Second,
	Start: func(ctx context.Context, a frParamReadArgs) (kit.TaskStart, *mcp.CallToolResult) {
		id, fail := frStartParamRead(ctx, a)
		return kit.TaskStart{Key: id, Flag: "op", Note: "已向设备发送读取请求，设备回复后平台会把结果发给你"}, fail
	},
	Status: frStatus,
	Cancel: frCancel,
}

func frStartParamRead(ctx context.Context, a frParamReadArgs) (string, *mcp.CallToolResult) {
	req, err := frRequest(a.frDeviceArgs, domain.FaultRecordOpParamRead)
	if err != nil {
		return "", kit.Fail(err)
	}
	req.IdList = a.Ids
	if len(req.IdList) == 0 {
		req.IdList = []int{4, 7}
	}
	return frSubmit(ctx, req)
}

// ---- fault_record_operations ----

type frOperationsArgs struct {
	SN   string `json:"sn,omitempty" jsonschema:"站点 SN；不填查全部站点"`
	Env  string `json:"env,omitempty" jsonschema:"服务器环境：prod / test；不填查全部"`
	Kind string `json:"kind,omitempty" jsonschema:"操作类型，多个用逗号分隔：device_info（读取信息）、record_fetch（召唤录波）、param_read（读取参数）、param_write（设置参数）"`
	Page int    `json:"page,omitempty" jsonschema:"页码，默认 1"`
	Size int    `json:"size,omitempty" jsonschema:"每页条数，1～100，默认 20"`
}

var FaultRecordOperations = kit.Def[frOperationsArgs]{
	Name:  "fault_record_operations",
	Title: "查询故障录波操作记录",
	Description: "分页查询 ToolBox 对设备做过的故障录波操作（读取信息、召唤录波、读取/设置参数），按时间倒序，包括页面上的操作与 AI 助手的操作。" +
		"返回 total 与 items：id（操作 id，用于 fault_record_operation_get、fault_record_data、fault_record_export）、kind、gatewaySn、deviceSn、summary（请求摘要）、" +
		"status、operator、hasFile（是否有已保存的录波文件）、createdAt。",
	ReadOnly:   true,
	Properties: map[string]map[string]any{"env": {"enum": []string{"prod", "test"}}},
	Handler: func(ctx context.Context, a frOperationsArgs) (*mcp.CallToolResult, error) {
		size := kit.Limit(a.Size, 20, 100)
		page := kit.Page(a.Page)
		res, err := services.ListFaultRecordOperations(ctx, mongoRepo.FaultRecordOpFilter{
			Env: a.Env, GatewaySn: strings.TrimSpace(a.SN), Kind: a.Kind,
		}, int64(page), int64(size))
		if err != nil {
			return kit.Upstream("ToolBox 故障录波", err), nil
		}
		items := make([]map[string]any, 0, len(res.Data))
		for _, s := range res.Data {
			m := map[string]any{
				"id": s.ID, "env": s.Env, "kind": s.Kind, "gatewaySn": s.GatewaySn, "deviceType": s.DeviceType, "deviceSn": s.DeviceSn,
				"summary": s.Summary, "status": s.Status, "operator": s.Operator, "hasFile": s.HasFile, "createdAt": fmtBeijing(s.CreatedAt),
			}
			if s.Error != "" {
				m["error"] = s.Error
			}
			items = append(items, m)
		}
		return kit.List(items, int(res.Total), size, "用 page 翻页，或用 sn、kind 缩小范围"), nil
	},
}

// ---- fault_record_operation_get ----

type frOperationGetArgs struct {
	ID string `json:"id" jsonschema:"操作 id（fault_record_operations 或各操作工具返回的 operationId）"`
}

var FaultRecordOperationGet = kit.Def[frOperationGetArgs]{
	Name:  "fault_record_operation_get",
	Title: "查询故障录波操作结果",
	Description: "查询一次故障录波操作的状态与逐项结果（设备回复的解析内容，不含原始报文）。" +
		"status 为 done 表示成功、item_failed 表示部分子项失败，其他结束状态见 error。召唤录波成功后 hasFile=true，可用 fault_record_data、fault_record_export 查看数据。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a frOperationGetArgs) (*mcp.CallToolResult, error) {
		d, err := services.GetFaultRecordOperation(ctx, strings.TrimSpace(a.ID))
		if errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) || errors.Is(err, services.ErrFaultRecordInvalid) {
			return kit.Failf("没有找到操作 %s，可以用 fault_record_operations 查看操作记录", a.ID), nil
		}
		if err != nil {
			return kit.Upstream("ToolBox 故障录波", err), nil
		}
		view := frOpView(d)
		if st := frTaskState(d); !st.Status.IsTerminal() {
			view["progress"] = st.Message
		}
		return kit.Object(view), nil
	},
}

// ---- fault_record_data ----

var FaultRecordData = kit.Def[frOperationGetArgs]{
	Name:  "fault_record_data",
	Title: "查看故障录波数据概要",
	Description: "解析一次召唤录波（record_fetch）保存的录波文件，返回每条记录的故障信息与波形概要：" +
		"failure（故障时间、触发源、软件版本、快照通道等）、waveform（采样点数、触发前点数、采样频率，以及每个通道的 min、max 与触发点的值）。" +
		"不含逐点采样值；需要逐点分析时用 fault_record_export 导出 CSV。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a frOperationGetArgs) (*mcp.CallToolResult, error) {
		v, err := services.GetFaultRecordRecord(ctx, strings.TrimSpace(a.ID))
		if errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) || errors.Is(err, services.ErrFaultRecordInvalid) {
			return kit.Fail(err), nil
		}
		if err != nil {
			return kit.Upstream("ToolBox 故障录波文件", err), nil
		}
		records := make([]map[string]any, 0, len(v.Records))
		for _, r := range v.Records {
			records = append(records, map[string]any{
				"batch": r.Batch, "sn": r.Sn, "recordIndex": r.RecordIndex,
				"failure": r.Failure, "waveform": waveformSummary(r.Waveform),
			})
		}
		return kit.Object(map[string]any{"operationId": v.OperationID, "records": records}), nil
	},
}

// waveformSummary 波形概要：通道统计，不含逐点数据
func waveformSummary(w faultRecordFile.Waveform) map[string]any {
	channels := make([]map[string]any, 0, len(w.Channels))
	for _, ch := range w.Channels {
		c := map[string]any{"channel": fmt.Sprintf("ch%d 0x%04X", ch.Number, ch.Meaning)}
		if ch.Configurable != nil {
			c["configurable"] = ch.Configurable.TypeName
		}
		if len(ch.Values) > 0 {
			lo, hi := ch.Values[0], ch.Values[0]
			for _, x := range ch.Values {
				lo, hi = min(lo, x), max(hi, x)
			}
			c["min"], c["max"] = lo, hi
			if w.PrePoints >= 0 && w.PrePoints < len(ch.Values) {
				c["atTrigger"] = ch.Values[w.PrePoints]
			}
		}
		channels = append(channels, c)
	}
	return map[string]any{"points": w.Points, "prePoints": w.PrePoints, "sampleFrequency": w.SampleFrequency, "channels": channels}
}

// ---- fault_record_export ----

var FaultRecordExport = kit.Def[frOperationGetArgs]{
	Name:  "fault_record_export",
	Title: "导出故障录波数据",
	Description: "把一次召唤录波保存的录波文件解析为 CSV（每条记录的故障信息、快照与逐点波形，打包为 zip），以文件形式保存到会话工作区。" +
		"返回文件路径；请用 Python 解压后用 pandas 分析、作图，不要把全文读入上下文。",
	ReadOnly: true,
	Handler: func(ctx context.Context, a frOperationGetArgs) (*mcp.CallToolResult, error) {
		name, data, err := services.ExportFaultRecordFile(ctx, strings.TrimSpace(a.ID), "csv")
		if errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) || errors.Is(err, services.ErrFaultRecordInvalid) {
			return kit.Fail(err), nil
		}
		if err != nil {
			return kit.Upstream("ToolBox 故障录波文件", err), nil
		}
		return kit.ExportFile("fwh://fault-record/"+name, "application/zip", data, "zip 内每条记录一组 CSV（故障信息、快照、逐点波形，通道列名为 ch<序号> 0x<含义码>）。"), nil
	},
}

// ---- 写操作（ops）：fault_record_fetch、fault_record_param_write、fault_record_cancel、fault_record_retry_download ----

type frFetchArgs struct {
	frDeviceArgs
	RecordIndexes []int `json:"recordIndexes" jsonschema:"要召唤的录波记录序号（从 fault_record_device_info 类别 3 的故障录波总目录中选），可多条，设备打成一个包上传"`
}

var FaultRecordFetch = kit.TaskDef[frFetchArgs]{
	Def: kit.Def[frFetchArgs]{
		Name:  "fault_record_fetch",
		Title: "召唤设备故障录波",
		Description: "通过 MQTT 让设备上传指定的故障录波记录，下载后保存并解析。耗时通常几分钟（设备打包、上传、下载）。" +
			"以长任务方式执行：提交后立即返回，完成后平台会把结果发给你；之后用 fault_record_data 查看概要、fault_record_export 导出 CSV。" +
			"先用 fault_record_device_info（类别 3）确认记录序号。这是写操作，执行前会请求确认。",
		ReadOnly:   false,
		Properties: mergeProps(frDeviceProps, map[string]map[string]any{"recordIndexes": {"minItems": 1, "items": map[string]any{"type": "integer", "minimum": 1}}}),
		Handler: func(ctx context.Context, a frFetchArgs) (*mcp.CallToolResult, error) {
			id, fail := frStartFetch(ctx, a)
			if fail != nil {
				return fail, nil
			}
			return frSubmitted(id, "召唤录波"), nil
		},
	},
	Poll: 15 * time.Second,
	Start: func(ctx context.Context, a frFetchArgs) (kit.TaskStart, *mcp.CallToolResult) {
		id, fail := frStartFetch(ctx, a)
		return kit.TaskStart{Key: id, Flag: "op", Note: "已提交召唤录波，设备上传与下载通常需要几分钟，完成后平台会把结果发给你"}, fail
	},
	Status: frStatus,
	Cancel: frCancel,
}

func frStartFetch(ctx context.Context, a frFetchArgs) (string, *mcp.CallToolResult) {
	req, err := frRequest(a.frDeviceArgs, domain.FaultRecordOpRecordFetch)
	if err != nil {
		return "", kit.Fail(err)
	}
	req.RecordIndexes = a.RecordIndexes
	return frSubmit(ctx, req)
}

type frParamWriteArgs struct {
	frDeviceArgs
	Params []proto.ParaItem `json:"params" jsonschema:"要设置的参数：id 为功能码，setVal 为十六进制字节（可带空格）。1 清除设备故障波形（不可恢复，setVal 为空）；2 采样通道配置（1 字节个数 + 每通道 2 字节）；3 手动触发故障录波（setVal 为空）；4 设备对时（7 字节：年 2B 大端、月、日、时、分、秒）；5 采样频率（2 字节）；6 可配采样通道（6 字节）；7 录波开关（00 关、01 开）"`
}

var FaultRecordParamWrite = kit.TaskDef[frParamWriteArgs]{
	Def: kit.Def[frParamWriteArgs]{
		Name:  "fault_record_param_write",
		Title: "设置设备故障录波参数",
		Description: "通过 MQTT 设置设备的故障录波参数或执行动作（清除波形、手动触发录波、对时、采样频率、通道配置、录波开关）。" +
			"会修改设备状态，其中清除波形不可恢复：调用前向用户说明要设置的设备、功能码与值。设置前可用 fault_record_param_read、fault_record_device_info 读取当前值。" +
			"返回逐项设置结果。这是破坏性写操作，每次执行前都会请求确认。",
		ReadOnly:    false,
		Destructive: true,
		Properties:  mergeProps(frDeviceProps, map[string]map[string]any{"params": {"minItems": 1}}),
		Handler: func(ctx context.Context, a frParamWriteArgs) (*mcp.CallToolResult, error) {
			id, fail := frStartParamWrite(ctx, a)
			if fail != nil {
				return fail, nil
			}
			return frWait(ctx, id), nil
		},
	},
	Poll: 5 * time.Second,
	Start: func(ctx context.Context, a frParamWriteArgs) (kit.TaskStart, *mcp.CallToolResult) {
		id, fail := frStartParamWrite(ctx, a)
		return kit.TaskStart{Key: id, Flag: "op", Note: "已向设备发送设置请求，设备回复后平台会把结果发给你"}, fail
	},
	Status: frStatus,
	Cancel: frCancel,
}

func frStartParamWrite(ctx context.Context, a frParamWriteArgs) (string, *mcp.CallToolResult) {
	req, err := frRequest(a.frDeviceArgs, domain.FaultRecordOpParamWrite)
	if err != nil {
		return "", kit.Fail(err)
	}
	req.ParaList = a.Params
	return frSubmit(ctx, req)
}

var FaultRecordCancel = kit.Def[frOperationGetArgs]{
	Name:  "fault_record_cancel",
	Title: "取消故障录波操作",
	Description: "取消一次进行中的故障录波操作（在页面或其他会话中发起的也可以取消），执行器 1 秒内停止。已结束的操作无法取消。" +
		"本会话以长任务方式发起的操作，也可以在平台的后台调用栏中取消。这是写操作，执行前会请求确认。",
	ReadOnly: false,
	// 取消已取消的操作会报“已结束”，不会产生额外影响
	Idempotent: true,
	Handler: func(ctx context.Context, a frOperationGetArgs) (*mcp.CallToolResult, error) {
		err := services.CancelFaultRecordOperation(ctx, strings.TrimSpace(a.ID))
		if errors.Is(err, services.ErrFaultRecordInvalid) || errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) {
			return kit.Fail(err), nil
		}
		if err != nil {
			return kit.Upstream("ToolBox 故障录波", err), nil
		}
		return mcp.NewToolResultText("已请求取消操作 " + a.ID + "，用 fault_record_operation_get 确认状态。"), nil
	},
}

var FaultRecordRetryDownload = kit.Def[frOperationGetArgs]{
	Name:  "fault_record_retry_download",
	Title: "重试下载故障录波文件",
	Description: "设备已上传录波文件、但下载失败或超时的召唤录波操作，重新下载（按 15 秒间隔重试到总超时）。" +
		"只在 fault_record_operation_get 显示上传已完成且下载失败时使用。这是写操作，执行前会请求确认。",
	ReadOnly: false,
	Handler: func(ctx context.Context, a frOperationGetArgs) (*mcp.CallToolResult, error) {
		err := services.RetryFaultRecordDownload(ctx, strings.TrimSpace(a.ID), ServiceAccount)
		if errors.Is(err, services.ErrFaultRecordInvalid) || errors.Is(err, mongoRepo.ErrFaultRecordOpNotFound) {
			return kit.Fail(err), nil
		}
		if err != nil {
			return kit.Upstream("ToolBox 故障录波", err), nil
		}
		return mcp.NewToolResultText("已重新提交下载，用 fault_record_operation_get 查看结果。"), nil
	},
}

// mergeProps 合并多组字段补充约束
func mergeProps(groups ...map[string]map[string]any) map[string]map[string]any {
	out := map[string]map[string]any{}
	for _, g := range groups {
		for k, v := range g {
			out[k] = v
		}
	}
	return out
}