agent-common 0.4.97__tar.gz → 0.4.99__tar.gz

{agent_common-0.4.97 → agent_common-0.4.99}/CHANGELOG_EN.md

@@ -2,6 +2,39 @@
 
 > [ KO 한국어 (CHANGELOG_KO.md) ](CHANGELOG_KO.md) | [ EN English (CHANGELOG_EN.md) ](CHANGELOG_EN.md) | [ ZH 中文 (CHANGELOG_ZH.md) ](CHANGELOG_ZH.md) | [ JA 日本語 (CHANGELOG_JA.md) ](CHANGELOG_JA.md)
 
+### v0.4.99 (2026-10-06)
+
+- **Made the Reference Time Zone of `BigQueryClient` DATETIME Conversion Configurable (Rules 1.1.1, 1.3.1, 4.2)**:
+  - New setting `bigquery.datetime_timezone_str` (default `KST`): the time zone of the wall-clock time written to `DATETIME` columns. It accepts a time zone abbreviation such as `KST` or an offset such as `+09:00`; `AUTO`/`SYSTEM` uses the host system's local time zone.
+  - `convert_to_bigquery_datetime` now converts a value that carries an offset to the time zone from this setting instead of the KST that was fixed in the source code. Because the default is `KST`, results are unchanged unless the setting is added.
+  - To write the current time to a `DATETIME` column on a host whose system clock is UTC (an Airflow pod, for example), pass the offset-carrying `DateTimeUtils.get_now_timestamp()` value instead of the offset-free `DateTimeUtils.get_now_no_tz()`; only a value with an offset can be converted to the reference time zone.
+  - The setting is resolved when `BigQueryClient` is created, so an invalid value fails with `ValueError` at startup instead of during row processing.
+  - Added the default to `default_agent_common.yml` and `BigQueryClient.DEFAULT_SCHEMA_DICT`.
+  - Updated the DATETIME time zone handling in manual `3.5` and the per-class settings table in manual `1.6` in four languages.
+- **Fixed the `DATETIME`/`DATE`/`TIME` Column Conversion in `BigQueryClient.merge_table_from_json_data`**:
+  - Columns declared as `DATETIME`, `DATE` or `TIME` in `column_types_dict` are now converted with `CAST(JSON_VALUE(...) AS DATETIME)` instead of the `DATETIME(...)`, `DATE(...)` and `TIME(...)` functions. Those functions do not accept a string expression, so a string value taken from JSON has to be converted with `CAST`.
+  - Columns of a non-string type such as `DATETIME` must have their type passed in `column_types_dict`. Without it a string value is inferred as `STRING` and the MERGE fails with a type error at the assignment.
+
+### v0.4.98 (2026-10-06)
+
+- **Separated Credential Resolution from Connection in `GcsClient` and `BigQueryClient` (Rules 1.6.4, 4.2, Breaking Change)**:
+  - The constructor now resolves credentials first with `GcpCredentialResolver.resolve()` and passes the result to `_connect(credentials_obj)`. The `try` block in `_connect()` now covers only client creation and the bucket or table lookup.
+  - Compatibility: exceptions raised during credential resolution (`ImportError`, `ValueError`, `FileNotFoundError`, and others) are no longer wrapped in `ConnectionError`; they propagate with their original type. Code that caught credential failures as `ConnectionError` must be updated.
+  - A credential failure is now logged once by `GcpCredentialResolver`, at the point where the exception is raised, instead of by the client. The same log is written when the resolver is used on its own, and the client does not log it again. To support this, the resolver now has `self.logger`, and `_get_service_account` changed from a class method to an instance method (the module cache remains a class variable).
+  - Moved the resolver's exception messages, which were written in Korean in the source code, into the log message catalog (four languages): `credential_package_missing` (`ImportError`), `credential_json_invalid` (`ValueError`), and `credential_file_not_found` (`FileNotFoundError`). Exception messages now follow the configured log language, and the log ID for a credential failure changes from `connection_failed` to one of these three.
+  - The source label in the missing key file message changed from `config.yml 설정값` to the argument name `credentials_path_str`.
+  - Updated the error handling guide in manual `3.6` in four languages.
+- **Merged the `S3Client.transfer_to_gcs` Elapsed-Time Log into the Result Log (Rules 1.1.1, 3.2, 4.2)**:
+  - Removed the separate `elapsed_time` log written after each result log. The per-stage timings (`details_str`) and the transfer context (`context_info_str`) are now part of the result log, so each file produces one log line instead of two.
+  - Deleted the Korean `action_name_str` values that were written in the source code ("GCS 파일 검사", "GCS 파일 전송", "GCS 파일 전송 오류"). They were printed in Korean even when the log language was `EN`, `ZH`, or `JA`.
+  - Added the templates `transfer_completed_with_elapsed_time`, `transfer_skipped_with_elapsed_time`, and `transfer_failed_with_elapsed_time`, which append the `{details_str} {context_info_str}` slots to the existing sentences (four languages). `transfer_to_gcs` uses these three log IDs.
+  - The existing `transfer_completed`, `transfer_skipped`, and `transfer_failed` templates are unchanged.
+  - Removed the `Status=Skipped` token from the skip log because it repeated the message text.
+  - `transfer_to_gcs` now writes one ERROR log per failed transfer instead of two, so the accumulated failure count drops accordingly, and the per-type error summary shows `transfer_failed_with_elapsed_time` instead of `elapsed_time`.
+  - The `elapsed_time` template itself is kept.
+- **Manual `3.1` Update (Rule 4.2)**:
+  - Updated the skip step in the transfer pipeline flowchart to match the new log structure (Korean, English, Japanese).
+
 ### v0.4.97 (2026-10-05)
 
 - **Per-Class Selection of What Configuration Auto-Creation and Auto-Repair Write (Rules 1.7.5, 4.2, Breaking Change)**:

{agent_common-0.4.97 → agent_common-0.4.99}/CHANGELOG_JA.md

@@ -2,6 +2,39 @@
 
 > [ KO 한국어 (CHANGELOG_KO.md) ](CHANGELOG_KO.md) | [ EN English (CHANGELOG_EN.md) ](CHANGELOG_EN.md) | [ ZH 中文 (CHANGELOG_ZH.md) ](CHANGELOG_ZH.md) | [ JA 日本語 (CHANGELOG_JA.md) ](CHANGELOG_JA.md)
 
+### v0.4.99 (2026-10-06)
+
+- **`BigQueryClient` の DATETIME 変換の基準タイムゾーンを設定化 (ルール 1.1.1, 1.3.1, 4.2 準拠)**:
+  - 新規設定 `bigquery.datetime_timezone_str` (既定値 `KST`): `DATETIME` 列に記録する壁時計時刻の基準タイムゾーン。`KST` などのタイムゾーン略称、または `+09:00` 形式のオフセットを指定し、`AUTO`/`SYSTEM` の場合はホストシステムのローカルタイムゾーンを使用。
+  - `convert_to_bigquery_datetime`: オフセットが明記された値を、ソースコードに固定されていた KST ではなく、この設定のタイムゾーンの時刻に換算。既定値が `KST` のため、設定を追加しなければ結果は従来と同じ。
+  - システム時刻が UTC の環境 (Airflow Pod など) で現在時刻を `DATETIME` 列に記録する場合は、オフセットのない `DateTimeUtils.get_now_no_tz()` ではなく、オフセット付きの `DateTimeUtils.get_now_timestamp()` の値を渡すことで基準タイムゾーンの時刻に換算される。
+  - 設定値は `BigQueryClient` の生成時に解釈するため、形式が不正な値は行の処理中ではなく起動時に `ValueError` で失敗。
+  - 既定値を `default_agent_common.yml` と `BigQueryClient.DEFAULT_SCHEMA_DICT` に追加。
+  - マニュアル `3.5` の DATETIME タイムゾーン処理の説明と、`1.6` のクラス別記録設定の表を 4 言語で更新。
+- **`BigQueryClient.merge_table_from_json_data` の `DATETIME`/`DATE`/`TIME` 列の変換式を修正**:
+  - `column_types_dict` で `DATETIME`、`DATE`、`TIME` と指定された列を、`DATETIME(...)`、`DATE(...)`、`TIME(...)` 関数ではなく `CAST(JSON_VALUE(...) AS DATETIME)` の形で変換。これらの関数は文字列式を引数に取らないため、JSON から取り出した文字列値は `CAST` で変換する必要がある。
+  - `DATETIME` など文字列以外の型の列は、`column_types_dict` で型を渡す必要がある。渡さない場合、文字列値が `STRING` と推論され、MERGE の代入で型エラーになる。
+
+### v0.4.98 (2026-10-06)
+
+- **`GcsClient`、`BigQueryClient` の認証段階と接続段階を分離 (ルール 1.6.4, 4.2 準拠、互換性変更)**:
+  - コンストラクタで先に `GcpCredentialResolver.resolve()` による認証を行い、その結果を `_connect(credentials_obj)` に渡して接続するよう変更。`_connect()` の `try` ブロックにはクライアント生成とバケット・テーブル照会のみが残る。
+  - 互換性: 認証段階の例外 (`ImportError`、`ValueError`、`FileNotFoundError` など) は `ConnectionError` にラップされず、元の型のまま送出される。認証失敗を `ConnectionError` として捕捉していたコードは修正が必要。
+  - 認証失敗のログを、クライアントではなく `GcpCredentialResolver` が例外の発生箇所で 1 回記録するよう変更。リゾルバを単独で使用する場合も同じログが残り、クライアントが再度記録することはない。このためリゾルバに `self.logger` を追加し、`_get_service_account` をクラスメソッドからインスタンスメソッドに変更 (モジュールキャッシュはクラス変数のまま)。
+  - ソースコードに韓国語で書かれていたリゾルバの例外メッセージをログメッセージ辞書へ移動 (4 言語): `credential_package_missing` (`ImportError`)、`credential_json_invalid` (`ValueError`)、`credential_file_not_found` (`FileNotFoundError`)。例外メッセージはログ言語設定に従い、認証失敗のログ ID は `connection_failed` からこの 3 つのいずれかに変わる。
+  - キーファイル不在メッセージの出所表記を `config.yml 설정값` から引数名 `credentials_path_str` に変更。
+  - マニュアル `3.6` の例外処理ガイドを 4 言語で更新。
+- **`S3Client.transfer_to_gcs` の所要時間ログを結果ログに統合 (ルール 1.1.1, 3.2, 4.2 準拠)**:
+  - ファイルごとに結果ログの後へ別途出力していた `elapsed_time` ログを削除し、区間別の所要時間 (`details_str`) と転送コンテキスト (`context_info_str`) を結果ログの 1 行にまとめて記録。ファイル 1 件あたりのログが 2 行から 1 行に減少。
+  - ソースコードに韓国語で書かれていた `action_name_str` の値 ("GCS 파일 검사"、"GCS 파일 전송"、"GCS 파일 전송 오류") を削除。ログ言語を `EN`、`ZH`、`JA` に設定してもこの部分だけ韓国語で出力されていた問題を解消。
+  - 既存の文の末尾に `{details_str} {context_info_str}` スロットを付けたテンプレート `transfer_completed_with_elapsed_time`、`transfer_skipped_with_elapsed_time`、`transfer_failed_with_elapsed_time` を追加 (4 言語)。`transfer_to_gcs` はこの 3 つのログ ID を使用。
+  - 既存の `transfer_completed`、`transfer_skipped`、`transfer_failed` テンプレートは変更なし。
+  - スキップログの `Status=Skipped` トークンはメッセージ本文と重複するため削除。
+  - 転送失敗 1 件につき `transfer_to_gcs` が出力する ERROR ログが 2 件から 1 件に減るため失敗累計件数がその分減少し、エラー種別ごとの集計には `elapsed_time` の代わりに `transfer_failed_with_elapsed_time` が表示される。
+  - `elapsed_time` テンプレート自体は維持。
+- **マニュアル `3.1` の補完 (ルール 4.2 準拠)**:
+  - 転送パイプラインのフロー図にあるスキップ段階の表記を新しいログ構造に合わせて修正 (韓国語、英語、日本語)。
+
 ### v0.4.97 (2026-10-05)
 
 - **設定ファイルの自動生成・自動補正の書き込み対象をクラス単位で選択 (ルール 1.7.5、4.2 準拠、互換性変更)**:

{agent_common-0.4.97 → agent_common-0.4.99}/CHANGELOG_KO.md

@@ -2,6 +2,39 @@
 
 > [ KO 한국어 (CHANGELOG_KO.md) ](CHANGELOG_KO.md) | [ EN English (CHANGELOG_EN.md) ](CHANGELOG_EN.md) | [ ZH 中文 (CHANGELOG_ZH.md) ](CHANGELOG_ZH.md) | [ JA 日本語 (CHANGELOG_JA.md) ](CHANGELOG_JA.md)
 
+### v0.4.99 (2026-10-06)
+
+- **`BigQueryClient` DATETIME 변환의 기준 타임존을 설정으로 분리 (규칙 1.1.1, 1.3.1, 4.2 준수)**:
+  - 신규 설정 `bigquery.datetime_timezone_str` (기본값 `KST`): `DATETIME` 컬럼에 기록할 벽시계 시각의 기준 타임존. `KST` 같은 타임존 약어나 `+09:00` 형식의 오프셋을 지정하며, `AUTO`/`SYSTEM`이면 호스트 시스템의 로컬 타임존을 사용.
+  - `convert_to_bigquery_datetime`: 오프셋이 명시된 값을 소스 코드에 고정되어 있던 KST 대신 이 설정의 타임존 시각으로 환산. 기본값이 `KST`이므로 설정을 추가하지 않으면 결과는 이전과 동일.
+  - 시스템 시각이 UTC인 환경(Airflow 파드 등)에서 현재 시각을 `DATETIME` 컬럼에 기록할 때는, 오프셋이 없는 `DateTimeUtils.get_now_no_tz()` 대신 오프셋이 포함된 `DateTimeUtils.get_now_timestamp()` 값을 넘겨야 기준 타임존 시각으로 환산됨.
+  - 설정값은 `BigQueryClient` 생성 시점에 해석하므로, 형식이 잘못된 값은 행 처리 중이 아닌 기동 시점에 `ValueError`로 실패.
+  - 기본값을 `default_agent_common.yml`과 `BigQueryClient.DEFAULT_SCHEMA_DICT`에 추가.
+  - 매뉴얼 `3.5`의 DATETIME 타임존 처리 설명과 `1.6`의 클래스별 기록 설정 표를 4개 언어로 갱신.
+- **`BigQueryClient.merge_table_from_json_data`의 `DATETIME`/`DATE`/`TIME` 컬럼 변환식 수정**:
+  - `column_types_dict`에 `DATETIME`, `DATE`, `TIME`으로 지정된 컬럼을 `DATETIME(...)`, `DATE(...)`, `TIME(...)` 함수 대신 `CAST(JSON_VALUE(...) AS DATETIME)` 형태로 변환. 이 함수들은 문자열 표현식을 인자로 받지 않으므로, JSON에서 꺼낸 문자열 값은 `CAST`로 변환해야 함.
+  - `DATETIME` 등 문자열이 아닌 타입의 컬럼은 `column_types_dict`로 타입을 넘겨야 함. 넘기지 않으면 문자열 값이 `STRING`으로 추론되어 MERGE의 대입 단계에서 타입 오류가 발생.
+
+### v0.4.98 (2026-10-06)
+
+- **`GcsClient`, `BigQueryClient`의 인증과 연결 단계 분리 (규칙 1.6.4, 4.2 준수, 호환성 변경)**:
+  - 생성자에서 `GcpCredentialResolver.resolve()`로 인증을 먼저 수행하고, 그 결과를 `_connect(credentials_obj)`에 넘겨 연결하도록 변경. `_connect()`의 `try` 블록에는 클라이언트 생성과 버킷·테이블 조회만 남음.
+  - 호환성: 인증 단계 예외(`ImportError`, `ValueError`, `FileNotFoundError` 등)가 더 이상 `ConnectionError`로 감싸지지 않고 원래 타입 그대로 전달됨. 인증 실패를 `ConnectionError`로 잡던 코드는 수정 필요.
+  - 인증 실패 로그를 클라이언트가 아닌 `GcpCredentialResolver`가 예외 발생 지점에서 한 번 기록하도록 변경. 리졸버를 단독으로 쓸 때도 같은 로그가 남으며, 클라이언트는 이를 다시 기록하지 않음. 이를 위해 리졸버에 `self.logger`를 추가하고 `_get_service_account`를 클래스 메서드에서 인스턴스 메서드로 변경 (모듈 캐시는 클래스 변수 유지).
+  - 소스 코드에 한글로 적혀 있던 리졸버의 예외 문장을 로그 메시지 사전으로 이동 (4개 언어): `credential_package_missing`(`ImportError`), `credential_json_invalid`(`ValueError`), `credential_file_not_found`(`FileNotFoundError`). 예외 메시지가 로그 언어 설정을 따르며, 인증 실패 로그 ID는 `connection_failed`에서 이 세 가지로 바뀜.
+  - 키 파일 미존재 메시지의 출처 표기를 `config.yml 설정값`에서 인자명 `credentials_path_str`로 변경.
+  - 매뉴얼 `3.6`의 예외 처리 가이드를 4개 언어로 갱신.
+- **`S3Client.transfer_to_gcs` 소요시간 로그를 결과 로그에 통합 (규칙 1.1.1, 3.2, 4.2 준수)**:
+  - 파일마다 결과 로그 뒤에 따로 남기던 `elapsed_time` 로그를 제거하고, 구간별 소요시간(`details_str`)과 전송 컨텍스트(`context_info_str`)를 결과 로그 한 줄에 함께 기록. 파일 1건당 로그가 2줄에서 1줄로 감소.
+  - 소스 코드에 한글로 적혀 있던 `action_name_str` 값("GCS 파일 검사", "GCS 파일 전송", "GCS 파일 전송 오류")을 삭제. 로그 언어를 `EN`, `ZH`, `JA`로 설정해도 이 부분만 한글로 출력되던 문제 해소.
+  - 기존 문장 끝에 `{details_str} {context_info_str}` 슬롯을 붙인 템플릿 `transfer_completed_with_elapsed_time`, `transfer_skipped_with_elapsed_time`, `transfer_failed_with_elapsed_time` 추가 (4개 언어). `transfer_to_gcs`는 이 세 로그 ID를 사용.
+  - 기존 `transfer_completed`, `transfer_skipped`, `transfer_failed` 템플릿은 변경 없음.
+  - 건너뜀 로그의 `Status=Skipped` 토큰은 메시지 본문과 중복되어 삭제.
+  - 전송 실패 1건당 `transfer_to_gcs`가 남기는 ERROR 로그가 2건에서 1건으로 줄어 실패 누적 건수가 그만큼 감소하고, 오류 유형별 집계에서 `elapsed_time` 대신 `transfer_failed_with_elapsed_time`이 표시됨.
+  - `elapsed_time` 템플릿은 그대로 유지.
+- **매뉴얼 `3.1` 보완 (규칙 4.2 준수)**:
+  - 전송 파이프라인 흐름도의 건너뜀 단계 표기를 변경된 로그 구조에 맞게 수정 (한국어, 영어, 일본어).
+
 ### v0.4.97 (2026-10-05)
 
 - **설정 파일 자동 생성·보정 대상을 클래스 단위로 선택 (규칙 1.7.5, 4.2 준수, 호환성 변경)**:

{agent_common-0.4.97 → agent_common-0.4.99}/CHANGELOG_ZH.md

@@ -2,6 +2,39 @@
 
 > [ KO 한국어 (CHANGELOG_KO.md) ](CHANGELOG_KO.md) | [ EN English (CHANGELOG_EN.md) ](CHANGELOG_EN.md) | [ ZH 中文 (CHANGELOG_ZH.md) ](CHANGELOG_ZH.md) | [ JA 日本語 (CHANGELOG_JA.md) ](CHANGELOG_JA.md)
 
+### v0.4.99 (2026-10-06)
+
+- **把 `BigQueryClient` DATETIME 转换的基准时区改为可配置 (遵循规则 1.1.1、1.3.1、4.2)**:
+  - 新增配置 `bigquery.datetime_timezone_str` (默认值 `KST`): 写入 `DATETIME` 列的钟表时刻所依据的基准时区。可填写 `KST` 等时区缩写或 `+09:00` 形式的偏移量，为 `AUTO`/`SYSTEM` 时使用宿主系统的本地时区。
+  - `convert_to_bigquery_datetime`: 带有偏移量的值不再换算为源代码中写死的 KST，而是换算为该配置所指定时区的时刻。默认值为 `KST`，因此不新增配置时结果与此前相同。
+  - 在系统时间为 UTC 的环境 (如 Airflow Pod) 中把当前时间写入 `DATETIME` 列时，应传入带偏移量的 `DateTimeUtils.get_now_timestamp()` 的值，而不是不带偏移量的 `DateTimeUtils.get_now_no_tz()`，这样才会换算为基准时区的时刻。
+  - 配置值在创建 `BigQueryClient` 时解析，因此格式不正确的值会在启动时以 `ValueError` 失败，而不是在处理数据行的过程中失败。
+  - 在 `default_agent_common.yml` 与 `BigQueryClient.DEFAULT_SCHEMA_DICT` 中新增默认值。
+  - 以 4 种语言更新手册 `3.5` 中的 DATETIME 时区处理说明，以及手册 `1.6` 中按类写入配置的表格。
+- **修正 `BigQueryClient.merge_table_from_json_data` 中 `DATETIME`/`DATE`/`TIME` 列的转换表达式**:
+  - 在 `column_types_dict` 中声明为 `DATETIME`、`DATE`、`TIME` 的列，改用 `CAST(JSON_VALUE(...) AS DATETIME)` 的形式转换，不再使用 `DATETIME(...)`、`DATE(...)`、`TIME(...)` 函数。这些函数不接受字符串表达式作为参数，因此从 JSON 中取出的字符串值必须用 `CAST` 转换。
+  - `DATETIME` 等非字符串类型的列必须通过 `column_types_dict` 传入类型。不传入时字符串值会被推断为 `STRING`，MERGE 在赋值时会出现类型错误。
+
+### v0.4.98 (2026-10-06)
+
+- **分离 `GcsClient`、`BigQueryClient` 的认证阶段与连接阶段 (遵循规则 1.6.4、4.2，兼容性变更)**:
+  - 构造函数先通过 `GcpCredentialResolver.resolve()` 完成认证，再把结果传给 `_connect(credentials_obj)` 进行连接。`_connect()` 的 `try` 块中只保留客户端创建以及存储桶、数据表的查询。
+  - 兼容性: 认证阶段的异常 (`ImportError`、`ValueError`、`FileNotFoundError` 等) 不再被包装为 `ConnectionError`，而是以原始类型抛出。此前以 `ConnectionError` 捕获认证失败的代码需要修改。
+  - 认证失败日志改由 `GcpCredentialResolver` 在抛出异常处记录一次，而不再由客户端记录。单独使用解析器时也会留下同样的日志，客户端不会重复记录。为此在解析器中新增 `self.logger`，并把 `_get_service_account` 由类方法改为实例方法 (模块缓存仍为类变量)。
+  - 把源代码中以韩文书写的解析器异常消息移入日志消息字典 (4 种语言): `credential_package_missing` (`ImportError`)、`credential_json_invalid` (`ValueError`)、`credential_file_not_found` (`FileNotFoundError`)。异常消息随日志语言设置输出，认证失败的日志 ID 由 `connection_failed` 变为这三者之一。
+  - 密钥文件不存在消息中的来源标注由 `config.yml 설정값` 改为参数名 `credentials_path_str`。
+  - 以 4 种语言更新手册 `3.6` 的异常处理指南。
+- **将 `S3Client.transfer_to_gcs` 的耗时日志合并到结果日志 (遵循规则 1.1.1、3.2、4.2)**:
+  - 删除每个文件在结果日志之后单独输出的 `elapsed_time` 日志，把各阶段耗时 (`details_str`) 与传输上下文 (`context_info_str`) 一并写入结果日志。每个文件的日志由 2 行减为 1 行。
+  - 删除源代码中以韩文书写的 `action_name_str` 值 ("GCS 파일 검사"、"GCS 파일 전송"、"GCS 파일 전송 오류")。此前即使日志语言设为 `EN`、`ZH`、`JA`，这一部分仍以韩文输出。
+  - 新增模板 `transfer_completed_with_elapsed_time`、`transfer_skipped_with_elapsed_time`、`transfer_failed_with_elapsed_time`，即在原有句子末尾加上 `{details_str} {context_info_str}` 占位符 (4 种语言)。`transfer_to_gcs` 使用这三个日志 ID。
+  - 原有的 `transfer_completed`、`transfer_skipped`、`transfer_failed` 模板保持不变。
+  - 跳过日志中的 `Status=Skipped` 与消息正文重复，已删除。
+  - 每次传输失败时 `transfer_to_gcs` 输出的 ERROR 日志由 2 条减为 1 条，失败累计次数相应减少；按错误类型的统计中显示 `transfer_failed_with_elapsed_time` 而不再是 `elapsed_time`。
+  - `elapsed_time` 模板本身保留。
+- **补充手册 `3.1` (遵循规则 4.2)**:
+  - 按新的日志结构修改传输流程图中跳过步骤的说明 (韩文、英文、日文)。
+
 ### v0.4.97 (2026-10-05)
 
 - **按类选择配置文件自动生成与自动补全的写入对象 (遵循规则 1.7.5、4.2，兼容性变更)**:

{agent_common-0.4.97/src/agent_common.egg-info → agent_common-0.4.99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent_common
-Version: 0.4.97
+Version: 0.4.99
 Summary: 자율 에이전트 및 데이터 파이프라인을 위한 경량 설정·로깅·도구 프레임워크 (Lightweight configuration, logging, and tooling framework for autonomous agents and data pipelines)
 Project-URL: Homepage, https://pypi.org/project/agent-common
 Project-URL: Repository, https://github.com/kampores/agent_common
@@ -286,7 +286,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 배포 환경 (Wheel 패키지 설치)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 PyPI 공식 배포 (관리자 전용)
@@ -301,7 +301,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. PyPI 업로드
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -545,7 +545,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # Production (Wheel package)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 Official PyPI Distribution (Maintainers Only)
@@ -560,7 +560,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. Upload to PyPI
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -804,7 +804,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 生产环境 (安装 Wheel 包)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 官方 PyPI 镜像分发（仅限维护者）
@@ -819,7 +819,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. 上传至 PyPI
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -1063,7 +1063,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 本番環境（Wheel パッケージのインストール）
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 公式 PyPI 配布（管理者専用）
@@ -1078,7 +1078,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. PyPI アップロード
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---

{agent_common-0.4.97 → agent_common-0.4.99}/README.md

@@ -253,7 +253,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 배포 환경 (Wheel 패키지 설치)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 PyPI 공식 배포 (관리자 전용)
@@ -268,7 +268,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. PyPI 업로드
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -512,7 +512,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # Production (Wheel package)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 Official PyPI Distribution (Maintainers Only)
@@ -527,7 +527,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. Upload to PyPI
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -771,7 +771,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 生产环境 (安装 Wheel 包)
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 官方 PyPI 镜像分发（仅限维护者）
@@ -786,7 +786,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. 上传至 PyPI
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---
@@ -1030,7 +1030,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 本番環境（Wheel パッケージのインストール）
-pip install dist/agent_common-0.4.97-py3-none-any.whl
+pip install dist/agent_common-0.4.99-py3-none-any.whl
 ```
 
 #### 🌐 公式 PyPI 配布（管理者専用）
@@ -1045,7 +1045,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. PyPI アップロード
-python -m twine upload dist/agent_common-0.4.97*
+python -m twine upload dist/agent_common-0.4.99*
 ```
 
 ---

{agent_common-0.4.97 → agent_common-0.4.99}/manual/en/clients/01_s3_ecs_storage_client_en.md

@@ -31,7 +31,7 @@ flowchart TD
     D --> E["gcs_client.get_blob_size(gcs_blob)"]
     E --> F{"GCS Object Exists &<br/>Size Matches?"}
     
-    F -->|"Match (Identical)"| G["Skip Transfer (SKIPPED)<br/>Log elapsed_time"]
+    F -->|"Match (Identical)"| G["Skip Transfer (SKIPPED)<br/>Log with CheckTime"]
     F -->|"Mismatch or Not Found"| H["get_object_stream()<br/>Fetch S3/ECS StreamingBody"]
     H --> I["gcs_client.upload_stream()<br/>Direct In-Memory Pipe Upload"]
     I --> J["Transfer Complete (UPLOADED)<br/>Log Sub-stage Latencies"]

{agent_common-0.4.97 → agent_common-0.4.99}/manual/en/clients/05_bigquery_timestamp_and_datetime_conversion_en.md

@@ -2,7 +2,7 @@
 
 > **Module**: `agent_common.clients.BigQueryClient`  
 > **Key Methods**: `convert_to_bigquery_timestamp()`, `convert_to_bigquery_datetime()`  
-> **Configuration**: `config.bigquery.timezone_offset_str`
+> **Configuration**: `config.bigquery.timezone_offset_str`, `config.bigquery.datetime_timezone_str`
 
 ---
 
@@ -54,8 +54,9 @@ def convert_to_bigquery_datetime(self, val_any: Any) -> Optional[str]
 ```
 - **Supported input formats**: Same as `convert_to_bigquery_timestamp`.
 - **Time zone handling**:
-  - If the source string carries an offset (`Z`, `+09:00`, `-0500`, etc.), it is converted to Korea Standard Time (KST) and the offset is then dropped.
+  - If the source string carries an offset (`Z`, `+09:00`, `-0500`, etc.), it is converted to the time zone set in `config.bigquery.datetime_timezone_str` (default `KST`) and the offset is then dropped. A current time generated on a host whose system clock is UTC (`DateTimeUtils.get_now_timestamp()`) is therefore also recorded in that time zone.
   - If there is no offset, the clock digits are used as they are.
+  - `datetime_timezone_str` accepts a time zone abbreviation such as `KST` or an offset such as `+09:00`. `AUTO`/`SYSTEM` uses the host system's local time zone, and an invalid value raises `ValueError` when `BigQueryClient` is created.
   - It is not affected by the `timezone_offset_str` setting.
 - Returns `None` when the value is empty or cannot be parsed as a date.
 
@@ -97,7 +98,7 @@ dt_1 = bq_client.convert_to_bigquery_datetime("20260824153000")
 # 2) ISO datetime without an offset -> "2026-08-24 15:30:00" (digits kept as is)
 dt_2 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00")
 
-# 3) UTC notation (Z) -> "2026-08-25 00:30:00" (converted to KST)
+# 3) UTC notation (Z) -> "2026-08-25 00:30:00" (converted to KST, the `datetime_timezone_str` value)
 dt_3 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00Z")
 
 # 4) Unparseable value -> None

{agent_common-0.4.97 → agent_common-0.4.99}/manual/en/clients/06_gcp_credential_resolver_en.md

@@ -105,12 +105,14 @@ class SecretManagerClient:
 
 ## 5. Error Handling Guide
 
-Exception messages are emitted in Korean; the leading text is shown below as it appears.
+Exception messages are emitted in the configured log language (`KO`, `EN`, `ZH`, `JA`). The messages below are the English ones; the log IDs are the same in every language.
 
-| Exception | Common cause | Resolution |
-| :--- | :--- | :--- |
-| `ImportError: ... 'google-auth' 패키지가 필요합니다` | `google-auth` is not installed | Run `pip install agent_common[clients]` or `pip install google-auth` |
-| `ValueError: GOOGLE_APPLICATION_CREDENTIALS_JSON 인메모리 JSON 인증 객체 생성에 실패했습니다` | Malformed JSON or missing required keys in the environment variable | Check the JSON string and its escaping in the environment variable |
-| `FileNotFoundError: 인증키 파일을 찾을 수 없습니다` | No file at the tier 2 or tier 3 path | Check the path and source (environment variable / `config.yml`) shown in the message |
+| Exception | Log ID | Common cause | Resolution |
+| :--- | :--- | :--- | :--- |
+| `ImportError: The 'google-auth' package is required ...` | `credential_package_missing` | `google-auth` is not installed | Run `pip install agent_common[clients]` or `pip install google-auth` |
+| `ValueError: Failed to create credentials from the in-memory JSON in GOOGLE_APPLICATION_CREDENTIALS_JSON` | `credential_json_invalid` | Malformed JSON or missing required keys in the environment variable | Check the JSON string and its escaping in the environment variable |
+| `FileNotFoundError: Credentials key file not found` | `credential_file_not_found` | No file at the tier 2 or tier 3 path | Check the path and source (`GOOGLE_APPLICATION_CREDENTIALS` / `credentials_path_str`) shown in the message |
 
-When called through `GcsClient` or `BigQueryClient`, these exceptions are wrapped in `ConnectionError` during the connection step. The original exception is available on `__cause__` and in the logged traceback.
+Before raising one of these exceptions, the resolver writes one ERROR log under the matching log ID. This is the same whether it is used on its own or called through `GcsClient` or `BigQueryClient`.
+
+`GcsClient` and `BigQueryClient` resolve credentials (`resolve()`) in the constructor before they connect. Exceptions from credential resolution are not wrapped in `ConnectionError`; they propagate with their original type, and the client does not log them again. `ConnectionError` is raised only for failures in the connection step, such as creating the client or looking up the bucket or table.

{agent_common-0.4.97 → agent_common-0.4.99}/manual/en/config_loader/03_type_coercion_and_guarantee_en.md

@@ -55,8 +55,8 @@ def coerce_type_by_key_suffix(key_str: str, val_any: Any) -> Any:
             ErrorHandler.raise_coercion_error(
                 key_str=key_str,
                 val_any=val_any,
-                expected_type_str="정수형(int)",
-                guide_msg_str="정수형 값으로 입력해 주십시오.",
+                expected_type_str="integer (int)",
+                guide_msg_str="Please provide an integer value.",
                 cause_exc=err,
             )
 
@@ -67,8 +67,8 @@ def coerce_type_by_key_suffix(key_str: str, val_any: Any) -> Any:
             ErrorHandler.raise_coercion_error(
                 key_str=key_str,
                 val_any=val_any,
-                expected_type_str="실수형(float)",
-                guide_msg_str="올바른 숫자형 값으로 입력해 주십시오.",
+                expected_type_str="floating-point number (float)",
+                guide_msg_str="Please provide a valid numeric value.",
                 cause_exc=err,
             )
 
@@ -84,15 +84,15 @@ def coerce_type_by_key_suffix(key_str: str, val_any: Any) -> Any:
             ErrorHandler.raise_coercion_error(
                 key_str=key_str,
                 val_any=val_any,
-                expected_type_str="불리언(bool)",
-                guide_msg_str="True 또는 False 값으로 입력해 주십시오.",
+                expected_type_str="boolean (bool)",
+                guide_msg_str="Please provide a True or False value.",
                 exc_cls=ValueError,
             )
         ErrorHandler.raise_coercion_error(
             key_str=key_str,
             val_any=val_any,
-            expected_type_str="불리언(bool)",
-            guide_msg_str="True 또는 False 값으로 입력해 주십시오.",
+            expected_type_str="boolean (bool)",
+            guide_msg_str="Please provide a True or False value.",
             exc_cls=TypeError,
         )
 
@@ -114,8 +114,8 @@ def coerce_type_by_key_suffix(key_str: str, val_any: Any) -> Any:
         ErrorHandler.raise_coercion_error(
             key_str=key_str,
             val_any=val_any,
-            expected_type_str="딕셔너리(dict)",
-            guide_msg_str="딕셔너리 매핑 구조로 입력해 주십시오.",
+            expected_type_str="dictionary (dict)",
+            guide_msg_str="Please provide a dictionary mapping structure.",
             exc_cls=TypeError,
         )
 
@@ -220,7 +220,7 @@ timeout_sec = mapping_cfg.timeout_float
 print(f"Timeout: {timeout_sec}")
 
 # Missing key produces exact diagnostic error:
-# AttributeError: mapping.yml에 정의되지 않은 설정 항목입니다: 'undefined_key'
+# AttributeError: Configuration item not defined in mapping.yml: 'undefined_key'
 ```
 
 #### C. Standalone Key-Value Coercion (`coerce_type_by_key_suffix`)

{agent_common-0.4.97 → agent_common-0.4.99}/manual/en/config_loader/06_ensure_config_self_healing_en.md

@@ -78,7 +78,7 @@ config_loader:
 | `S3Client_bool` | `transfer.timeout_seconds_int` |
 | `GcsClient_bool` | `transfer.timeout_seconds_int` |
 | `GcpCredentialResolver_bool` | None (uses environment variables only) |
-| `BigQueryClient_bool` | `transfer.timeout_seconds_int`, `bigquery.ignore_unknown_values_bool`, `bigquery.timezone_offset_str` |
+| `BigQueryClient_bool` | `transfer.timeout_seconds_int`, `bigquery.ignore_unknown_values_bool`, `bigquery.timezone_offset_str`, `bigquery.datetime_timezone_str` |
 | `ProgressTracker_bool` | `progress_tracker.*` |
 | `TableFormatter_bool` | `table_formatter.*` |
 | `ToolParser_bool` | `transfer.tool_dir_str` |

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ja/clients/01_s3_ecs_storage_client_ja.md

@@ -31,7 +31,7 @@ flowchart TD
     D --> E["gcs_client.get_blob_size(gcs_blob)"]
     E --> F{"GCS ファイルの存在および<br/>サイズ一致確認"}
     
-    F -->|"一致 (同一ファイル)"| G["転送スキップ (SKIPPED)<br/>elapsed_time のログ記録"]
+    F -->|"一致 (同一ファイル)"| G["転送スキップ (SKIPPED)<br/>CheckTime を含めてログ記録"]
     F -->|"不一致または未存在"| H["get_object_stream()<br/>S3/ECS StreamingBody の取得"]
     H --> I["gcs_client.upload_stream()<br/>リアルタイムメモリパイプラインアップロード"]
     I --> J["転送完了 (UPLOADED)<br/>各区間レイテンシの精密ロギング"]

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ja/clients/05_bigquery_timestamp_and_datetime_conversion_ja.md

@@ -2,7 +2,7 @@
 
 > **所属モジュール**: `agent_common.clients.BigQueryClient`  
 > **中核メソッド**: `convert_to_bigquery_timestamp()`, `convert_to_bigquery_datetime()`  
-> **関連設定**: `config.bigquery.timezone_offset_str`
+> **関連設定**: `config.bigquery.timezone_offset_str`, `config.bigquery.datetime_timezone_str`
 
 ---
 
@@ -54,8 +54,9 @@ def convert_to_bigquery_datetime(self, val_any: Any) -> Optional[str]
 ```
 - **対応入力フォーマット**: `convert_to_bigquery_timestamp` と同じです。
 - **タイムゾーン処理**:
-  - 元の文字列にオフセット（`Z`、`+09:00`、`-0500` など）がある場合、韓国時間 (KST) に換算してからオフセットを除去します。
+  - 元の文字列にオフセット（`Z`、`+09:00`、`-0500` など）がある場合、`config.bigquery.datetime_timezone_str`（既定値 `KST`）の時刻に換算してからオフセットを除去します。システム時刻が UTC の環境で生成した現在時刻（`DateTimeUtils.get_now_timestamp()`）も、このタイムゾーンの時刻で記録されます。
   - オフセットがない場合は、時刻の数字をそのまま使用します。
+  - `datetime_timezone_str` には `KST` などのタイムゾーン略称、または `+09:00` 形式のオフセットを指定します。`AUTO`/`SYSTEM` の場合はホストシステムのローカルタイムゾーンを使用し、形式が不正な場合は `BigQueryClient` の生成時に `ValueError` が発生します。
   - `timezone_offset_str` 設定の影響は受けません。
 - 値が空、または日付として解釈できない場合は `None` を返します。
 
@@ -97,7 +98,7 @@ dt_1 = bq_client.convert_to_bigquery_datetime("20260824153000")
 # 2) オフセットなしの ISO 日時 -> "2026-08-24 15:30:00"（数字はそのまま）
 dt_2 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00")
 
-# 3) UTC 表記 (Z) -> "2026-08-25 00:30:00"（KST に換算）
+# 3) UTC 表記 (Z) -> "2026-08-25 00:30:00"（`datetime_timezone_str` の KST に換算）
 dt_3 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00Z")
 
 # 4) 解釈できない値 -> None

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ja/clients/06_gcp_credential_resolver_ja.md

@@ -105,12 +105,14 @@ class SecretManagerClient:
 
 ## 5. 例外処理ガイド
 
-例外メッセージは韓国語で出力されます。下表は実際に出力される先頭の文言です。
+例外メッセージはログ言語設定 (`KO`、`EN`、`ZH`、`JA`) に応じた言語で出力されます。下表のメッセージは日本語のもので、ログ ID はどの言語でも同じです。
 
-| 発生例外 | 主な発生原因 | 対処方法 |
-| :--- | :--- | :--- |
-| `ImportError: ... 'google-auth' 패키지가 필요합니다` | `google-auth` が未インストール | `pip install agent_common[clients]` または `pip install google-auth` を実行 |
-| `ValueError: GOOGLE_APPLICATION_CREDENTIALS_JSON 인메모리 JSON 인증 객체 생성에 실패했습니다` | 環境変数の JSON 構文エラー、または必須キーの欠落 | 環境変数に注入した JSON 文字列とエスケープ状態を確認 |
-| `FileNotFoundError: 인증키 파일을 찾을 수 없습니다` | 2位または3位のパスにファイルが存在しない | メッセージに表示されたパスとソース（環境変数 / `config.yml`）を確認 |
+| 発生例外 | ログ ID | 主な発生原因 | 対処方法 |
+| :--- | :--- | :--- | :--- |
+| `ImportError: GCP サービスアカウント認証機能を使用するには 'google-auth' パッケージが必要です` | `credential_package_missing` | `google-auth` が未インストール | `pip install agent_common[clients]` または `pip install google-auth` を実行 |
+| `ValueError: GOOGLE_APPLICATION_CREDENTIALS_JSON のインメモリ JSON から認証オブジェクトを生成できませんでした` | `credential_json_invalid` | 環境変数の JSON 構文エラー、または必須キーの欠落 | 環境変数に注入した JSON 文字列とエスケープ状態を確認 |
+| `FileNotFoundError: 認証キーファイルが見つかりません` | `credential_file_not_found` | 2位または3位のパスにファイルが存在しない | メッセージに表示されたパスとソース (`GOOGLE_APPLICATION_CREDENTIALS` / `credentials_path_str`) を確認 |
 
-`GcsClient`、`BigQueryClient` 経由で呼び出された場合、上記の例外は接続段階で `ConnectionError` にラップされて送出されます。元の例外は `__cause__` およびログのトレースバックで確認できます。
+リゾルバは上記の例外を送出する前に、対応するログ ID で ERROR ログを 1 回記録します。単独で使用する場合も、`GcsClient`、`BigQueryClient` 経由で呼び出される場合も同じです。
+
+`GcsClient`、`BigQueryClient` はコンストラクタで先に認証 (`resolve()`) を行い、その後に接続します。認証段階の例外は `ConnectionError` にラップされず元の型のまま送出され、クライアントが再度記録することはありません。`ConnectionError` は、クライアント生成やバケット・テーブル照会など接続段階の失敗でのみ発生します。

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ja/config_loader/06_ensure_config_self_healing_ja.md

@@ -78,7 +78,7 @@ config_loader:
 | `S3Client_bool` | `transfer.timeout_seconds_int` |
 | `GcsClient_bool` | `transfer.timeout_seconds_int` |
 | `GcpCredentialResolver_bool` | なし (環境変数のみ使用) |
-| `BigQueryClient_bool` | `transfer.timeout_seconds_int`、`bigquery.ignore_unknown_values_bool`、`bigquery.timezone_offset_str` |
+| `BigQueryClient_bool` | `transfer.timeout_seconds_int`、`bigquery.ignore_unknown_values_bool`、`bigquery.timezone_offset_str`、`bigquery.datetime_timezone_str` |
 | `ProgressTracker_bool` | `progress_tracker.*` |
 | `TableFormatter_bool` | `table_formatter.*` |
 | `ToolParser_bool` | `transfer.tool_dir_str` |

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ko/clients/01_s3_ecs_storage_client_ko.md

@@ -31,7 +31,7 @@ flowchart TD
     D --> E["gcs_client.get_blob_size(gcs_blob)"]
     E --> F{"GCS 파일 존재 및<br/>용량 일치 여부?"}
     
-    F -->|"일치 (동일 파일)"| G["전송 생략 (SKIPPED)<br/>elapsed_time 로깅"]
+    F -->|"일치 (동일 파일)"| G["전송 생략 (SKIPPED)<br/>CheckTime 포함 단일 행 로깅"]
     F -->|"불일치 또는 미존재"| H["get_object_stream()<br/>S3/ECS StreamingBody 획득"]
     H --> I["gcs_client.upload_stream()<br/>실시간 메모리 파이프라인 업로드"]
     I --> J["전송 완료 (UPLOADED)<br/>구간별 레이턴시 정밀 로깅"]

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ko/clients/05_bigquery_timestamp_and_datetime_conversion_ko.md

@@ -2,7 +2,7 @@
 
 > **소속 모듈**: `agent_common.clients.BigQueryClient`  
 > **핵심 메서드**: `convert_to_bigquery_timestamp()`, `convert_to_bigquery_datetime()`  
-> **관련 설정**: `config.bigquery.timezone_offset_str`
+> **관련 설정**: `config.bigquery.timezone_offset_str`, `config.bigquery.datetime_timezone_str`
 
 ---
 
@@ -54,8 +54,9 @@ def convert_to_bigquery_datetime(self, val_any: Any) -> Optional[str]
 ```
 - **지원 입력 포맷**: `convert_to_bigquery_timestamp`와 동일합니다.
 - **타임존 처리**:
-  - 원천 문자열에 오프셋(`Z`, `+09:00`, `-0500` 등)이 있으면 한국 시각(KST)으로 환산한 뒤 오프셋을 제거합니다.
+  - 원천 문자열에 오프셋(`Z`, `+09:00`, `-0500` 등)이 있으면 `config.bigquery.datetime_timezone_str`(기본값 `KST`)의 시각으로 환산한 뒤 오프셋을 제거합니다. 시스템 시각이 UTC인 환경에서 만든 현재 시각(`DateTimeUtils.get_now_timestamp()`)도 이 타임존의 시각으로 기록됩니다.
   - 오프셋이 없으면 시각 숫자를 그대로 사용합니다.
+  - `datetime_timezone_str`에는 `KST` 같은 타임존 약어나 `+09:00` 형식의 오프셋을 지정합니다. `AUTO`/`SYSTEM`이면 호스트 시스템의 로컬 타임존을 사용하며, 형식이 잘못되면 `BigQueryClient` 생성 시점에 `ValueError`가 발생합니다.
   - `timezone_offset_str` 설정의 영향을 받지 않습니다.
 - 값이 비어 있거나 날짜로 해석할 수 없으면 `None`을 반환합니다.
 
@@ -97,7 +98,7 @@ dt_1 = bq_client.convert_to_bigquery_datetime("20260824153000")
 # 2) 오프셋이 없는 ISO 일시 -> "2026-08-24 15:30:00" (숫자 그대로)
 dt_2 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00")
 
-# 3) UTC 표기(Z) -> "2026-08-25 00:30:00" (KST로 환산)
+# 3) UTC 표기(Z) -> "2026-08-25 00:30:00" (`datetime_timezone_str`의 KST로 환산)
 dt_3 = bq_client.convert_to_bigquery_datetime("2026-08-24T15:30:00Z")
 
 # 4) 해석할 수 없는 값 -> None

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ko/clients/06_gcp_credential_resolver_ko.md

@@ -105,10 +105,14 @@ class SecretManagerClient:
 
 ## 5. 예외 처리 가이드
 
-| 발생 예외 | 주요 발생 원인 | 조치 방안 |
-| :--- | :--- | :--- |
-| `ImportError: 'google-auth' 패키지가 필요합니다` | `google-auth` 미설치 상태 | `pip install agent_common[clients]` 또는 `pip install google-auth` 실행 |
-| `ValueError: GOOGLE_APPLICATION_CREDENTIALS_JSON 인메모리 JSON 인증 객체 생성에 실패했습니다` | 환경변수의 JSON 문법 오류 또는 필수 키 누락 | 환경변수에 주입된 JSON 문자열과 이스케이프 상태 점검 |
-| `FileNotFoundError: 인증키 파일을 찾을 수 없습니다` | 2순위 또는 3순위 경로에 파일이 없음 | 메시지에 표시된 경로와 원천(환경변수 / `config.yml`) 확인 |
+예외 메시지는 로그 언어 설정(`KO`, `EN`, `ZH`, `JA`)에 따른 언어로 출력됩니다. 아래 표의 메시지는 한국어 기준이며, 로그 ID는 언어와 무관하게 같습니다.
 
-`GcsClient`, `BigQueryClient`를 통해 호출될 때는 위 예외가 연결 단계에서 `ConnectionError`로 감싸져 전달되며, 원래 예외는 `__cause__`와 로그의 트레이스백에서 확인할 수 있습니다.
+| 발생 예외 | 로그 ID | 주요 발생 원인 | 조치 방안 |
+| :--- | :--- | :--- | :--- |
+| `ImportError: ... 'google-auth' 패키지가 필요합니다` | `credential_package_missing` | `google-auth` 미설치 상태 | `pip install agent_common[clients]` 또는 `pip install google-auth` 실행 |
+| `ValueError: GOOGLE_APPLICATION_CREDENTIALS_JSON 인메모리 JSON 인증 객체 생성에 실패했습니다` | `credential_json_invalid` | 환경변수의 JSON 문법 오류 또는 필수 키 누락 | 환경변수에 주입된 JSON 문자열과 이스케이프 상태 점검 |
+| `FileNotFoundError: 인증키 파일을 찾을 수 없습니다` | `credential_file_not_found` | 2순위 또는 3순위 경로에 파일이 없음 | 메시지에 표시된 경로와 원천(`GOOGLE_APPLICATION_CREDENTIALS` / `credentials_path_str`) 확인 |
+
+리졸버는 위 예외를 던지기 전에 해당 로그 ID로 ERROR 로그를 한 번 기록합니다. 단독으로 사용할 때와 `GcsClient`, `BigQueryClient`를 통해 호출될 때 모두 같습니다.
+
+`GcsClient`, `BigQueryClient`는 생성자에서 인증(`resolve()`)을 먼저 수행한 뒤 연결합니다. 인증 단계의 예외는 `ConnectionError`로 감싸지 않고 원래 타입 그대로 전달되며, 클라이언트는 이를 다시 기록하지 않습니다. `ConnectionError`는 클라이언트 생성과 버킷·테이블 조회 등 연결 단계의 실패에만 발생합니다.

{agent_common-0.4.97 → agent_common-0.4.99}/manual/ko/config_loader/06_ensure_config_self_healing_ko.md

@@ -78,7 +78,7 @@ config_loader:
 | `S3Client_bool` | `transfer.timeout_seconds_int` |
 | `GcsClient_bool` | `transfer.timeout_seconds_int` |
 | `GcpCredentialResolver_bool` | 없음 (환경변수만 사용) |
-| `BigQueryClient_bool` | `transfer.timeout_seconds_int`, `bigquery.ignore_unknown_values_bool`, `bigquery.timezone_offset_str` |
+| `BigQueryClient_bool` | `transfer.timeout_seconds_int`, `bigquery.ignore_unknown_values_bool`, `bigquery.timezone_offset_str`, `bigquery.datetime_timezone_str` |
 | `ProgressTracker_bool` | `progress_tracker.*` |
 | `TableFormatter_bool` | `table_formatter.*` |
 | `ToolParser_bool` | `transfer.tool_dir_str` |