@things-factory/ops-master 10.1.248 → 10.1.250

package/dist-client/pages/master/master-page-base.d.ts

@@ -0,0 +1,369 @@
+import '@material/web/icon/icon.js';
+import '@operato/data-grist/ox-grist.js';
+import { DataGrist, FetchOption } from '@operato/data-grist';
+import type { ReferenceOptions } from './grist-reference.js';
+import { PageView } from '@operato/shell';
+import { AssignmentChange } from './assignment-fields.js';
+import { AppliedAnswer } from './applied-when-dialog.js';
+import './applied-when-dialog.js';
+/**
+ * 마스터 화면이 함께 쓰는 것 — **코드 재사용은 여기서, 화면은 각자.**
+ *
+ * ── 왜 화면을 갈랐나 (2026-09-01) ──────────────────────────────────────────
+ * 전에는 화면 하나가 `?axis=` 로 열두 축을 다 맡았다. 근거는 「열두 축이 하는 일이 같다」였는데, 그
+ * 말은 **지금 자리표시자라서 같아 보이는 것**이었다. 선언을 읽으면 이미 갈라져 있다.
+ *
+ *   정지 사유 · 위치      계층(parentName · parentId) — 표가 아니라 나무여야 한다
+ *   등급 넷              baseIds 다중 상속 — 쉼표 문자열로 편집 중이다
+ *   인원 · 설비 · 자산    근무 캘린더 · 검사 결과를 JSON 원문으로 보인다
+ *   자재                 GTIN · 단위 · 보관처의 칸이 없어 properties JSON 이다
+ *   공정                 duration 이 ISO 기간, bizStep 이 EPCIS 어휘다
+ *   검사 기준            컬럼이 0개다 — 항목 · 상하한 · 단위 · 방법이 들어와야 한다
+ *
+ * 그 자리표시자를 걷으면 열둘이 서로 다른 화면이 된다. 공용 화면에 「이 축만」 분기를 열둘 넣는 것은
+ * 화면 열둘보다 나쁘다.
+ *
+ * ── UX 일관성과 일괄 개발 편의는 다르다 ────────────────────────────────────
+ * 일관성은 **쓰는 사람이 겪는 것**이다. 같은 뜻이 같은 자리에, 같은 용어로, 같은 조작으로. 그것은
+ * 어휘와 배치와 부품을 공유해서 얻는다.
+ *
+ * 일괄 개발의 편의는 **만드는 쪽이 겪는 것**이고, 기반 클래스로 얻으면 된다. 그것을 얻으려고 서로 다른
+ * 대상을 한 화면에 묶으면 편의는 만드는 쪽이 가져가고 값은 쓰는 쪽이 치른다.
+ *
+ * ── MDI 에서도 갈려야 한다 ─────────────────────────────────────────────────
+ * MDI 탭은 페이지 **요소**로 나뉜다(`page-mdibar.ts`). 한 라우트면 인원과 설비를 나란히 열 수 없는데,
+ * 마스터 작업의 대부분이 두 항목을 비교하며 옮겨 적는 일이다. 품목을 보면서 품목 등급을 채운다.
+ *
+ * ── 이 클래스가 갖는 것과 갖지 않는 것 ─────────────────────────────────────
+ * 갖는 것: 화면 골격 · 컬럼 설정 · 가져오기 · 저장 · 컬럼 하나를 그리는 방식.
+ * 갖지 않는 것: **무엇을 보이나.** 그것은 각 화면이 `spec` 으로 말한다.
+ */
+export type MasterColumnType = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'list'
+/** 정해진 값 중에서 고른다. `options` 를 함께 준다. */
+ | 'select'
+/**
+ * ISO 8601 기간 — `PT30S`.
+ *
+ * 이름이 `duration` 이 아니다. 그 이름은 초 숫자용으로 이미 임자가 있다(`worklist`). 등록소를
+ * 앱 전체가 나눠 쓰므로, 이름이 겹치면 나중에 부팅한 쪽이 오류보고없이 이긴다.
+ */
+ | 'iso-duration'
+/** 다른 표의 이름 하나. `reference` 를 함께 준다. */
+ | 'reference' | 'reference-list';
+export interface MasterColumn {
+    name: string;
+    /** 화면 문구 키. `field.<이것>`. */
+    label: string;
+    type: MasterColumnType;
+    /**
+     * `select` 가 고를 값들.
+     *
+     * **여기에 손으로 적지 않는다.** `master-options.ts` 가 계약에서 가져오거나, 계약이 타입으로만
+     * 주는 것은 컴파일러가 계약에 묶은 거울에서 가져온다. 화면에 값을 베껴 적으면 커널이 값을 늘렸을
+     * 때 화면만 옛 목록을 보인다.
+     */
+    options?: readonly string[];
+    /**
+     * `reference` 가 어느 표에서 고르나.
+     *
+     * 저장되는 것은 **이름**이지 id 가 아니다 — 커널이 이름으로 주소를 잡는다.
+     */
+    reference?: ReferenceOptions;
+    width?: number;
+    /** 고칠 수 없는 칸. 자동으로 붙는 값이 여기 온다. */
+    readonly?: boolean;
+    /**
+     * 가로로 스크롤해도 화면에 남는 컬럼.
+     *
+     * 컬럼이 열 개를 넘고 폭 합이 1000px 을 넘는 축이 있다. 오른쪽 끝을 고치려고 스크롤하면 이름이 화면
+     * 밖으로 나가서 **어느 행을 고치는지 알 수 없다.**
+     */
+    fixed?: boolean;
+    /**
+     * 표에 그리지 않는다 — **검색에는 남는다.**
+     *
+     * 같은 사실을 두 번 보이지 않으려고 감추는 자리가 있다. 로케이션의 상위는 트리의 들여쓰기가 말하므로
+     * 컬럼으로 또 보일 필요가 없지만, 「LINE-1 아래 있는 것」을 찾는 일은 있다.
+     *
+     * `searchText` 는 `filter: 'search'` 를 선언한 컬럼마다 필터를 만들고 hidden 을 보지 않는다
+     * (`data-grist.ts` 의 `set searchText`). 그래서 감춘 컬럼도 검색에는 참여한다.
+     *
+     * 다만 컬럼 설정 목록에서는 **빠진다** — personalizer 가 페이지 설정의 hidden 을 걸러낸다
+     * (`ox-grist-personalizer.ts:51`). 사용자가 켜야 할 컬럼에는 쓰지 않는다.
+     */
+    hidden?: boolean;
+}
+/** 각 마스터 화면이 자기에 대해 말하는 것. */
+export interface MasterSpec {
+    /** 컬럼 설정을 사람마다 따로 저장하는 키. 화면마다 달라야 한다. */
+    key: string;
+    /**
+     * 이 화면이 다루는 마스터 축.
+     *
+     * **배정·선언 칸이 있는 축만 「언제부터」를 묻는다**(§`assignment-fields`). 안 적으면 안 묻는다 —
+     * 그 축에는 이력을 받는 칸이 없다는 뜻이다.
+     */
+    axis?: string;
+    /** 제목 문구 키. `title.<이것>`. */
+    title: string;
+    /**
+     * 도움말 문서 키 — `helps/<이것>.md`.
+     *
+     * `ox-page-title-bar` 가 이 값이 있으면 제목 옆에 도움말 아이콘을 그린다. 상세한 설명은 그 문서가
+     * 갖는다 — 화면에 형식적인 소개 문장을 붙이는 것은 자리만 차지하고 도움이 안 된다.
+     */
+    help: string;
+    /** GraphQL 조회 이름 — 서버가 낸 그대로. */
+    query: string;
+    /** GraphQL 저장 이름. */
+    mutation: string;
+    columns: MasterColumn[];
+}
+/** 열두 축이 공통으로 갖는 유효 기간 — ISA-95. */
+export declare const EFFECTIVE: MasterColumn[];
+/** 이름과 설명은 열두 축이 모두 갖는다. 이름은 스크롤해도 남는다. */
+export declare const IDENTITY: MasterColumn[];
+declare const MasterPageBase_base: (new (...args: any[]) => {
+    __preferenceProviders: {
+        [element: string]: import("@operato/p13n").PagePreferenceProvider;
+    };
+    getPagePreferenceProvider(element: string): import("@operato/p13n").PagePreferenceProvider | undefined;
+}) & (new (...args: any[]) => import("lit").LitElement) & typeof PageView;
+export declare abstract class MasterPageBase extends MasterPageBase_base {
+    static styles: import("lit").CSSResult[];
+    /** 이 화면이 자기에 대해 말하는 것. 화면마다 자기 것을 준다. */
+    protected abstract get spec(): MasterSpec;
+    active: boolean;
+    gristConfig: any;
+    mode: 'CARD' | 'LIST' | 'GRID';
+    protected ready: boolean;
+    protected grist: DataGrist;
+    get context(): {
+        title: string;
+        importable: {
+            handler: (records: any[]) => Promise<void>;
+        };
+        help: string;
+        search: {
+            handler: (search: string) => void;
+            value: string;
+        };
+        actions: {
+            title: string;
+            action: () => Promise<void>;
+            icon: string;
+            emphasis: {
+                raised: boolean;
+            };
+        }[];
+        exportable: {
+            name: string;
+            data: () => any[];
+        };
+    };
+    /**
+     * 지금 무엇을 보고 있는가 — 표 바로 위.
+     *
+     * 계층을 드릴다운으로 걷는 화면은 「어디를 보고 있나」를 말해야 한다. 대부분의 화면은 표 하나가 전부라
+     * 범위가 없다 — 그런 화면은 아무것도 그리지 않고, 그 줄이 접힌다.
+     */
+    protected renderScope(): import("lit-html").TemplateResult<1>;
+    /**
+     * 화면 골격 — 표 하나와 컬럼 설정.
+     *
+     * 자기 인터페이스가 필요한 화면은 이것을 덮어쓴다. 위치와 정지 사유는 계층이라 표가 아니라 나무여야
+     * 하고, 그때 이 render 를 쓰지 않는다.
+     */
+    render(): import("lit-html").TemplateResult<1>;
+    /**
+     * 주소 끝의 이름 조각을 **목록 좁히기**에 쓰나.
+     *
+     * 다른 화면의 참조 칸에서 걸어 들어오면 주소가 `.../ops-master-material-definition/M0161-0003` 이
+     * 된다. 그 조각을 아무도 안 읽으면 106줄짜리 목록 첫 장이 뜨고, 사람은 방금 누른 이름을 다시
+     * 찾아야 한다 — 걸어온 보람이 없다.
+     *
+     * 자리 화면과 제조법 화면은 그 조각을 **파고들기**에 이미 쓰고 있다(그 이름 아래를 보여 준다).
+     * 그 둘은 여기서 빠진다 — 두 뜻이 한 조각에 겹치면 어느 쪽도 제대로 안 된다.
+     */
+    protected get pathSegmentNarrowsList(): boolean;
+    pageInitialized(): Promise<void>;
+    /**
+     * 셸은 `(changes, after, before)` 를 넘긴다 — 인수 없는 모양으로 좁히면 주소를 읽어야 하는 화면이
+     * 이것을 덮어쓸 수 없다(`after.resourceId` 와 `before.resourceId` 를 비교하는 자리다).
+     */
+    pageUpdated(_changes?: any, _after?: any, _before?: any): Promise<void>;
+    protected configOf(): any;
+    protected columnOf(column: MasterColumn): {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            options?: undefined;
+            reference?: undefined;
+            editor?: undefined;
+            opensPopup?: undefined;
+        };
+        sortable: boolean;
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+        filter?: undefined;
+    } | {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            options?: undefined;
+            reference?: undefined;
+            editor?: undefined;
+            opensPopup?: undefined;
+        };
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+        sortable?: undefined;
+        filter?: undefined;
+    } | {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            options: readonly string[];
+            reference?: undefined;
+            editor?: undefined;
+            opensPopup?: undefined;
+        };
+        filter: string;
+        sortable: boolean;
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+    } | {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            reference: {
+                queryName?: string | undefined;
+                multiple?: boolean;
+                title: string;
+                columns?: {
+                    name: string;
+                    header?: string;
+                    width?: number;
+                }[];
+                valueField?: string;
+            };
+            options?: undefined;
+            editor?: undefined;
+            opensPopup?: undefined;
+        };
+        filter: string;
+        sortable: boolean;
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+    } | {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            editor: import("@operato/data-grist").FieldEditor;
+            opensPopup: boolean;
+            reference: {
+                queryName?: string | undefined;
+                multiple: boolean;
+                title: string;
+                columns?: {
+                    name: string;
+                    header?: string;
+                    width?: number;
+                }[];
+                valueField?: string;
+            };
+            options?: undefined;
+        };
+        sortable: boolean;
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+        filter?: undefined;
+    } | {
+        type: string;
+        name: string;
+        header: string;
+        record: {
+            editable: boolean;
+            options?: undefined;
+            reference?: undefined;
+            editor?: undefined;
+            opensPopup?: undefined;
+        };
+        filter: string;
+        sortable: boolean;
+        width: number | undefined;
+        fixed: boolean | undefined;
+        hidden: boolean | undefined;
+    };
+    fetchHandler({ page, limit, sortings, filters }: FetchOption): Promise<{
+        total: any;
+        records: any;
+    }>;
+    /**
+     * JSON 칸을 **사람이 고칠 수 있는 글자로 편다.**
+     *
+     * 서버는 구조를 구조로 낸다(`ScalarObject` 로 선언하지만 **스키마에 나가는 이름은 `Object`** 다) — 그것이
+   * 사실이고, 곧 붙을 전용 편집기가 원하는 모양이다.
+     * 그런데 지금 이 그리드의 JSON 칸은 글자 편집기라 객체를 그대로 주면 `[object Object]` 가 된다.
+     * 그래서 **화면에 들어올 때만** 편다. 스키마를 화면 사정에 맞추지 않고, 화면이 자기 몫을 한다.
+     *
+     * 이 옮김은 `packJson` 과 짝이다. 한쪽만 고치면 저장이 오류보고없이 망가진다.
+     */
+    protected spreadJson(item: any): any;
+    /**
+     * 저장하기 전에 JSON 칸의 글자를 **구조로 되읽는다.**
+     *
+     * 읽지 못하면 **보내지 않는다.** 그냥 보내면 글자가 통째로 값이 되어, 사람이 적은 구조가 사라진 채로
+     * 저장이 성공했다고 나온다. 어느 행 어느 칸인지 말해 주어야 고칠 수 있다.
+     */
+    protected packJson(patches: any[]): {
+        patches: any[];
+        problems: string[];
+    };
+    /**
+     * 파일로 올린 줄들을 이 화면의 마스터로 넣는다.
+     *
+     * ── 오류보고없이 버리지 않는다 ─────────────────────────────────────────────────
+     * 모르는 열 이름, 이름이 없는 줄, 중복된 이름을 **알린다.** 오류보고없이 빼면 사람은 다 올라간 줄 알고,
+     * 빠진 것은 나중에 「그 설비가 왜 없지」로 나타난다.
+     *
+     * ── 하나라도 틀리면 아무것도 안 보낸다 ───────────────────────────────────
+     * 절반만 들어가면 무엇이 들어갔는지 사람이 모른다. 파일을 고쳐 다시 올리는 편이 낫다.
+     *
+     * ── 새로 만들 것과 고칠 것을 이름으로 구분한다 ─────────────────────────────
+     * 서버는 `+`(새로)와 `M`(고침, id 필요)을 나눠 받는다. 그러니 **올리기 전에 그 이름들이 이미
+     * 있는지 물어야 한다.** 안 물으면 같은 이름이 두 벌 생긴다.
+     */
+    protected importHandler(records: any[]): Promise<void>;
+    /**
+     * 파일의 머리글을 이 화면의 열 이름으로 바꾼다.
+     *
+     * **두 가지를 다 받는다** — 열 이름 그대로(`homeLocation`)와 화면에 보이는 말(`홈 자리`).
+     * 사람이 이 화면에서 내려받아 고쳐 올리면 머리글이 화면의 말이고, 다른 시스템에서 뽑아 오면
+     * 열 이름이다. 한쪽만 받으면 다른 쪽이 통째로 「모르는 열」이 된다.
+     */
+    /** 무엇이 잘못됐는지를 사람에게 보일 문장으로 바꾼다. 줄 번호는 엑셀에서 보는 그 번호다. */
+    private sayProblem;
+    private headerIndex;
+    /** 이 이름들이 이미 있나 — 있으면 그 `id`. 없는 이름은 지도에 없다. */
+    private idsByName;
+    /** 「언제부터」를 묻는다. 사람이 그만두면 `undefined` 이고, 그때는 **아무것도 안 보낸다.** */
+    protected askAppliedWhen(changes: AssignmentChange[]): Promise<AppliedAnswer | undefined>;
+    protected save(): Promise<void>;
+}
+export {};