Aislo/Z01_MasterData/Z01_MasterData_UI_Cells.ts

/* =============================================================================
 * Z01_MasterData_UI_Cells.ts
 * 마스터 표 칸 글자 — 숨김 열 · 열 제목 · 칸 값 · 쪽 수 (import 없음 · 시험이 그대로 돌림)
 *
 * 한글 이름은 API 가 `label` 로 줌(이름표 파일 `resources/data_master_labels/`) — 화면은
 * 사전을 두지 않고 받은 대로 보임. 두 벌이 되면 어긋나기 때문(2026-09-15 브레인 Z01 ①).
 * ========================================================================== */

export interface MasterColumn {
  key: string;
  label: string;
  unit?: string | null;
  /** 내부 id · sha · 생성시각 — 기본으로 안 보임 */
  hidden?: boolean;
}

export function shownColumns(columns: MasterColumn[], showHidden: boolean): MasterColumn[] {
  return showHidden ? columns : columns.filter((column) => !column.hidden);
}

export function columnTitle(column: MasterColumn): string {
  return column.unit ? `${column.label} (${column.unit})` : column.label;
}

/** 단위가 붙은 수만 쉼표 — 연도·코드 같은 수(단위 없음)에 쉼표가 끼면 틀린 값처럼 보임. */
export function cellText(value: unknown, unit?: string | null): string {
  if (value === null || value === undefined) return "";
  if (typeof value === "boolean") return value ? "예" : "아니오";
  if (typeof value === "number" && unit) {
    return value.toLocaleString("ko-KR", { maximumFractionDigits: 10 });
  }
  if (typeof value === "object") return JSON.stringify(value);
  // 부동소수 끝자리 떠돌이(0.00018109999999999998)를 15자리에서 잘라 원래 수로 보임.
  if (typeof value === "number") return String(Number(value.toPrecision(15)));
  return String(value);
}

/** 줄마다 판의 기준일 — 기초단가 한 표에 시기가 다른 판이 섞여 줄마다 보임(2026-09-15 브레인). */
export const EFFECTIVE_DATE_KEY = "effective_date";

/** 한 줄의 칸들 — columns 차례대로만(columns 에 없는 열은 안 그림) · 줄에 그 열이 없으면 「—」. */
export function rowCells(row: Record<string, unknown>, columns: MasterColumn[]): string[] {
  return columns.map((column) => {
    // 기준일 없는 자료(machine_operating 등)는 빈칸이 아니라 모른다고 말함.
    if (column.key === EFFECTIVE_DATE_KEY) return cellText(row[column.key]) || "판 모름";
    return Object.hasOwn(row, column.key) ? cellText(row[column.key], column.unit) : "—";
  });
}

/** 단추 글자·칸 설명에 넣는 값 — 수는 늘 쉼표 · 단위(이름표)를 뒤에 붙여 무엇인지 보이게. */
export function valueWithUnit(value: unknown, unit?: string | null): string {
  const text =
    typeof value === "number"
      ? value.toLocaleString("ko-KR", { maximumFractionDigits: 10 })
      : cellText(value, unit);
  return text && unit ? `${text} ${unit}` : text;
}

/** 자료 출처표 한 줄 — 어디서 받고 최신이 무엇인지(데스크탑 서브 출처표 · 메인이 표 수준에 실음). */
export interface TableSource {
  source_id?: string;
  /** 원본 이름 — 한 표가 원본 여럿을 모아 어느 것이 뒤처졌는지 가려야 함 */
  name?: string;
  publisher: string;
  where: string;
  cycle?: string;
  latest_published?: string;
  our_edition?: string;
  checked_at?: string;
  /** 뒤처짐 판정 — 서버만 함 · null 은 「모름」이라 띠를 안 세움 */
  outdated?: boolean | null;
}

/**
 * 뒤처진 자료 띠 글자 — 서버가 outdated 라 할 때만. 화면은 날짜를 견주지 않음(판정 두 벌 금지).
 * 받는 자리를 꼭 적음 — 최신이 무엇인지·어디서 받는지가 없어 건설 노임이 반 년 뒤처졌음.
 */
export function outdatedBanner(sources?: TableSource[]): string[] {
  return (sources ?? [])
    .filter((source) => source.outdated === true)
    .map((source) => {
      const head = source.name ? `${source.name} — ` : "";
      const where = source.where ? ` ${source.where}` : "";
      return `${head}이 자료는 ${source.our_edition ?? "판 모름"} 판 · 최신은 ${source.latest_published ?? "?"} 공표 · ${source.publisher}${where}`;
    });
}

/** 열 제목을 눌러 세운 차례 — null 이면 원본 차례(서버가 sort 없이 주는 그대로). */
export interface SortOrder {
  key: string;
  desc: boolean;
}

/** 같은 열을 누르면 오름 → 내림 → 원본 차례, 다른 열이면 그 열 오름부터. */
export function nextSort(current: SortOrder | null, key: string): SortOrder | null {
  if (current?.key !== key) return { key, desc: false };
  return current.desc ? null : { key, desc: true };
}

/** 알림은 한 줄로도 목록으로도 옴 — 받은 대로 줄 목록으로. */
export function noticeLines(notice?: string | string[]): string[] {
  if (!notice) return [];
  return Array.isArray(notice) ? notice.filter(Boolean) : [notice];
}

/** 서버 글자의 `**굵게**` 를 조각으로 — 별표가 화면에 글자로 남으면 안 됨. */
export function boldSegments(text: string): { text: string; bold: boolean }[] {
  return text
    .split(/\*\*(.+?)\*\*/g)
    .map((part, index) => ({ text: part, bold: index % 2 === 1 }))
    .filter((part) => part.text !== "");
}

/** 기초단가 표 머리 — 열 하나에 한 문장이라 표에 한 번만 옴(2026-09-15 브레인 ④). */
export interface TableMeta {
  /** 한 표가 모은 원본마다 한 줄 */
  source?: TableSource[];
  /**
   * 표 머리 알림 — 서버가 한 벌로 줌(첫 줄 「새로 만드는 프로젝트부터」 · 요율은 법정값 경고까지).
   * 화면이 사전을 가지면 두 벌이 됨.
   */
  notice?: string | string[];
  /**
   * 서버가 세워 줄 수 있는 열 — 이 목록에 있는 제목만 눌림.
   * 없으면 제목이 안 눌림(원본 차례) — 눌렀는데 그대로인 화면을 안 만들려고 서버에 물어서 켬.
   */
  sortable?: string[];
  editable?: string[];
  /** 열key → 왜 못 고치나 */
  locked?: Record<string, string>;
  /** 열key → 식 자체 */
  formula?: Record<string, string>;
}

/** 덮개 판정 낱말 셋 — 서버가 줌 · 이것만 씀(2026-09-15 브레인). */
export type OverrideState = "edited" | "source_changed" | "orphan";

export interface CellInfo {
  editable: boolean;
  reason: string | null;
  overridden: boolean;
  /** 고쳐진 칸만 — 사람이 고칠 때의 원본 값 */
  original?: unknown;
  /** 고친 칸의 서버 판정 — 안 고친 칸 null · 서버가 state 를 안 주면 「missing」(때우지 않음) */
  state: OverrideState | "missing" | null;
  /** source_changed 칸만 — 지금 원본 값 */
  current?: unknown;
  rule: string | null;
  /** 이 줄 값을 넣은 식 — 줄마다 다를 때만 옴 */
  filled: string | null;
}

/** 칸 하나의 고침 상태 — 줄의 `@overrides`·`@formula` 는 해당할 때만 실려 옴. */
export function cellInfo(meta: TableMeta, row: Record<string, unknown>, key: string): CellInfo {
  const overrides = row["@overrides"] as
    Record<string, { original: unknown; current?: unknown; state?: OverrideState }> | undefined;
  const filled = row["@formula"] as Record<string, string> | undefined;
  const override = overrides?.[key];
  // 판정은 서버 state 만 — 화면이 값을 견줘 따로 정하면 판정이 두 벌이 됨(2026-09-15 브레인).
  const state = override ? (override.state ?? "missing") : null;
  return {
    editable: meta.editable?.includes(key) ?? false,
    reason: meta.locked?.[key] ?? null,
    overridden: override !== undefined,
    ...(override ? { original: override.original } : {}),
    state,
    ...(state === "source_changed" ? { current: override?.current } : {}),
    rule: meta.formula?.[key] ?? null,
    filled: filled?.[key] ?? null,
  };
}

const NUMBER_TEXT = /^-?[\d,]+(\.\d+)?$/;

/** 고친 글자를 보낼 값으로 — 수 칸은 쉼표를 떼 수로, 못 읽으면 undefined(저장 안 함). */
export function parseCellInput(text: string, original: unknown): unknown {
  const trimmed = text.trim();
  const numeric = typeof original === "number" || (original == null && NUMBER_TEXT.test(trimmed));
  if (!numeric) return text;
  if (!NUMBER_TEXT.test(trimmed)) return undefined;
  return Number(trimmed.replaceAll(",", ""));
}

export function pageCount(total: number, size: number): number {
  return Math.max(1, Math.ceil(total / size));
}

/** 쪽 번호 칸에 적은 값을 1~끝 쪽으로 — 큰 표(800쪽)는 한 칸씩 넘길 수 없음. */
export function clampPage(value: number, pages: number): number {
  return Number.isFinite(value) ? Math.min(pages, Math.max(1, Math.round(value))) : 1;
}

/**
 * 최신 요청의 응답만 — 검색 글자가 바뀌어 옛 요청이 늦게 오면 새 표를 덮음.
 * 옛 요청은 undefined 로 끝나고(오류도 삼킴) 최신 요청의 오류만 던짐.
 */
export function latestOnly<A extends unknown[], T>(
  fn: (...args: A) => Promise<T>,
): (...args: A) => Promise<T | undefined> {
  let seq = 0;
  return async (...args) => {
    const mine = ++seq;
    try {
      const value = await fn(...args);
      return mine === seq ? value : undefined;
    } catch (error) {
      if (mine === seq) throw error;
      return undefined;
    }
  };
}