From 1e71bdcfee87d8a9ea7f14650346239a08aa5a67 Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Thu, 22 Oct 2026 14:57:31 +0900 Subject: [PATCH] =?UTF-8?q?261022=5F02=5FENH:=20=EB=B0=9C=EC=86=A1=20?= =?UTF-8?q?=EC=B7=A8=EC=86=8C=EC=97=90=20=EB=8C=80=ED=95=9C=20=ED=83=80?= =?UTF-8?q?=EC=9E=85=20=EC=B6=94=EA=B0=80=EC=99=80=20=ED=97=AC=ED=8D=BC=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/consumer.md | 10 +++++ AGENTS.md | 19 ++++++++++ package-lock.json | 4 +- package.json | 2 +- src/noti-hub/index.ts | 3 +- src/noti-hub/noti-hub-types.ts | 62 +++++++++++++++++++++++++++++++ src/noti-hub/send-cancellation.ts | 58 +++++++++++++++++++++++++++++ 7 files changed, 154 insertions(+), 4 deletions(-) create mode 100644 src/noti-hub/send-cancellation.ts diff --git a/.agent/consumer.md b/.agent/consumer.md index af2543c..cf981dc 100644 --- a/.agent/consumer.md +++ b/.agent/consumer.md @@ -17,6 +17,16 @@ Before each related task, read the current contents of every matching reference, If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead. +## Noti-hub Reservation Cancellation + +- Import cancellation types, constants, and helpers from `@kri/common/noti-hub` only. They are runtime-neutral and require no optional peers. +- Individual current cancellation state is determined by resultCode via isReserveCanceledResult; bulk current state is cancellationStatus (NONE/PARTIAL/ALL). cancelDt and cancelUser are request history, not current state. +- sendIdx is the single-cancel identifier, not cmid. It is absent from the latest abbreviated report (/api/v1/report/last/send/...). Request sendIdx must be a positive integer; bulkSendKey is required and at most 32 characters. +- EMAIL_RESERVE_CANCELED_RESULT_CODE is 108 for EMAIL. SMS_KKO_RESERVE_CANCELED_RESULT_CODE is 9998 for SMS, LMS_MMS, and KKO. Unknown message types are not recognized as canceled. +- Display the server's resultViewLabel/resultLabel ("예약 취소"). There is no separate result-code list API. +- HTTP 200 can contain notCancelableCount. parseSendCancelResponse validates nonnegative integer counts and targetCount = canceledCount + alreadyCanceledCount + notCancelableCount, throwing TypeError on invalid data. Bulk targetCount counts currently registered detail rows; response canceledCount counts only cancellations made by that request. +- Existing response fields are unchanged; all added fields on existing types are optional. Verify with npm run typecheck and npm run build. + ## HTTP Streaming - `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body). diff --git a/AGENTS.md b/AGENTS.md index 2b28406..fe4ddd8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -253,6 +253,25 @@ Before each related task, read the current contents of every matching reference, If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead. +## Noti-hub Reservation Cancellation + +- Import cancellation types, constants, and helpers from `@kri/common/noti-hub` only. They are runtime-neutral and require no optional peers. +- Individual current cancellation state is determined by resultCode via isReserveCanceledResult; bulk current state is cancellationStatus (NONE/PARTIAL/ALL). cancelDt and cancelUser are request history, not current state. +- sendIdx is the single-cancel identifier, not cmid. It is absent from the latest abbreviated report (/api/v1/report/last/send/...). Request sendIdx must be a positive integer; bulkSendKey is required and at most 32 characters. +- EMAIL_RESERVE_CANCELED_RESULT_CODE is 108 for EMAIL. SMS_KKO_RESERVE_CANCELED_RESULT_CODE is 9998 for SMS, LMS_MMS, and KKO. Unknown message types are not recognized as canceled. +- Display the server's resultViewLabel/resultLabel ("예약 취소"). There is no separate result-code list API. +- HTTP 200 can contain notCancelableCount. parseSendCancelResponse validates nonnegative integer counts and targetCount = canceledCount + alreadyCanceledCount + notCancelableCount, throwing TypeError on invalid data. Bulk targetCount counts currently registered detail rows; response canceledCount counts only cancellations made by that request. +- Existing response fields are unchanged; all added fields on existing types are optional. Verify with npm run typecheck and npm run build. + +## HTTP Streaming + +- `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body). +- Streaming shares ordinary authentication, URL, body and HTTP-error policy. Read body incrementally; no automatic JSON/NDJSON/SSE parsing or reconnect is performed. +- Streaming options accept an external AbortSignal. Caller cancellation raises AbortError without an HTTP error notification. Cancel the body when it will not be consumed. +- timeoutMs covers connection/headers (and an HTTP error body); idleTimeoutMs covers inactivity after successful headers and resets on consumed chunks. Both default to the client's defaultTimeoutMs (60 seconds by default), and 0 disables that timer for streaming only. +- Mid-stream transport/time-out errors reach the body reader. HTTP error statuses use existing HttpError handlers before a stream is returned. A 204 response has body=null. +- See HTTP_STREAMING.md for examples and node --test tests/http-stream.test.mjs for focused validation after npm run build. + # KriFrontCommon Project Instruction Router ## Required Project References diff --git a/package-lock.json b/package-lock.json index 9dfe781..63b01a5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@kri/common", - "version": "0.19.0", + "version": "0.19.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@kri/common", - "version": "0.19.0", + "version": "0.19.3", "license": "UNLICENSED", "dependencies": { "clsx": "^2.1.1", diff --git a/package.json b/package.json index 93827d8..4c0a015 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kri/common", - "version": "0.19.2", + "version": "0.19.3", "description": "KRI 프런트엔드 공통 유틸리티", "type": "module", "main": "./dist/index.js", diff --git a/src/noti-hub/index.ts b/src/noti-hub/index.ts index b855065..20f1ca6 100644 --- a/src/noti-hub/index.ts +++ b/src/noti-hub/index.ts @@ -1,2 +1,3 @@ export * from './noti-hub-types.js'; -export * from './kko-template.js'; \ No newline at end of file +export * from './kko-template.js'; +export * from './send-cancellation.js'; \ No newline at end of file diff --git a/src/noti-hub/noti-hub-types.ts b/src/noti-hub/noti-hub-types.ts index f4288d5..3d41f80 100644 --- a/src/noti-hub/noti-hub-types.ts +++ b/src/noti-hub/noti-hub-types.ts @@ -169,6 +169,36 @@ export type BulkSendResult = { failedChunks?: BulkSendFailedChunk[]; }; +/** 벌크의 현재 취소 상태. cancelDt 이력과 구분한다. */ +export type SendCancellationStatus = 'NONE' | 'PARTIAL' | 'ALL'; + +/** POST /api/v1/message-send/cancel/single 요청. */ +export type SendCancelSingleRequest = { + /** 필수 양의 정수. cmid가 아닌 개별 발송 식별자. */ + sendIdx: number; +}; + +/** POST /api/v1/message-send/cancel/bulk 요청. */ +export type SendCancelBulkRequest = { + /** 필수 벌크 발송 키. 최대 32자. */ + bulkSendKey: string; +}; + +/** + * 단건·벌크 공통 취소 응답. 취소 불가 건이 있어도 HTTP 200일 수 있다. + * 항상 targetCount = canceledCount + alreadyCanceledCount + notCancelableCount. + */ +export type SendCancelResponse = { + /** 대상 건수. 벌크는 현재 등록된 상세 행 기준. */ + targetCount: number; + /** 이번 요청에서 취소한 건수. */ + canceledCount: number; + /** 이미 취소 상태인 건수. */ + alreadyCanceledCount: number; + /** 발송 시작·완료 등으로 취소하지 못한 건수. */ + notCancelableCount: number; +}; + export type SendResultSummaryRequest = { bulkSendKey?: string; itrntPrjctCd?: string; @@ -184,6 +214,7 @@ export type SendResultSummaryResponse = { successCount?: number; failCount?: number; standByCount?: number; + canceledCount?: number; totalCount?: number; price?: number; cost?: number; @@ -195,7 +226,16 @@ export type BulkSendDetailResponse = PageResponse; export type ReportExcelResponse = FileResponse; +/** 현재 취소 상태는 cancellationStatus로 판단하며 cancelDt만으로 판단하지 않는다. */ export type BulkSendInfo = { + /** 벌크 취소 요청자 이력. */ + cancelUser?: string; + /** 벌크 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */ + cancelDt?: string; + /** 현재 취소 상태인 상세 건수. */ + canceledCount?: number; + /** 벌크의 현재 취소 상태. */ + cancellationStatus?: SendCancellationStatus; bulkSendKey: string; reqstSvc: string; prjctCd: string; @@ -211,7 +251,17 @@ export type BulkSendInfo = { regDt?: string; }; +/** + * 개별 건의 현재 취소 상태는 resultCode로 판단한다. + * 표시명은 서버의 resultLabel을 그대로 사용한다("예약 취소"). 별도 결과 코드 목록 API는 없다. + */ export type SendInfo = { + /** 개별 취소 식별자. cmid가 아니다. */ + sendIdx?: number; + /** 취소 요청자. */ + cancelUser?: string; + /** 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */ + cancelDt?: string; cmid: string; bulkSendKey?: string; sendTyCode: number; @@ -236,7 +286,19 @@ export type SendInfo = { regDt: string; }; +/** + * 개별 건의 현재 취소 상태는 resultCode로 판단한다. + * 최신 발송 축약 조회(/api/v1/report/last/send/...)에는 sendIdx가 없다. + * 표시명은 서버의 resultViewLabel/resultLabel을 그대로 사용한다("예약 취소"). + * 별도 결과 코드 목록 API는 없다. + */ export type SendResultInfo = { + /** 개별 취소 식별자. cmid가 아니다. 최신 발송 축약 조회에는 제공되지 않는다. */ + sendIdx?: number; + /** 취소 요청자. */ + cancelUser?: string; + /** 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */ + cancelDt?: string; cmid: string; bulkSendKey?: string; /** MessageType 코드 */ diff --git a/src/noti-hub/send-cancellation.ts b/src/noti-hub/send-cancellation.ts new file mode 100644 index 0000000..a6a6f95 --- /dev/null +++ b/src/noti-hub/send-cancellation.ts @@ -0,0 +1,58 @@ +import { MessageType } from "./noti-hub-types.js"; +import type { SendCancelResponse, SendResultInfo } from "./noti-hub-types.js"; + +/** 이메일 예약 취소 결과 코드. */ +export const EMAIL_RESERVE_CANCELED_RESULT_CODE = 108; + +/** 문자(SMS, LMS_MMS)·알림톡(KKO) 예약 취소 결과 코드. */ +export const SMS_KKO_RESERVE_CANCELED_RESULT_CODE = 9998; + +/** + * 채널과 resultCode로 개별 건의 현재 예약 취소 상태를 판단한다. + * cancelDt는 요청 이력이므로 상태 판정에 사용하지 않는다. 알 수 없는 채널은 false. + * 표시명은 서버의 resultViewLabel/resultLabel을 그대로 사용한다("예약 취소"). + * 별도 결과 코드 목록 API는 없다. + */ +export const isReserveCanceledResult = ( + result: Pick, +): boolean => { + switch (result.sendTy) { + case MessageType.EMAIL: + return result.resultCode === EMAIL_RESERVE_CANCELED_RESULT_CODE; + case MessageType.SMS: + case MessageType.LMS_MMS: + case MessageType.KKO: + return result.resultCode === SMS_KKO_RESERVE_CANCELED_RESULT_CODE; + default: + return false; + } +}; + +const isCount = (value: unknown): value is number => + typeof value === "number" && Number.isInteger(value) && value >= 0; + +/** + * 취소 응답의 각 건수가 0 이상 정수이고 합계 관계가 맞는지 검증한다. + * HTTP 200이어도 취소 불가 건이 있을 수 있으며, 벌크 대상은 현재 등록된 상세 행 기준이다. + * @throws {TypeError} 응답 형태, 건수 또는 합계가 올바르지 않을 때. + */ +export const parseSendCancelResponse = (value: unknown): SendCancelResponse => { + if ( + typeof value !== "object" || value === null || Array.isArray(value) || + !("targetCount" in value) || !("canceledCount" in value) || + !("alreadyCanceledCount" in value) || !("notCancelableCount" in value) + ) { + throw new TypeError("Invalid send cancellation response"); + } + + const { targetCount, canceledCount, alreadyCanceledCount, notCancelableCount } = value; + if ( + !isCount(targetCount) || !isCount(canceledCount) || + !isCount(alreadyCanceledCount) || !isCount(notCancelableCount) || + targetCount !== canceledCount + alreadyCanceledCount + notCancelableCount + ) { + throw new TypeError("Invalid send cancellation counts or total"); + } + + return { targetCount, canceledCount, alreadyCanceledCount, notCancelableCount }; +};