syntax = "proto3";

package agv.calibration.workshop;

import "calibration_common.proto";
import "vehicle_profile.proto";

// =========================================================
// 文件作用：自动化标定车间总编排协议
// 使用范围：
// 1) 负责整车标定会话的创建、规划、执行、暂停、恢复、取消
// 2) 负责人工确认节点、审批节点、回滚、报告归档
// 3) 负责把外部定位 / 底盘 / 运控 / 传感器标定串成完整闭环
// 4) 负责根据车辆画像与阶段配置自动生成执行计划
// =========================================================

// =========================================================
// 服务：车间总编排服务
// 运行位置：Ubuntu 车间电脑
// 调用方：上位机界面、自动化车间入口程序、调度系统
// =========================================================
service WorkshopOrchestrationService {
  // 心跳保活
  rpc Heartbeat(.agv.calibration.common.HeartbeatRequest)
      returns (.agv.calibration.common.HeartbeatResponse);

  // 创建一场新的整车标定会话
  rpc CreateWorkshopSession(CreateWorkshopSessionRequest)
      returns (CreateWorkshopSessionResponse);

  // 查询会话信息
  rpc GetWorkshopSession(WorkshopSessionQuery)
      returns (WorkshopSessionResponse);

  // 生成本次会话的执行计划
  rpc BuildExecutionPlan(BuildExecutionPlanRequest)
      returns (BuildExecutionPlanResponse);

  // 重建执行计划
  rpc RebuildExecutionPlan(RebuildExecutionPlanRequest)
      returns (BuildExecutionPlanResponse);

  // 校验当前执行计划
  rpc ValidateExecutionPlan(ValidateExecutionPlanRequest)
      returns (ValidateExecutionPlanResponse);

  // 执行车间预检 / readiness 检查
  rpc RunWorkshopPrecheck(RunWorkshopPrecheckRequest)
      returns (.agv.calibration.common.JobAccepted);

  // 查询最近一次预检结果
  rpc GetLastWorkshopPrecheckResult(WorkshopSessionQuery)
      returns (WorkshopPrecheckResponse);

  // 启动整场自动化标定
  rpc StartWorkshopSession(StartWorkshopSessionRequest)
      returns (.agv.calibration.common.JobAccepted);

  // 查询整场会话对应长任务状态
  rpc GetWorkshopJobStatus(.agv.calibration.common.JobQuery)
      returns (.agv.calibration.common.JobStatus);

  // 暂停整场会话
  rpc PauseWorkshopSession(PauseWorkshopSessionRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 恢复整场会话
  rpc ResumeWorkshopSession(ResumeWorkshopSessionRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 取消整场会话
  rpc CancelWorkshopSession(CancelWorkshopSessionRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 打开会话事件流
  rpc StreamWorkshopEvent(WorkshopSessionQuery)
      returns (stream WorkshopEvent);

  // 人工确认某个等待中的手动步骤
  rpc AcknowledgeManualStep(ManualStepAckRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 审批某个阶段的结果
  rpc ApproveStageResult(ApproveStageResultRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 对某阶段参数进行回滚
  rpc RollbackStageParameters(RollbackStageParametersRequest)
      returns (.agv.calibration.common.StandardResponse);

  // 获取最终车间报告
  rpc GetWorkshopReport(WorkshopSessionQuery)
      returns (WorkshopReportResponse);
}

// =========================================================
// 会话状态
// 作用：描述整场整车标定会话当前所处阶段
// =========================================================
enum WorkshopSessionState {
  WORKSHOP_SESSION_STATE_UNSPECIFIED = 0; // 未指定
  DRAFT = 1;                              // 草稿，尚未规划
  PLANNING = 2;                           // 正在规划
  READY = 3;                              // 已规划完成，可启动
  PRECHECK_RUNNING = 4;                   // 预检执行中
  RUNNING = 5;                            // 运行中
  PAUSED = 6;                             // 已暂停
  WAITING_MANUAL_ACTION = 7;              // 等待人工动作
  WAITING_APPROVAL = 8;                   // 等待审批
  SUCCEEDED = 9;                          // 整场成功
  FAILED = 10;                            // 整场失败
  CANCELED = 11;                          // 已取消
  ROLLED_BACK = 12;                       // 已回滚
}

// =========================================================
// 阶段执行策略
// 作用：控制某个阶段失败时系统该如何处理
// =========================================================
enum StageExecutionPolicy {
  STAGE_EXECUTION_POLICY_UNSPECIFIED = 0; // 未指定
  REQUIRED = 1;                           // 必须执行，失败即整场失败
  OPTIONAL = 2;                           // 可选执行，失败后可继续
  SKIP_IF_UNSUPPORTED = 3;                // 若车辆不支持则自动跳过
}

// =========================================================
// 审批状态
// 作用：描述某一阶段结果是否需要人工审核
// =========================================================
enum ApprovalState {
  APPROVAL_STATE_UNSPECIFIED = 0; // 未指定
  APPROVAL_NOT_REQUIRED = 1;      // 不需要审批
  APPROVAL_PENDING = 2;           // 待审批
  APPROVED = 3;                   // 已通过
  REJECTED = 4;                   // 已拒绝
}

// =========================================================
// 人工动作类型
// 作用：表达需要人工介入的节点类型
// =========================================================
enum ManualActionType {
  MANUAL_ACTION_TYPE_UNSPECIFIED = 0; // 未指定
  PLACE_TARGET_BOARD = 1;             // 放置标靶 / 标定板
  CONFIRM_WORKCELL_CLEAR = 2;         // 确认工位区域安全
  CONFIRM_VEHICLE_POSE = 3;           // 确认车辆姿态已就位
  CONFIRM_ARM_HOME = 4;               // 确认机械臂已回零
  CONFIRM_SENSOR_INSTALLATION = 5;    // 确认传感器安装状态
  CONFIRM_READY_TO_CONTINUE = 6;      // 确认可继续执行
  OTHER_MANUAL_ACTION = 7;            // 其他人工动作
}

// =========================================================
// 车间事件类型
// 作用：用于异步通知界面 / 上层系统
// =========================================================
enum WorkshopEventType {
  WORKSHOP_EVENT_TYPE_UNSPECIFIED = 0; // 未指定
  SESSION_STATE_CHANGED = 1;           // 会话状态变化
  EXECUTION_PLAN_BUILT = 2;            // 执行计划已生成
  PRECHECK_STARTED = 3;                // 预检开始
  PRECHECK_COMPLETED = 4;              // 预检完成
  STAGE_STARTED = 5;                   // 阶段开始
  STAGE_COMPLETED = 6;                 // 阶段完成
  STAGE_FAILED = 7;                    // 阶段失败
  MANUAL_ACTION_REQUIRED = 8;          // 需要人工操作
  APPROVAL_REQUIRED = 9;               // 需要审批
  SAFETY_TRIGGERED = 10;               // 安全保护触发
  ROLLBACK_EXECUTED = 11;              // 已执行回滚
  REPORT_READY = 12;                   // 报告已生成
}

// =========================================================
// 操作员信息
// 作用：记录本次会话的人工责任归属
// =========================================================
message WorkshopOperatorInfo {
  string operator_id = 1;    // 操作员工号
  string operator_name = 2;  // 操作员姓名
  string workstation_id = 3; // 工位 ID
  string shift_id = 4;       // 班次 ID
}

// =========================================================
// 单项标定任务配置
// 作用：表达本次会话中某类流程阶段是否启用
// =========================================================
message RequestedCalibrationTask {
  .agv.calibration.vehicle.profile.WorkflowStageType stage_type = 1; // 阶段类型
  bool enabled = 2;                                                 // 是否启用
  bool require_manual_approval = 3;                                 // 是否要求人工审批
  StageExecutionPolicy execution_policy = 4;                        // 执行策略
  string reason = 5;                                                // 启用 / 禁用原因
}

// =========================================================
// 会话配置
// 作用：描述整场自动化标定运行策略
// =========================================================
message WorkshopSessionConfig {
  repeated RequestedCalibrationTask requested_tasks = 1; // 请求执行的阶段列表
  bool auto_commit_parameters = 2;                      // 是否自动写入参数
  bool require_manual_approval_before_commit = 3;       // 写入前是否要求审批
  bool run_validation_after_each_stage = 4;             // 每阶段后是否自动复测
  bool stop_on_first_failure = 5;                       // 是否首错即停
  bool allow_optional_stage_skip = 6;                   // 是否允许可选阶段跳过
  bool enable_auto_rollback_on_validation_failure = 7; // 验证失败是否自动回滚
  bool allow_rebuild_execution_plan = 8;               // 是否允许运行前重建计划
}

// =========================================================
// 阶段计划
// 作用：描述车间编排器生成的一步执行计划
// =========================================================
message StagePlan {
  string stage_id = 1;      // 阶段 ID
  .agv.calibration.vehicle.profile.WorkflowStageType stage_type = 2; // 流程阶段类型
  .agv.calibration.vehicle.profile.CalibrationModuleType module_type = 3; // 所属模块类型
  string display_name = 4;  // 阶段显示名
  uint32 order_index = 5;   // 阶段顺序号

  StageExecutionPolicy execution_policy = 6;         // 执行策略
  repeated string depends_on_stage_ids = 7;          // 依赖的前置阶段 ID
  bool requires_manual_confirmation_before_start = 8; // 开始前是否要求人工确认
  bool requires_approval_before_commit = 9;          // 参数提交前是否要求审批
  ManualActionType manual_action_type = 10;          // 若为人工阶段，对应的人工动作类型
  string executor_endpoint_name = 11;                // 实际执行的端点名（可对应 action / service）
  string description = 12;                           // 阶段说明
  uint32 retry_limit = 13;                           // 最大重试次数
  bool auto_generated = 14;                          // 是否由系统自动生成
  repeated string target_resource_ids = 15;          // 阶段关联的资源 ID 列表
  repeated .agv.calibration.common.KeyValuePair metadata = 16; // 扩展元数据
}

// =========================================================
// 执行计划校验问题
// 作用：描述当前阶段计划中的冲突、缺项或风险
// =========================================================
message ExecutionPlanValidationIssue {
  bool blocking = 1; // 是否为阻塞问题
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string issue_code = 3; // 问题代码
  string message = 4;    // 问题说明
  string related_stage_id = 5; // 关联阶段 ID
}

// =========================================================
// 车间会话
// 作用：统一表达整场标定会话的核心状态
// =========================================================
message WorkshopSession {
  string session_id = 1;   // 会话 ID
  WorkshopSessionState state = 2; // 会话状态

  .agv.calibration.vehicle.profile.VehicleProfile vehicle_profile_snapshot = 3; // 车辆画像快照
  WorkshopOperatorInfo operator_info = 4; // 操作员信息
  WorkshopSessionConfig config = 5;       // 会话配置
  repeated StagePlan stage_plan = 6;      // 阶段计划

  int64 created_timestamp_us = 7; // 创建时间
  int64 updated_timestamp_us = 8; // 最近更新时间
  string active_stage_id = 9;     // 当前活跃阶段 ID

  string workshop_line_id = 10;   // 所属工位 / 产线 ID
  string active_job_id = 11;      // 当前整场执行的 job_id
  .agv.calibration.common.FileDigest vehicle_profile_digest = 12; // 车辆画像摘要
}

// =========================================================
// 创建会话请求
// 作用：创建一场新的整车标定会话
// =========================================================
message CreateWorkshopSessionRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  .agv.calibration.vehicle.profile.VehicleProfile vehicle_profile_snapshot = 2; // 车辆画像快照
  WorkshopOperatorInfo operator_info = 3; // 操作员信息
  WorkshopSessionConfig config = 4;       // 会话配置
  string workshop_line_id = 5;            // 产线 / 工位线 ID
  bool auto_build_execution_plan = 6;     // 创建后是否自动生成计划
}

// =========================================================
// 创建会话响应
// 作用：返回新建会话结果
// =========================================================
message CreateWorkshopSessionResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  string session_id = 4; // 新建会话 ID
  WorkshopSessionState state = 5; // 初始状态
  WorkshopSession session = 6; // 完整会话内容
}

// =========================================================
// 会话查询请求
// 作用：按 session_id 查询会话
// =========================================================
message WorkshopSessionQuery {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
}

// =========================================================
// 会话查询响应
// 作用：返回整场会话信息
// =========================================================
message WorkshopSessionResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  WorkshopSession session = 4; // 会话详情
}

// =========================================================
// 生成执行计划请求
// 作用：根据车辆画像与配置生成阶段计划
// =========================================================
message BuildExecutionPlanRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  bool validate_profile_before_build = 3; // 生成前是否先校验车辆画像
}

// =========================================================
// 重建执行计划请求
// 作用：在修改配置 / 修正依赖关系后重建计划
// =========================================================
message RebuildExecutionPlanRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string rebuild_reason = 3; // 重建原因
  bool keep_finished_stage_results = 4; // 是否保留已完成阶段结果
}

// =========================================================
// 生成执行计划响应
// 作用：返回生成后的阶段计划
// =========================================================
message BuildExecutionPlanResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  repeated StagePlan stage_plan = 4; // 阶段计划
  repeated string warnings = 5; // 警告信息
}

// =========================================================
// 校验执行计划请求
// 作用：检查当前阶段计划是否闭合、依赖是否正确、资源是否冲突
// =========================================================
message ValidateExecutionPlanRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
}

// =========================================================
// 校验执行计划响应
// 作用：返回当前执行计划的校验结果
// =========================================================
message ValidateExecutionPlanResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  bool valid = 4; // 计划是否有效
  repeated ExecutionPlanValidationIssue issues = 5; // 校验问题列表
}

// =========================================================
// 车间预检请求
// 作用：在正式启动前检查车辆、工位、服务、传感器、资源锁等是否就绪
// =========================================================
message RunWorkshopPrecheckRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
}

// =========================================================
// 单个预检项
// 作用：表达一条 readiness / 安全 / 资源检查结果
// =========================================================
message PrecheckItem {
  string item_code = 1; // 检查项编码
  string display_name = 2; // 检查项名称
  bool passed = 3; // 是否通过
  bool blocking = 4; // 是否为阻塞项
  .agv.calibration.common.ErrorCode error_code = 5; // 错误码
  string message = 6; // 结果说明
  .agv.calibration.vehicle.profile.WorkflowStageType related_stage_type = 7; // 关联阶段
  .agv.calibration.vehicle.profile.CalibrationModuleType related_module_type = 8; // 关联模块
}

// =========================================================
// 车间预检结果
// 作用：返回最近一次预检详细结果
// =========================================================
message WorkshopPrecheckResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  bool all_passed = 4; // 是否全部通过
  repeated PrecheckItem items = 5; // 检查项明细
  int64 checked_timestamp_us = 6; // 检查时间
  uint32 blocking_issue_count = 7; // 阻塞问题数量
  bool ready_for_start = 8; // 是否可进入正式执行
}

// =========================================================
// 启动会话请求
// 作用：正式启动整场自动化标定
// =========================================================
message StartWorkshopSessionRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
}

// =========================================================
// 暂停会话请求
// 作用：暂停整场标定
// =========================================================
message PauseWorkshopSessionRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string reason = 3; // 暂停原因
}

// =========================================================
// 恢复会话请求
// 作用：从暂停态恢复整场标定
// =========================================================
message ResumeWorkshopSessionRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string reason = 3; // 恢复原因
}

// =========================================================
// 取消会话请求
// 作用：终止整场标定
// =========================================================
message CancelWorkshopSessionRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string reason = 3; // 取消原因
}

// =========================================================
// 车间事件
// 作用：向界面 / 上层系统异步推送状态变化
// =========================================================
message WorkshopEvent {
  int64 server_timestamp_us = 1; // 服务端时间戳
  string session_id = 2; // 会话 ID
  string stage_id = 3;   // 阶段 ID

  WorkshopEventType event_type = 4; // 事件类型
  WorkshopSessionState session_state = 5; // 当前会话状态
  .agv.calibration.common.JobState stage_job_state = 6; // 当前阶段任务状态

  .agv.calibration.vehicle.profile.WorkflowStageType stage_type = 7; // 流程阶段类型
  .agv.calibration.vehicle.profile.CalibrationModuleType module_type = 8; // 模块类型

  bool requires_manual_ack = 9; // 是否需要人工确认
  ApprovalState approval_state = 10; // 审批状态
  string message = 11; // 事件说明
}

// =========================================================
// 人工步骤确认请求
// 作用：当系统停在人工步骤时，由操作员确认完成
// =========================================================
message ManualStepAckRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string stage_id = 3;   // 阶段 ID
  bool confirmed = 4;    // 是否确认完成
  string note = 5;       // 备注
}

// =========================================================
// 阶段结果审批请求
// 作用：对某阶段结果进行通过 / 驳回
// =========================================================
message ApproveStageResultRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string stage_id = 3;   // 阶段 ID
  ApprovalState decision = 4; // 审批结论
  string reviewer_id = 5; // 审批人 ID
  string comment = 6;     // 审批说明
}

// =========================================================
// 参数回滚请求
// 作用：对某阶段参数回滚到指定版本
// =========================================================
message RollbackStageParametersRequest {
  .agv.calibration.common.RequestHeader header = 1; // 请求头
  string session_id = 2; // 会话 ID
  string stage_id = 3;   // 阶段 ID
  string target_parameter_version = 4; // 回滚目标版本
  string reason = 5; // 回滚原因
}

// =========================================================
// 阶段结果摘要
// 作用：用于最终报告中概述每个阶段的结果
// =========================================================
message StageResultSummary {
  string stage_id = 1; // 阶段 ID
  .agv.calibration.vehicle.profile.WorkflowStageType stage_type = 2; // 阶段类型
  .agv.calibration.vehicle.profile.CalibrationModuleType module_type = 3; // 模块类型

  bool success = 4; // 是否成功
  bool auto_acceptance_passed = 5; // 自动验收是否通过
  .agv.calibration.common.JobState final_job_state = 6; // 最终任务状态
  ApprovalState approval_state = 7; // 审批状态
  string parameter_version = 8; // 该阶段产出的参数版本

  repeated .agv.calibration.common.FileReference artifacts = 9; // 关联产物
  string summary = 10; // 摘要说明

  bool rolled_back = 11; // 是否发生回滚
  string failure_root_cause = 12; // 失败根因说明
  repeated .agv.calibration.common.KeyValuePair metadata = 13; // 阶段结果扩展信息
}

// =========================================================
// 车间最终报告
// 作用：归档整场会话的总体结果与所有阶段结果
// =========================================================
message WorkshopReport {
  string session_id = 1; // 会话 ID
  bool overall_success = 2; // 是否总体成功
  int64 started_timestamp_us = 3; // 开始时间
  int64 finished_timestamp_us = 4; // 结束时间
  repeated StageResultSummary stage_results = 5; // 各阶段结果
  repeated .agv.calibration.common.FileReference report_files = 6; // 报告文件
  string summary = 7; // 总结说明
  string active_parameter_bundle_version = 8; // 最终生效参数包版本
  repeated .agv.calibration.common.KeyValuePair metadata = 9; // 报告扩展元数据
}

// =========================================================
// 车间报告响应
// 作用：返回最终归档报告
// =========================================================
message WorkshopReportResponse {
  bool success = 1; // 是否成功
  .agv.calibration.common.ErrorCode error_code = 2; // 错误码
  string message = 3; // 说明
  WorkshopReport report = 4; // 报告内容
}