/**
 * 제어 모드 — 백엔드 API stub
 *
 * 인터페이스는 실 DB 연동 베이스로 설계. 초기 구현은 mock 응답.
 * 실제 API 만들 때 함수 안의 mock 만 fetch 호출로 교체.
 *
 * 향후 매핑 (예시):
 *   listExecutionHistory → GET /api/control/executions?card_id=...&limit=...
 *   getNodeStats         → GET /api/control/nodes/{nodeId}/stats
 *   listNodeComments     → GET /api/control/nodes/{nodeId}/comments
 *   listPresence         → GET /api/control/dashboards/{dashboardId}/presence (WS 권장)
 *   listRelations        → GET /api/control/tables/{tableName}/relations
 *   listRelatedRules     → GET /api/control/cards/{cardId}/related-rules
 */

export interface ExecutionRecord {
  id: string;
  ts: string;          // HH:MM:SS or full ISO
  who: string;         // user@domain or "API · webhook"
  trig: string;        // trigger reference (e.g., shipment_no)
  ok: boolean;
  ms: number;
  steps: number;
  err?: string;
}

export interface NodeStats {
  valid: boolean;
  lastMs: number | null;
  runs: number;
  alert: string | null;
}

export interface NodeComment {
  who: string;
  short: string;
  color: string;       // RGB triplet "0,206,201"
  text: string;
  at: string;          // relative time
}

export interface PresenceUser {
  name: string;
  short: string;
  color: string;
  mode: 'edit' | 'view';
}

export interface TableRelation {
  from: string;
  to: string;
  label: string;
  type: 'auto' | 'rel';
}

export interface RelatedRule {
  id: string;
  name: string;
  status: 'active' | 'draft' | 'sched';
  lastRun: string;
  runs: number;
  successRate: number | null;
  nodes: number;
  owner: string;
  primary?: boolean;
}

/** 실행 이력 — 카드별 최근 실행 결과 */
export async function listExecutionHistory(
  cardId: string,
  options: { limit?: number } = {},
): Promise<ExecutionRecord[]> {
  void cardId; void options;
  // TODO: GET /api/control/executions?card_id=...&limit=...
  return Promise.resolve([]);
}

/** 노드 통계 — 단일 노드의 valid/runs/lastMs/alert */
export async function getNodeStats(nodeId: string): Promise<NodeStats> {
  void nodeId;
  // TODO: GET /api/control/nodes/{nodeId}/stats
  return Promise.resolve({ valid: true, lastMs: null, runs: 0, alert: null });
}

/** 노드 댓글 */
export async function listNodeComments(nodeId: string): Promise<NodeComment[]> {
  void nodeId;
  // TODO: GET /api/control/nodes/{nodeId}/comments
  return Promise.resolve([]);
}

/** 현재 보고 있는 사용자 (presence) */
export async function listPresence(dashboardId: string): Promise<PresenceUser[]> {
  void dashboardId;
  // TODO: GET /api/control/dashboards/{dashboardId}/presence (WS 권장)
  return Promise.resolve([]);
}

/** 테이블 관계 (view 모드의 fan-out 트리) */
export async function listRelations(tableName: string): Promise<TableRelation[]> {
  void tableName;
  // TODO: GET /api/control/tables/{tableName}/relations
  return Promise.resolve([]);
}

/** 관련 룰 — 이 카드에 연결된 룰 목록 */
export async function listRelatedRules(cardId: string): Promise<RelatedRule[]> {
  void cardId;
  // TODO: GET /api/control/cards/{cardId}/related-rules
  return Promise.resolve([]);
}