@exabugs/dynamodb-client 1.11.3 → 1.12.0

package/dist/server/utils/errorHandler.d.ts

@@ -7,6 +7,12 @@ import type { APIGatewayProxyResultV2 } from 'aws-lambda';
 /**
  * エラーをハンドリングしてレスポンスを生成する
  *
+ * ログ出力自体はcreateErrorResponseが一元的に行う（ステータスコードに応じた
+ * レベル分け・eventの付与も含む）。ここで個別にログを出すと、同じエラーが
+ * 二重に記録されたり、最終的なステータスコードが決まる前にerrorレベルで
+ * 出てしまう（4xxなのにerror扱いになる）。例外的にスタックトレースだけは、
+ * 原因不明な500の診断に必須なためlogContextとして個別に渡す。
+ *
  * @param error - エラーオブジェクト
  * @param requestId - リクエストID
  * @returns HTTPレスポンス

package/dist/server/utils/errorHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../src/server/utils/errorHandler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAe1D;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAsEtF"}
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../src/server/utils/errorHandler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAO1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAgEtF"}

package/dist/server/utils/errorHandler.js

@@ -1,17 +1,16 @@
 import { HTTP_STATUS } from '../../shared/constants/http.js';
 import { VALIDATION_ERROR_PATTERNS } from '../../shared/constants/validation.js';
-import { ErrorCode, createLogger, isAppError } from '../../shared/index.js';
+import { ErrorCode, isAppError } from '../../shared/index.js';
 import { createErrorResponse } from './responseBuilder.js';
-/**
- * ロガーインスタンス
- */
-const logger = createLogger({
-    service: 'error-handler',
-    level: process.env.LOG_LEVEL || 'info',
-});
 /**
  * エラーをハンドリングしてレスポンスを生成する
  *
+ * ログ出力自体はcreateErrorResponseが一元的に行う（ステータスコードに応じた
+ * レベル分け・eventの付与も含む）。ここで個別にログを出すと、同じエラーが
+ * 二重に記録されたり、最終的なステータスコードが決まる前にerrorレベルで
+ * 出てしまう（4xxなのにerror扱いになる）。例外的にスタックトレースだけは、
+ * 原因不明な500の診断に必須なためlogContextとして個別に渡す。
+ *
  * @param error - エラーオブジェクト
  * @param requestId - リクエストID
  * @returns HTTPレスポンス
@@ -23,12 +22,6 @@ export function handleError(error, requestId) {
     }
     // 標準Errorの場合
     if (error instanceof Error) {
-        // スタックトレースをログ出力
-        logger.error('Error stack trace', {
-            requestId,
-            stack: error.stack,
-            message: error.message,
-        });
         // バリデーションエラーの判定
         if (isValidationError(error.message)) {
             return createErrorResponse(ErrorCode.VALIDATION_ERROR, error.message, HTTP_STATUS.BAD_REQUEST, requestId);
@@ -41,8 +34,8 @@ export function handleError(error, requestId) {
         if (error.message.includes('Unknown operation')) {
             return createErrorResponse(ErrorCode.INVALID_OPERATION, error.message, HTTP_STATUS.BAD_REQUEST, requestId);
         }
-        // その他のエラー
-        return createErrorResponse(ErrorCode.INTERNAL_ERROR, error.message, HTTP_STATUS.INTERNAL_SERVER_ERROR, requestId);
+        // その他のエラー（原因不明の500。スタックトレースをログに残す）
+        return createErrorResponse(ErrorCode.INTERNAL_ERROR, error.message, HTTP_STATUS.INTERNAL_SERVER_ERROR, requestId, { stack: error.stack });
     }
     // 予期しないエラー
     return createErrorResponse(ErrorCode.UNKNOWN_ERROR, 'An unexpected error occurred', HTTP_STATUS.INTERNAL_SERVER_ERROR, requestId, {

package/dist/server/utils/errorHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../../src/server/utils/errorHandler.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,GAAG,YAAY,CAAC;IAC1B,OAAO,EAAE,eAAe;IACxB,KAAK,EAAG,OAAO,CAAC,GAAG,CAAC,SAAiD,IAAI,MAAM;CAChF,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,SAAiB;IAC3D,6BAA6B;IAC7B,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,mBAAmB,CACxB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,UAAU,EAChB,SAAS,EACT,KAAK,CAAC,OAAO,CACd,CAAC;IACJ,CAAC;IAED,aAAa;IACb,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,gBAAgB;QAChB,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE;YAChC,SAAS;YACT,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;QAEH,gBAAgB;QAChB,IAAI,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,OAAO,mBAAmB,CACxB,SAAS,CAAC,gBAAgB,EAC1B,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,WAAW,EACvB,SAAS,CACV,CAAC;QACJ,CAAC;QAED,YAAY;QACZ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAClD,OAAO,mBAAmB,CACxB,SAAS,CAAC,eAAe,EACzB,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,eAAe,EAC3B,SAAS,CACV,CAAC;QACJ,CAAC;QAED,cAAc;QACd,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAChD,OAAO,mBAAmB,CACxB,SAAS,CAAC,iBAAiB,EAC3B,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,WAAW,EACvB,SAAS,CACV,CAAC;QACJ,CAAC;QAED,UAAU;QACV,OAAO,mBAAmB,CACxB,SAAS,CAAC,cAAc,EACxB,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,qBAAqB,EACjC,SAAS,CACV,CAAC;IACJ,CAAC;IAED,WAAW;IACX,OAAO,mBAAmB,CACxB,SAAS,CAAC,aAAa,EACvB,8BAA8B,EAC9B,WAAW,CAAC,qBAAqB,EACjC,SAAS,EACT;QACE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;KACrB,CACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,OAAe;IACxC,OAAO,yBAAyB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAChF,CAAC"}
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../../src/server/utils/errorHandler.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,SAAiB;IAC3D,6BAA6B;IAC7B,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,mBAAmB,CACxB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,UAAU,EAChB,SAAS,EACT,KAAK,CAAC,OAAO,CACd,CAAC;IACJ,CAAC;IAED,aAAa;IACb,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,gBAAgB;QAChB,IAAI,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,OAAO,mBAAmB,CACxB,SAAS,CAAC,gBAAgB,EAC1B,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,WAAW,EACvB,SAAS,CACV,CAAC;QACJ,CAAC;QAED,YAAY;QACZ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAClD,OAAO,mBAAmB,CACxB,SAAS,CAAC,eAAe,EACzB,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,eAAe,EAC3B,SAAS,CACV,CAAC;QACJ,CAAC;QAED,cAAc;QACd,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAChD,OAAO,mBAAmB,CACxB,SAAS,CAAC,iBAAiB,EAC3B,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,WAAW,EACvB,SAAS,CACV,CAAC;QACJ,CAAC;QAED,mCAAmC;QACnC,OAAO,mBAAmB,CACxB,SAAS,CAAC,cAAc,EACxB,KAAK,CAAC,OAAO,EACb,WAAW,CAAC,qBAAqB,EACjC,SAAS,EACT,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CACvB,CAAC;IACJ,CAAC;IAED,WAAW;IACX,OAAO,mBAAmB,CACxB,SAAS,CAAC,aAAa,EACvB,8BAA8B,EAC9B,WAAW,CAAC,qBAAqB,EACjC,SAAS,EACT;QACE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;KACrB,CACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,OAAe;IACxC,OAAO,yBAAyB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/dist/server/utils/responseBuilder.d.ts

@@ -15,14 +15,20 @@ export declare function createSuccessResponse(data: unknown, requestId: string):
 /**
  * エラーレスポンスを生成する
  *
+ * `logContext`はログにのみ使う（クライアントへのレスポンスには含めない）。
+ * 例外オブジェクトは「何が起きたか」の診断情報を持つだけで、それを外部に
+ * どう見せるか（レスポンスボディの形）はこの関数の責務であり、呼び出し元の
+ * 判断を自動的に継承しない（過去にdetailsを無条件にレスポンスへ転記していた
+ * ことがあったが、使われていなかった上に責務が混同されていたため廃止した）。
+ *
  * @param code - エラーコード
  * @param message - エラーメッセージ
  * @param statusCode - HTTPステータスコード
  * @param requestId - リクエストID
- * @param details - 追加詳細情報
+ * @param logContext - ログにのみ出す診断情報（resource/id等。レスポンスには出ない）
  * @returns HTTPレスポンス
  */
-export declare function createErrorResponse(code: string, message: string, statusCode: number, requestId: string, details?: unknown): APIGatewayProxyResultV2;
+export declare function createErrorResponse(code: string, message: string, statusCode: number, requestId: string, logContext?: Record<string, unknown>): APIGatewayProxyResultV2;
 /**
  * CORSレスポンスを生成する
  *

package/dist/server/utils/responseBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responseBuilder.d.ts","sourceRoot":"","sources":["../../../src/server/utils/responseBuilder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAoB1D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAgB/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,OAAO,GAChB,uBAAuB,CAgCzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,uBAAuB,CAM9E"}
+{"version":3,"file":"responseBuilder.d.ts","sourceRoot":"","sources":["../../../src/server/utils/responseBuilder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAoB1D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAgB/F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,uBAAuB,CA8BzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,uBAAuB,CAM9E"}

package/dist/server/utils/responseBuilder.js

@@ -37,26 +37,30 @@ export function createSuccessResponse(data, requestId) {
 /**
  * エラーレスポンスを生成する
  *
+ * `logContext`はログにのみ使う（クライアントへのレスポンスには含めない）。
+ * 例外オブジェクトは「何が起きたか」の診断情報を持つだけで、それを外部に
+ * どう見せるか（レスポンスボディの形）はこの関数の責務であり、呼び出し元の
+ * 判断を自動的に継承しない（過去にdetailsを無条件にレスポンスへ転記していた
+ * ことがあったが、使われていなかった上に責務が混同されていたため廃止した）。
+ *
  * @param code - エラーコード
  * @param message - エラーメッセージ
  * @param statusCode - HTTPステータスコード
  * @param requestId - リクエストID
- * @param details - 追加詳細情報
+ * @param logContext - ログにのみ出す診断情報（resource/id等。レスポンスには出ない）
  * @returns HTTPレスポンス
  */
-export function createErrorResponse(code, message, statusCode, requestId, details) {
+export function createErrorResponse(code, message, statusCode, requestId, logContext) {
     const response = {
         success: false,
         error: {
             code,
             message,
             statusCode,
-            details,
         },
     };
     // 4xx（クライアント起因。存在しないIDの参照など、日常的に起きうる想定内の失敗）はwarn、
     // 5xx（サーバー起因の障害）はerrorにする。eventにはcode（例: ITEM_NOT_FOUND）を入れる。
-    // detailsにresource/id等の文脈が入っている場合はログにも残す（原因特定に必須）。
     // 詳細: docs/NOTIFY.md（eventが無いと通知の重複抑制がIDの数だけ指紋を作ってしまう）
     const level = statusCode >= 500 ? 'error' : 'warn';
     logger[level]('Request failed', {
@@ -64,7 +68,7 @@ export function createErrorResponse(code, message, statusCode, requestId, detail
         event: code,
         message,
         statusCode,
-        ...(details !== undefined && details !== null ? { details } : {}),
+        ...(logContext ?? {}),
     });
     return {
         statusCode,

package/dist/server/utils/responseBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"responseBuilder.js","sourceRoot":"","sources":["../../../src/server/utils/responseBuilder.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD;;GAEG;AACH,MAAM,MAAM,GAAG,YAAY,CAAC;IAC1B,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAG,OAAO,CAAC,GAAG,CAAC,SAAiD,IAAI,MAAM;CAChF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa,EAAE,SAAiB;IACpE,MAAM,QAAQ,GAAgC;QAC5C,OAAO,EAAE,IAAI;QACb,IAAI;KACL,CAAC;IAEF,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAEhD,OAAO;QACL,UAAU,EAAE,WAAW,CAAC,EAAE;QAC1B,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,YAAY;SAChB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,OAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,OAAiB;IAEjB,MAAM,QAAQ,GAAqB;QACjC,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI;YACJ,OAAO;YACP,UAAU;YACV,OAAO;SACR;KACF,CAAC;IAEF,kDAAkD;IAClD,8DAA8D;IAC9D,mDAAmD;IACnD,uDAAuD;IACvD,MAAM,KAAK,GAAG,UAAU,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,MAAM,CAAC,KAAK,CAAC,CAAC,gBAAgB,EAAE;QAC9B,SAAS;QACT,KAAK,EAAE,IAAI;QACX,OAAO;QACP,UAAU;QACV,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC,CAAC;IAEH,OAAO;QACL,UAAU;QACV,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,YAAY;SAChB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO;QACL,UAAU;QACV,OAAO,EAAE,YAAY;QACrB,IAAI,EAAE,EAAE;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"responseBuilder.js","sourceRoot":"","sources":["../../../src/server/utils/responseBuilder.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGrD;;GAEG;AACH,MAAM,MAAM,GAAG,YAAY,CAAC;IAC1B,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAG,OAAO,CAAC,GAAG,CAAC,SAAiD,IAAI,MAAM;CAChF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa,EAAE,SAAiB;IACpE,MAAM,QAAQ,GAAgC;QAC5C,OAAO,EAAE,IAAI;QACb,IAAI;KACL,CAAC;IAEF,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAEhD,OAAO;QACL,UAAU,EAAE,WAAW,CAAC,EAAE;QAC1B,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,YAAY;SAChB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,OAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,UAAoC;IAEpC,MAAM,QAAQ,GAAqB;QACjC,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI;YACJ,OAAO;YACP,UAAU;SACX;KACF,CAAC;IAEF,kDAAkD;IAClD,8DAA8D;IAC9D,uDAAuD;IACvD,MAAM,KAAK,GAAG,UAAU,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,MAAM,CAAC,KAAK,CAAC,CAAC,gBAAgB,EAAE;QAC9B,SAAS;QACT,KAAK,EAAE,IAAI;QACX,OAAO;QACP,UAAU;QACV,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;KACtB,CAAC,CAAC;IAEH,OAAO;QACL,UAAU;QACV,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,YAAY;SAChB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO;QACL,UAAU;QACV,OAAO,EAAE,YAAY;QACrB,IAAI,EAAE,EAAE;KACT,CAAC;AACJ,CAAC"}

package/docs/NOTIFY.md

@@ -24,7 +24,7 @@ JSON 1 行。`level`（`debug` / `info` / `warn` / `error` / `fatal`）、`messa
 
 ## Notice
 
-外部へ送るのは、許可したフィールドだけ（`level` / `event` / `message` / `app` / `env` / `target` / `action` / `occurredAt` / `suppressed`）。文字数を制限し、制御文字を除く。ログ全体は転送しない。
+外部へ送るのは、許可したフィールドだけ（`level` / `event` / `message` / `app` / `env` / `target` / `action` / `occurredAt` / `suppressed`。alerts を有効にしたときは `detailUrl` も）。文字数を制限し、制御文字を除く。ログ全体は転送しない。
 
 ## 重複抑制と流量制限
 
@@ -101,3 +101,83 @@ export const handler = createNotifyHandler({
 - アラームは、ログを出さないもの（Lambda の Errors / Throttles、DynamoDB のスロットル、WAF など）に使う。ログと同じ事象（SPARSE_SCAN など）をアラームでも通知すると二重になる
 - Lambda の非同期の再試行は 0 にする（重複を避ける。失敗は失敗先で受ける）
 - SES の送信元ドメインは、検証と本番アクセスが済んだリージョンのものを使う
+
+## alerts（通知を管理画面のレコードとして残す）
+
+任意の機能（[ADR 0003](adr/0003-alerts.md)）。`recorder` を渡したときだけ動き、渡さなければ従来と何も変わらない。通知を、指紋ごとに 1 件の `alerts` レコード（呼び出し側の Single-Table に相乗り）として残し、通知の本文に `詳細: <adminBaseUrl>/alerts/<id>/show` を足す。管理者は AWS にログインせず、レコードの `level` / `event` / `message` / `target` / `action` / `count` / `firstSeenAt` / `lastSeenAt` で対処できる。ログの購読から来た通知は、`firstLog` / `lastLog`（`region` / `logGroup` / `logStream` / `timestamp` / `requestId?`）も持つ。`requestId` は Lambda のもの（テキスト形式の接頭辞・JSON 形式の外側・`RequestId:` 行）だけで、接頭辞の無いアプリの JSON 行の `requestId` は使わない。
+
+- 記録は重複抑制の前に行い、抑制された発生も数える。アラームの ALARM → OK は同じレコード（`state`）
+- ID と件数の正は、通知ストアの `al#<alertKey>` 行（`UpdateItem` 1 回で原子的に更新）。レコードの `count` はその写しで、目安
+- 記録の単位は alertKey（同じ呼び出しの中の、同じ alertKey の発生は 1 つにまとめる）。結果の `recorded` / `unrecorded` も、通知の件数ではなく、この単位の数
+- 記録の上限: 3 秒・50 単位（error / fatal を優先）・並列 5（`recordLimits` で変更可。有限の正の整数でない値は既定値）。超えた分・失敗した分・遮断中の分は `unrecorded` に数え、その通知は URL なしで送る。記録の失敗で通知は止まらない。`dryRun` では記録しない
+- 記録しないもの: `target` が `alerts` の通知、`HEARTBEAT`（`skipRecordEvents` で変更可）、`skipRecordLogGroups` に当たるロググループから来た通知（通知は送る。`unrecorded` にも数えない）
+- `adminBaseUrl` が `http://` / `https://` で始まらなければ、URL を付けない（記録はする。起動時に warn を 1 回出す）。末尾の `/` は除く
+
+#### ループを防ぐ（Records のロググループを `skipRecordLogGroups` に入れる）
+
+記録先の Records のログを購読していると、記録の失敗（Records の 500）→ Records のエラーログ → 通知 → 記録 → 失敗、が回る。Records の失敗ログ（`Request failed` の `INTERNAL_ERROR`、`Failed to prepare record for update` など）には `resource` が出ないので、`target` が `alerts` かどうかでは見分けられない（`target` での除外は、`resource: 'alerts'` を出すログにしか効かない）。
+
+- **除外（必ず設定する）**: Records のロググループを `skipRecordLogGroups` に入れる（完全一致、または末尾 `*` の前方一致）。そのロググループから来た通知は記録しない（通知は従来どおり送る）。Records 自身の障害は通知で届くが、alerts には残らない
+- **遮断（最後の防壁。設定不要）**: 記録の失敗・時間切れが 3 回続いたら、そのハンドラ（コンテナ）では 60 秒間記録しない（`recordBreaker: { failures, cooldownMs }` で変更可）。遮断中も通知は URL なしで送り、結果に `recordSuspended: true` が入る。遮断した時に warn を 1 回出す。期間が過ぎた後の最初の失敗で再び遮断し、成功で解除する。状態はコンテナごとなので、複数のコンテナが動いていれば、それぞれが 3 回まで試す
+- **`message` / `target` は 28 日間保存される**（秘密・個人情報は伏せない。`clean()` は制御文字と長さだけ）。ログに秘密を出さないこと
+
+### 配線（各アプリ）
+
+```ts
+import { DynamoClient } from '@exabugs/dynamodb-client/client/iam';
+import {
+  DynamoNoticeStore,
+  createAlertRecorder,
+  createNotifyHandler,
+} from '@exabugs/dynamodb-client/notify';
+
+const store = new DynamoNoticeStore(doc, process.env.NOTICE_TABLE!);
+// timeout は記録の上限（3 秒）以下にする（打ち切った後に HTTP が残らないよう、短くする）
+const records = new DynamoClient(process.env.RECORDS_IAM_URL!, { auth: { region }, timeout: 2500 });
+await records.connect(); // 呼び出しのたびに作るなら、管理者の一覧の取得（admins.ts）と同じ形でよい
+
+export const handler = createNotifyHandler({
+  // …従来の設定…
+  store,
+  recorder: createAlertRecorder({ collection: records.db().collection('alerts'), index: store }),
+  adminBaseUrl: process.env.ADMIN_BASE_URL, // 例: https://admin.example.com（BrowserRouter）
+  // Records（alerts の書き込み先）のロググループ。ループを防ぐ（上の「ループを防ぐ」）
+  skipRecordLogGroups: ['/aws/lambda/astro-dev-records'], // 例。各アプリの Records 関数のロググループ
+});
+```
+
+- 環境変数: 既存の `NOTICE_TABLE` / `RECORDS_IAM_URL` に加えて、`ADMIN_BASE_URL`（任意。無ければ URL を載せない）
+- IAM: 通知ストアへは `dynamodb:UpdateItem` だけ（既存の権限のまま。`GetItem` は要らない）。Records の IAM URL の呼び出し（`lambda:InvokeFunctionUrl`）は、管理者の一覧の取得で既に持っている
+- 同時実行数: 同じレコードへの同時の書き込みはシャドーを孤立させうるので、**記録を有効にするときだけ**、通知 Lambda の予約同時実行数を 1 にする（今の通知 Lambda は未設定。入れると、記録なしでも遅れ方が変わる）。直列化は努力目標で、強制はされない（打ち切った HTTP は止まらない・削除の定時処理と重なる・管理画面から書ける）。孤立したシャドーは `src/scripts/repair-shadows.ts` で修復できる
+- ライブラリは Terraform を提供しない（`alerts` の定時削除・同時実行数・環境変数は各アプリの infra で）
+
+### 削除（定時 Lambda）
+
+ネイティブ TTL は効かない（`ttl` が最上位の属性にならない）。アプリの定時 Lambda（1 日 1 回など）から呼ぶ:
+
+```ts
+import { DynamoClient } from '@exabugs/dynamodb-client/client/iam';
+import { cleanupAlerts } from '@exabugs/dynamodb-client/notify';
+
+export const handler = async () => {
+  const client = new DynamoClient(process.env.RECORDS_IAM_URL!, { auth: { region } });
+  await client.connect();
+  try {
+    const r = await cleanupAlerts({ collection: client.db().collection('alerts'), maxPerRun: 500 });
+    if (r.errors.length > 0) throw new Error(`alerts の削除に失敗: ${r.errors.join(' / ')}`);
+    return r; // more: true なら、次回に残りを消す
+  } finally {
+    await client.close();
+  }
+};
+```
+
+- `lastSeenAt` の昇順に条件なしで読み、期限内のものが出たら止める（`lastSeenAt: { $lt }` の範囲検索は、本体の不具合で `ValidationException` になるため。TODO.md）
+- 読んだ ID は直ちに `deleteMany({ id: { $in } })` で消す（本体とシャドーを一緒に消す）。存在しない ID の削除は Records が warn を出す（それも通知に戻る）
+- 失敗は `errors` / `failed` で返す（握りつぶさない）
+
+### 管理画面（各アプリ）
+
+- 一覧・詳細はアプリが書く。`<Datagrid bulkActionButtons={false}>`、Edit なしの読み取り専用にする。ただし読み取り専用は UI だけの担保（Records 本体はリソースごとの認可を持たない）。管理者以外から `alerts` を読めないことは、各アプリの権限で確認する
+- URL は `<adminBaseUrl>/alerts/<id>/show`（BrowserRouter）。未ログインで開くと、ログイン後にダッシュボードへ飛んで遷移先が消えるので、各アプリで元の URL に戻す処理が要る
+- 詳細に `CloudWatchLogButton`（`@exabugs/dynamodb-client/integrations/react-admin`）を置ける。AWS を操作できる人向けの補助で、ログ参照（既定 `lastLog`、`source="firstLog"` も可）が無ければ何も描画しない。リージョン・ドメイン・時間幅（前後 5 分）は部品が決める。商用・中国（`cn-*`）・GovCloud（`us-gov-*`）以外のリージョン（ISO など）や形の不正なリージョンでは、何も描画しない。URL の形式は、ap-northeast-1 の実機のコンソールで確認済み。`aws-cn` / `aws-us-gov` のドメインは未確認（ADR 0003）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",