260715_0

docs/wiki/concepts/common_util.md

@@ -0,0 +1,35 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B01_Dashboard/B01_backend]]", "[[B03_FileInput/B03_backend]]", "[[B04_wf1_Surface/B04_backend]]", "[[B05_wf2_Route/B05_backend]]", "[[B06_wf3_ProfileCross/B06_backend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/structure.md, raw/guidelines/backend.md
+---
+
+# 공통 유틸 (common_util/)
+
+> 둘 이상의 페이지가 실제로 공유하는 경로·원자적 파일쓰기·기하 유틸만 이 폴더에 배치 (migration_plan.md 2.2)
+
+| 파일 | 역할 | 사용처 |
+|---|---|---|
+| `common_util_validate.ts` | 프론트 1차 유효성 검사 (이메일/빈값/최소길이) | 전 페이지 |
+| `common_util_auth.py` | 비밀번호·OTP·세션 쿠키·권한 검증 | 전 페이지 → [[auth_rbac]] |
+| `common_util_auth_repository.py` | 인증·조직·관리 Raw SQL 저장소 | 인증 관련 |
+| `common_util_email.py` | 비동기 SMTP 발송+재시도(최대3회) | OTP/승인 알림 |
+| `common_util_email_templates.py` | 인증·조직 알림 이메일 템플릿 | common_util_email.py |
+| `common_util_string.ts` | 문자열 유틸 | 미상세 |
+| `common_util_storage.py` | 프로젝트·워크플로우 단계별 저장 경로 | → [[storage_paths]] |
+| `common_util_json.py` | JSON 원자적 저장 | workflow.json 등 |
+| `common_util_workflow.py` | 공유 workflow.json 상태 처리 | ⚠️ [[workflow_state]] 재설계로 대체/정리 예정 |
+| `common_util_resource_monitor.py` | 시스템 리소스 계측(2분 주기) + log + DB 기록 | `sample_resources_loop()` → [[B01_Dashboard/B01_backend|B01_Dashboard]] |
+| `common_util_format.py` | 포맷 유틸 | 미상세 |
+
+## 이메일 발송 (common_util_email.py)
+- 개발: Google Gmail SMTP / 상용: Google Workspace 또는 AWS SES
+- 발송 유형: OTP, 가입확인, 팀원승인요청(ADMIN), 승인/거부결과, 회사참여신청(SYSTEM_ADMIN), 인증갱신알림
+
+## 리소스 모니터링 (common_util_resource_monitor.py)
+- `main.py` lifespan에서 `asyncio.create_task` 등록/취소
+- 계측: `psutil.cpu_percent`, `psutil.virtual_memory().percent`, `shutil.disk_usage`
+- 이중 기록: `system_resources` 테이블 (DB) + `log/system_resources.log` (탭 구분 1줄, `.gitignore`)
+- 30일 롤링 삭제 (DB `DELETE`, 로그파일 오래된 줄 제거)