docs(agents): 저장 시각 정밀도와 DB 왕복 검증 규칙을 명시한다

2026-10-26 12:02:57 +09:00
parent c97b028dd5
commit 96a59021ff
3 changed files with 30 additions and 0 deletions
@@ -79,3 +79,16 @@
 - 주석은 한 문장으로 간결하게 작성한다.
 - 주석은 코드의 의도와 구조를 설명한다.
 - 주석은 코드 변경 시 업데이트를 잊지 않는다.
+
+### 12) DB 저장 시각과 응답 정밀도
+- 상태 변경 시각을 DB에 저장하면서 API 응답에도 반환할 때는 먼저 해당 컬럼의 DDL 정밀도를 확인한다.
+  MySQL의 소수초 정밀도를 지정하지 않은 `TIMESTAMP`/`DATETIME`은 초 단위다. `(3)`/`(6)` 컬럼에 초 절삭을 일괄 적용하지 않는다.
+- OS/JDK의 `LocalDateTime.now()`는 나노초까지 반환할 수 있고, H2/JDBC/MySQL은 저장 시 반올림·절삭할 수 있다.
+  로컬에서 DB 재조회값과 응답이 같았다는 사실만으로 다른 OS/JDK에서도 같다고 가정하지 않는다.
+- 시각을 한 번 얻고 저장 컬럼의 정밀도·업무 계약에 맞게 정규화한 단일 변수를 엔티티와 응답에 공통 사용한다.
+  선물의 소수초 없는 TIMESTAMP 상태 시각은 기존 관례대로 `now.truncatedTo(ChronoUnit.SECONDS)`를 사용한다.
+- 정밀도 조정은 해당 업무 저장 경계에서 처리한다. 응답만 절삭하거나 저장/응답에서 각각 `now()`를 호출하지 않는다.
+  시간대 변환은 별도 계약이며 이 문제를 고치기 위해 전역 `toUtcIso`, Jackson, timezone 또는 DDL을 임의 변경하지 않는다.
+- 관련된 메서드만 수정하고 다른 도메인/상태 시각을 무단으로 일괄 정규화하지 않는다. 검증은 테스트 스타일의 왕복 규칙을 따른다.
+- 선례: `82ce6f88`의 `GiftAdminService.cancelGift` 및 선물하기 계획 `P14-T4`.
+  같은 원인으로 수령확인 `deliveredAt` 비교가 재발해 `P16-R1`에서 이 규칙을 명시했다.