sonamu 0.7.53 → 0.8.0

package/src/skills/project/architecture.md

@@ -0,0 +1,373 @@
+# 아키텍처 설계
+
+> 이 문서는 시스템의 전체 구조와 설계 결정을 기록합니다.
+> 개발 과정에서 결정된 아키텍처 사항들을 업데이트합니다.
+
+## 시스템 개요
+
+### 기술 스택
+
+- **Backend**: Sonamu + Node.js + TypeScript
+- **Database**: PostgreSQL
+- **Frontend**: React + TanStack Router + TanStack Query
+- **Auth**: better-auth
+- **Storage**: Local FS / S3 (선택)
+- **Deployment**: (추후 결정)
+
+---
+
+## 데이터베이스 설계
+
+### 주요 테이블
+
+<!--
+예시:
+
+**users**
+- id (PK)
+- email (unique)
+- name
+- role (enum: admin, user)
+- created_at
+
+**posts**
+- id (PK)
+- title
+- content
+- author_id (FK → users)
+- status (enum: draft, published)
+- created_at
+- updated_at
+-->
+
+### 관계도
+
+<!--
+ERD 또는 텍스트로 표현
+
+예시:
+```
+users 1---N posts
+users 1---N comments
+posts 1---N comments
+users N---M roles (user__roles)
+```
+-->
+
+### 인덱스 전략
+
+<!--
+예시:
+- users.email: unique index
+- posts.author_id: index (조회 성능)
+- posts.created_at: index (정렬용)
+- posts(status, created_at): composite index (필터+정렬)
+-->
+
+---
+
+## API 설계
+
+### 엔드포인트 구조
+
+```
+/api/{model}/{method}
+
+예시:
+GET  /api/user/findMany
+GET  /api/user/findById?id=1
+POST /api/user/save
+POST /api/user/del
+```
+
+### 인증/권한
+
+<!--
+예시:
+- Public: 공개 API (로그인 불필요)
+- User: 로그인 필요
+- Admin: 관리자 권한 필요
+- Owner: 본인 데이터만 접근 가능
+-->
+
+### 에러 응답
+
+```json
+{
+  "code": 400,
+  "message": "잘못된 요청입니다",
+  "issues": [
+    {
+      "path": ["email"],
+      "message": "이메일 형식이 올바르지 않습니다"
+    }
+  ]
+}
+```
+
+---
+
+## 프론트엔드 구조
+
+### 라우팅
+
+<!--
+예시:
+```
+/                    # 홈
+/login               # 로그인
+/admin               # 관리자 대시보드
+/admin/users         # 사용자 목록
+/admin/users/:id     # 사용자 상세/편집
+/admin/posts         # 게시글 관리
+```
+-->
+
+### 상태 관리
+
+- **서버 상태**: TanStack Query (자동 캐싱, 리페칭)
+- **폼 상태**: useTypeForm (Zod 검증)
+- **전역 상태**: Context API (최소화)
+
+### 컴포넌트 구조
+
+```
+src/
+├── routes/           # 페이지 컴포넌트
+├── components/       # 재사용 컴포넌트
+├── services/         # API Service (자동생성)
+├── contexts/         # Context Providers
+└── lib/              # 유틸리티
+```
+
+---
+
+## 보안 설계
+
+### 인증
+
+- **세션 기반**: better-auth 사용
+- **쿠키**: httpOnly, secure, sameSite
+- **만료 시간**: 24시간 (연장 가능)
+
+### 권한 관리
+
+<!--
+예시 (연구과제):
+- Role 기반: admin, evaluator, applicant
+- Guard를 통한 API 접근 제어
+- 프론트엔드 라우트 보호
+
+예시 (의료 실험):
+- Role 기반: principal_investigator, researcher, monitor, subject
+- 데이터 접근 레벨: full, anonymized, restricted
+- IRB 승인 상태에 따른 기능 제한
+
+예시 (커머스):
+- Role 기반: admin, seller, customer
+- 리소스 소유권 검증 (본인 주문/상품만 접근)
+- IP 기반 관리자 접근 제한 (선택)
+
+예시 (AI Agent):
+- Role 기반: admin, developer, user
+- 플랜별 기능 제한 (free, pro, enterprise)
+- API 키 기반 인증 (외부 연동)
+
+예시 (의사 소통 도구):
+- Role 기반: admin, moderator, member
+- 채널별 권한 설정 (읽기/쓰기/관리)
+- 의료정보 접근 로그 기록 (감사용)
+-->
+
+### 데이터 보호
+
+<!--
+예시 (일반):
+- 비밀번호: bcrypt 해싱
+- 개인정보: 암호화 저장 (선택)
+- SQL Injection: Knex parameterized query
+- XSS: React 자동 이스케이핑
+
+예시 (의료 실험 - HIPAA 준수):
+- PHI(Protected Health Information): AES-256 암호화
+- 데이터 전송: TLS 1.3
+- 감사 로그: 모든 접근 기록 저장 (삭제 불가)
+- 데이터 익명화: 개인식별정보 분리 저장
+
+예시 (커머스 - PCI DSS 준수):
+- 카드 정보: PG사에 위임 (직접 저장 금지)
+- 결제 토큰: 일회용 사용 후 폐기
+- 주문 정보: 배송 완료 후 일부 마스킹
+
+예시 (AI Agent):
+- 프롬프트 내 민감정보 자동 감지 및 마스킹
+- 대화 히스토리: 사용자별 격리 저장
+- API 키: 해싱 후 저장, 원본은 1회만 표시
+
+예시 (의사 소통 도구):
+- 메시지 E2E 암호화 (선택적)
+- 파일: 바이러스 스캔 + 암호화 저장
+- 의료정보 자동 감지 시 강제 암호화
+- 삭제된 메시지: 30일 후 완전 삭제 (right to be forgotten)
+-->
+
+---
+
+## 파일 저장소
+
+### 업로드 방식
+
+<!--
+예시:
+- 개발: Local FS (packages/api/public/uploaded)
+- 프로덕션: S3
+- URL: /api/public/uploaded/{key}
+-->
+
+### 파일 관리
+
+<!--
+예시 (게시판):
+- 파일명: UUID + 원본파일명
+- 최대 크기: 10MB
+- 허용 확장자: jpg, png, pdf, docx
+- 삭제 정책: 소프트 삭제 (30일 후 영구 삭제)
+
+예시 (의료 실험):
+- 파일명: 익명화된 피험자 ID + 타임스탬프
+- 최대 크기: 100MB (DICOM 이미지 등)
+- 허용 확장자: dcm, jpg, png, pdf, xlsx
+- 버전 관리: 모든 버전 보관 (감사 추적)
+- 암호화: AES-256 (at rest)
+
+예시 (커머스):
+- 상품 이미지: CDN 업로드, 자동 리사이징 (여러 해상도)
+- 최대 크기: 5MB (이미지), 20MB (기타)
+- 썸네일: 자동 생성 (200x200, 400x400, 800x800)
+- 삭제 정책: 상품 삭제 시 즉시 CDN에서 제거
+
+예시 (AI Agent):
+- 업로드 파일: 텍스트 추출 후 임베딩 생성
+- 최대 크기: 10MB
+- 허용 확장자: txt, pdf, docx, md
+- 처리 후 원본 삭제 (임베딩만 보관)
+
+예시 (의사 소통 도구):
+- 파일명: UUID (원본명은 메타데이터로 저장)
+- 최대 크기: 50MB
+- 바이러스 스캔: 업로드 시 필수
+- 미리보기: 이미지/PDF 자동 생성
+- 삭제 정책: 메시지 삭제 시 함께 삭제 (7일 유예)
+-->
+
+---
+
+## 성능 최적화
+
+### 캐싱 전략
+
+<!--
+예시:
+- 정적 데이터: 브라우저 캐시 (1년)
+- API 응답: 필요시 Redis 캐시
+- 쿼리 결과: Sonamu 내장 캐시
+-->
+
+### 데이터베이스 최적화
+
+<!--
+예시:
+- N+1 문제: Subset의 relation으로 해결
+- 대량 조회: 페이지네이션 필수
+- 집계 쿼리: 인덱스 활용
+-->
+
+### 프론트엔드 최적화
+
+<!--
+예시:
+- 코드 스플리팅: TanStack Router 자동 처리
+- 이미지 최적화: lazy loading
+- API 호출: debounce, throttle 적용
+-->
+
+---
+
+## 배포 아키텍처
+
+<!--
+예시:
+```
+[Client Browser]
+       |
+       v
+[Nginx / CloudFront]
+       |
+       v
+[Node.js Server]
+       |
+       v
+[PostgreSQL]
+```
+-->
+
+### 환경 구성
+
+<!--
+예시:
+- Development: localhost:34900
+- Staging: staging.example.com
+- Production: api.example.com
+-->
+
+---
+
+## 모니터링 & 로깅
+
+<!--
+예시:
+- 에러 추적: Sentry (선택)
+- 로그: Winston / Pino
+- 성능: New Relic / Datadog (선택)
+- 헬스체크: /api/health
+-->
+
+---
+
+## 개발 중 아키텍처 결정
+
+<!--
+날짜별로 중요한 아키텍처 결정 기록
+
+### 2024-01-15
+- 파일 저장소: S3 사용 결정 (확장성 고려)
+- 이유: 서버 디스크 용량 제한, CDN 연동 용이
+
+### 2024-01-20
+- 캐싱: Redis 도입 결정
+- 대상: 대시보드 통계, 검색 결과
+- TTL: 5분
+-->
+
+---
+
+## 마이그레이션 전략
+
+<!--
+예시:
+- 스키마 변경: Sonamu migration 사용
+- 데이터 마이그레이션: 별도 스크립트 작성
+- 롤백 계획: 각 마이그레이션마다 down 함수 구현
+-->
+
+---
+
+## 확장성 고려사항
+
+<!--
+예시:
+- 수평 확장: 무상태(stateless) 서버 설계
+- 데이터베이스: 읽기 복제본 추가 가능
+- 파일 저장소: S3로 무제한 확장
+- 캐시: Redis Cluster 고려
+-->

package/src/skills/project/business-logic.md

@@ -0,0 +1,270 @@
+# 비즈니스 로직 상세
+
+> 이 문서는 개발 과정에서 정리되는 비즈니스 규칙과 로직을 기록합니다.
+> 대화를 통해 명확해진 내용들을 추가하여 일관된 구현을 유지합니다.
+
+## 엔티티별 비즈니스 규칙
+
+### [Entity명]
+
+#### 상태 전이
+
+<!--
+예시:
+- draft → published: 관리자만 가능, 필수 필드 검증
+- published → closed: 마감일 이후 자동 전환
+- closed → archived: 90일 후 자동 전환
+-->
+
+#### 검증 규칙
+
+<!--
+예시:
+- 제목: 3-100자, 필수
+- 시작일 < 종료일
+- 예산: 0 이상
+- 첨부파일: 최대 10MB, 5개까지
+-->
+
+#### 계산 로직
+
+<!--
+예시:
+- 총점 = sum(평가항목별 점수 × 가중치)
+- 진행률 = (완료된 마일스톤 / 전체 마일스톤) × 100
+-->
+
+#### 권한 규칙
+
+<!--
+예시:
+- 생성: 로그인한 모든 사용자
+- 수정: 작성자 본인 또는 관리자
+- 삭제: 관리자만
+- 조회: 공개 상태면 모두, 비공개면 작성자/관리자만
+-->
+
+---
+
+## 워크플로우
+
+### [프로세스명]
+
+<!--
+예시: 연구과제 평가 프로세스
+
+1. 공고 발행 (관리자)
+2. 과제 지원 (신청자)
+3. 평가위원 배정 (관리자)
+4. 평가표 작성 (평가위원)
+   - 각 항목별 점수 입력
+   - 총점 자동 계산
+   - 의견 작성
+5. 평가 완료 처리
+   - 모든 평가위원 제출 완료 시
+   - 평균 점수 계산
+6. 선정 결과 발표 (관리자)
+
+예시: 의료 실험 데이터 수집 프로세스
+
+1. 프로토콜 승인 (IRB)
+2. 피험자 모집 및 동의서 획득 (연구원)
+3. 베이스라인 데이터 수집 (연구원)
+4. 데이터 검증 (모니터)
+5. 주기적 follow-up 데이터 수집
+   - 스케줄 알림 자동 발송
+   - 데이터 입력
+   - 이상치 자동 플래그
+6. 최종 분석 (연구책임자)
+
+예시: 커머스 주문 처리 프로세스
+
+1. 장바구니 담기 (고객)
+2. 주문 생성 및 재고 예약 (시스템)
+3. 결제 처리 (PG사 연동)
+4. 결제 확인 및 주문 확정 (시스템)
+5. 상품 준비 (판매자)
+6. 배송 시작 (배송사 연동)
+7. 배송 완료 (배송사 웹훅)
+8. 구매 확정 (고객 또는 자동)
+
+예시: AI Agent 대화 세션 프로세스
+
+1. 세션 생성 (사용자)
+2. 프롬프트 템플릿 선택 (사용자 또는 자동)
+3. 사용자 메시지 입력
+4. 모델 선택 및 파라미터 설정 (자동)
+5. AI 응답 생성 (외부 API 호출)
+6. 응답 저장 및 표시
+7. 사용량 기록 (토큰 수 계산)
+8. 세션 종료 또는 계속
+
+예시: 의사 소통 도구 메시지 전달 프로세스
+
+1. 메시지 작성 (의사)
+2. 메시지 타입 감지 (텍스트/이미지/파일/음성)
+3. 의료정보 포함 여부 자동 감지
+4. 민감 정보 암호화 (필요시)
+5. 채널 멤버에게 전송
+6. 실시간 알림 발송 (푸시/이메일)
+7. 읽음 상태 업데이트
+8. 검색 인덱싱
+-->
+
+---
+
+## 상태 전이 다이어그램
+
+<!--
+Mermaid 다이어그램이나 텍스트로 표현
+
+예시:
+```
+[초안] --발행--> [발행됨] --마감--> [마감됨] --보관--> [보관됨]
+  |                |
+  +----삭제--------+
+```
+-->
+
+---
+
+## 비즈니스 제약사항
+
+<!--
+예시 (연구과제):
+- 한 사용자는 동일 공고에 한 번만 지원 가능
+- 평가위원은 자신의 소속 기관 과제는 평가 불가
+- 평가 시작 후에는 평가 기준 변경 불가
+- 마감일 이후 지원서 수정 불가
+
+예시 (의료 실험):
+- IRB 승인 없이는 데이터 수집 불가
+- 피험자는 언제든 참여 철회 가능
+- 프로토콜 일탈은 24시간 내 보고 필수
+- 데이터 삭제 요청시 익명화 처리 (완전 삭제 불가)
+
+예시 (커머스):
+- 동일 상품 중복 재고 예약 방지
+- 결제 실패시 재고 예약 자동 해제
+- 판매자는 본인 상품만 수정 가능
+- 리뷰는 구매 확정 후에만 작성 가능
+
+예시 (AI Agent):
+- 동시 세션 수 제한 (플랜별)
+- API 호출 실패시 3회 재시도 후 에러
+- 프롬프트 템플릿은 버전 관리 (삭제 불가)
+- 과거 대화는 수정 불가 (읽기 전용)
+
+예시 (의사 소통 도구):
+- 채널 멤버만 메시지 접근 가능
+- 삭제된 메시지는 7일간 복구 가능
+- 민감 정보 포함 채널은 외부 초대 불가
+- 파일은 바이러스 검사 후 업로드
+-->
+
+---
+
+## 알림 규칙
+
+<!--
+예시 (연구과제):
+- 공고 발행 시: 전체 사용자에게 이메일 발송
+- 평가 배정 시: 해당 평가위원에게 알림
+- 평가 마감 3일 전: 미제출 평가위원에게 알림
+- 선정 결과 발표 시: 지원자에게 개별 알림
+
+예시 (의료 실험):
+- 방문 예정일 3일 전: 피험자에게 SMS 알림
+- 데이터 이상치 감지: 연구원에게 즉시 알림
+- 프로토콜 일탈 발생: 연구책임자에게 즉시 알림
+- 동의서 만료 30일 전: 연구원에게 갱신 알림
+
+예시 (커머스):
+- 주문 확정: 판매자에게 즉시 알림
+- 배송 시작: 고객에게 추적번호 포함 알림
+- 재고 부족 (임계값 이하): 판매자에게 알림
+- 구매 확정: 판매자에게 정산 예정 알림
+
+예시 (AI Agent):
+- 사용량 80% 도달: 사용자에게 경고
+- API 오류 발생: 관리자에게 즉시 알림
+- 세션 타임아웃 5분 전: 사용자에게 연장 여부 확인
+- 새 모델 추가: 전체 사용자에게 공지
+
+예시 (의사 소통 도구):
+- 새 메시지: 채널 멤버에게 실시간 푸시
+- 멘션 시: 해당 사용자에게 강조 알림
+- 파일 업로드 완료: 업로더에게 알림
+- 읽지 않은 메시지 100개 이상: 일일 요약 이메일
+-->
+
+---
+
+## 예외 처리
+
+<!--
+예시:
+- 중복 지원 시도: "이미 지원한 공고입니다" 에러
+- 권한 없는 수정: "권한이 없습니다" 에러
+- 마감 후 지원: "마감된 공고입니다" 에러
+- 필수 필드 누락: 구체적인 필드명 포함 에러
+-->
+
+---
+
+## 데이터 일관성
+
+<!--
+예시 (연구과제):
+- 과제 삭제 시: 관련 평가 데이터도 함께 삭제 (CASCADE)
+- 사용자 삭제 시: 작성한 콘텐츠는 유지하되 "탈퇴한 사용자"로 표시
+- 평가표 제출 후: 평가 항목 변경 불가 (버전 관리)
+
+예시 (의료 실험):
+- 피험자 탈퇴 시: 데이터는 익명화하여 보존
+- 프로토콜 변경 시: 기존 버전도 보관 (감사 추적)
+- 동의서 철회 시: 향후 데이터 수집 중단, 기존 데이터는 익명화
+
+예시 (커머스):
+- 상품 삭제 시: 주문 히스토리는 유지 (스냅샷)
+- 주문 취소 시: 재고 복원, 결제 환불 처리
+- 판매자 탈퇴 시: 진행 중인 주문 완료 후 계정 비활성화
+
+예시 (AI Agent):
+- 프롬프트 템플릿 삭제 시: 기존 세션은 유지 (soft delete)
+- 사용자 삭제 시: 대화 히스토리 익명화
+- 모델 변경 시: 기존 세션은 기존 모델 설정 유지
+
+예시 (의사 소통 도구):
+- 채널 삭제 시: 메시지 30일간 보관 후 영구 삭제
+- 사용자 탈퇴 시: 메시지는 유지하되 "탈퇴한 사용자"로 표시
+- 파일 삭제 시: 참조하는 메시지가 있으면 soft delete
+-->
+
+---
+
+## 성능 고려사항
+
+<!--
+예시:
+- 대시보드 통계: 캐시 적용 (5분 TTL)
+- 검색: 인덱스 적용 필요 필드 명시
+- 파일 업로드: 비동기 처리
+- 대량 데이터: 페이지네이션 필수
+-->
+
+---
+
+## 개발 중 논의 내역
+
+<!--
+날짜별로 대화 중 정리된 내용 기록
+
+### 2024-01-15
+- 평가 점수 계산 방식 확정: 가중치 평균 사용
+- 동점자 처리: 특정 항목 우선순위로 결정
+
+### 2024-01-20
+- 첨부파일 저장 방식: S3 사용 결정
+- 파일명 중복 처리: UUID 접두사 추가
+-->