261022_02_ENH: 발송 취소에 대한 타입 추가와 헬퍼 추가

This commit is contained in:
2026-10-22 14:57:31 +09:00
parent 5778deac9e
commit 1e71bdcfee
7 changed files with 154 additions and 4 deletions

View File

@@ -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. 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 ## HTTP Streaming
- `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body). - `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body).

View File

@@ -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. 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 # KriFrontCommon Project Instruction Router
## Required Project References ## Required Project References

4
package-lock.json generated
View File

@@ -1,12 +1,12 @@
{ {
"name": "@kri/common", "name": "@kri/common",
"version": "0.19.0", "version": "0.19.3",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "@kri/common", "name": "@kri/common",
"version": "0.19.0", "version": "0.19.3",
"license": "UNLICENSED", "license": "UNLICENSED",
"dependencies": { "dependencies": {
"clsx": "^2.1.1", "clsx": "^2.1.1",

View File

@@ -1,6 +1,6 @@
{ {
"name": "@kri/common", "name": "@kri/common",
"version": "0.19.2", "version": "0.19.3",
"description": "KRI 프런트엔드 공통 유틸리티", "description": "KRI 프런트엔드 공통 유틸리티",
"type": "module", "type": "module",
"main": "./dist/index.js", "main": "./dist/index.js",

View File

@@ -1,2 +1,3 @@
export * from './noti-hub-types.js'; export * from './noti-hub-types.js';
export * from './kko-template.js'; export * from './kko-template.js';
export * from './send-cancellation.js';

View File

@@ -169,6 +169,36 @@ export type BulkSendResult = {
failedChunks?: BulkSendFailedChunk[]; 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 = { export type SendResultSummaryRequest = {
bulkSendKey?: string; bulkSendKey?: string;
itrntPrjctCd?: string; itrntPrjctCd?: string;
@@ -184,6 +214,7 @@ export type SendResultSummaryResponse = {
successCount?: number; successCount?: number;
failCount?: number; failCount?: number;
standByCount?: number; standByCount?: number;
canceledCount?: number;
totalCount?: number; totalCount?: number;
price?: number; price?: number;
cost?: number; cost?: number;
@@ -195,7 +226,16 @@ export type BulkSendDetailResponse = PageResponse<SendInfo>;
export type ReportExcelResponse = FileResponse; export type ReportExcelResponse = FileResponse;
/** 현재 취소 상태는 cancellationStatus로 판단하며 cancelDt만으로 판단하지 않는다. */
export type BulkSendInfo = { export type BulkSendInfo = {
/** 벌크 취소 요청자 이력. */
cancelUser?: string;
/** 벌크 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */
cancelDt?: string;
/** 현재 취소 상태인 상세 건수. */
canceledCount?: number;
/** 벌크의 현재 취소 상태. */
cancellationStatus?: SendCancellationStatus;
bulkSendKey: string; bulkSendKey: string;
reqstSvc: string; reqstSvc: string;
prjctCd: string; prjctCd: string;
@@ -211,7 +251,17 @@ export type BulkSendInfo = {
regDt?: string; regDt?: string;
}; };
/**
* 개별 건의 현재 취소 상태는 resultCode로 판단한다.
* 표시명은 서버의 resultLabel을 그대로 사용한다("예약 취소"). 별도 결과 코드 목록 API는 없다.
*/
export type SendInfo = { export type SendInfo = {
/** 개별 취소 식별자. cmid가 아니다. */
sendIdx?: number;
/** 취소 요청자. */
cancelUser?: string;
/** 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */
cancelDt?: string;
cmid: string; cmid: string;
bulkSendKey?: string; bulkSendKey?: string;
sendTyCode: number; sendTyCode: number;
@@ -236,7 +286,19 @@ export type SendInfo = {
regDt: string; regDt: string;
}; };
/**
* 개별 건의 현재 취소 상태는 resultCode로 판단한다.
* 최신 발송 축약 조회(/api/v1/report/last/send/...)에는 sendIdx가 없다.
* 표시명은 서버의 resultViewLabel/resultLabel을 그대로 사용한다("예약 취소").
* 별도 결과 코드 목록 API는 없다.
*/
export type SendResultInfo = { export type SendResultInfo = {
/** 개별 취소 식별자. cmid가 아니다. 최신 발송 축약 조회에는 제공되지 않는다. */
sendIdx?: number;
/** 취소 요청자. */
cancelUser?: string;
/** 취소 요청 일시 이력. 현재 상태 판정에 사용하지 않는다. */
cancelDt?: string;
cmid: string; cmid: string;
bulkSendKey?: string; bulkSendKey?: string;
/** MessageType 코드 */ /** MessageType 코드 */

View File

@@ -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<SendResultInfo, "sendTy" | "resultCode">,
): 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 };
};