docs(architecture): 코루틴 환경 @Transactional 사용 가이드 추가 (#166)

[jskjw157]

요약

PR #238에서 MetadataRefreshServiceImpl.refreshEvent suspend 함수의 @Transactional을 제거하고 동기 TransactionalMetadataUpdater로 위임한 패턴을, 팀 차원에서 재발 방지/온보딩용으로 문서화했다.

배경

• suspend 함수는 Dispatchers.IO/withContext 등으로 스레드를 갈아타는데, Spring @Transactional은 AOP 프록시가 시작 스레드의 TransactionSynchronizationManager ThreadLocal에 트랜잭션을 매단다.
• 결과적으로 suspend 진입점에 @Transactional을 붙이면 트랜잭션이 코루틴과 함께 이동하지 못해 부분 커밋·예측 불가 롤백·연결 누수가 발생한다.
• 관련 이슈: [Bug] MetadataRefreshService suspend 함수 @Transactional 제거 #166, fix(security): runCatching + @Transactional 트랜잭션 격리 실패 #224

문서 구성

docs/architecture/coroutine-transactional.md (한국어, 7개 섹션):

1. 배경 — AOP 프록시 + ThreadLocal 메커니즘과 코루틴 스레드 호핑 다이어그램
2. 안티패턴 — suspend에 @Transactional을 붙였을 때의 실패 모드
3. 권장 패턴 — 동기 @Component로 위임 (TransactionalMetadataUpdater 코드 예시)
4. REQUIRES_NEW 채택 이유 — 배치 부분 성공 격리, REQUIRED와의 비교
5. 회귀 방지 테스트 — shouldIsolateTransactionsBetweenEvents 본문 인용
6. 리뷰/구현 체크리스트 (6개 항목)
7. 참고 자료 — [Bug] MetadataRefreshService suspend 함수 @Transactional 제거 #166, fix(security): runCatching + @Transactional 트랜잭션 격리 실패 #224, Spring/Kotlin 공식 문서 링크

리뷰 포인트

• 코드 예시가 실제 TransactionalMetadataUpdater.kt 패턴과 일치하는지
• 한국어 톤/용어가 다른 docs/architecture/ 문서들과 어울리는지
• 누락된 실패 모드나 추가하면 좋은 체크리스트 항목 제안

영향 범위

문서 단일 파일 추가 (docs/architecture/coroutine-transactional.md, +238). 코드/빌드 변경 없음.