2주차: 명세서 작성

.commitlintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      ["feat", "fix", "docs", "style", "refactor", "test", "build", "ci", "perf", "chore"]
+    ],
+    "type-case": [2, "always", "lower-case"],
+    "type-empty": [2, "never"],
+    "subject-case": [0],
+    "subject-empty": [2, "never"],
+    "subject-max-length": [2, "always", 72],
+    "subject-full-stop": [2, "never"],
+    "body-leading-blank": [2, "always"],
+    "scope-empty": [0]
+  }
+}

.gitignore

@@ -15,3 +15,7 @@ __pycache__/
 
 .DS_Store
 Thumbs.db
+node_modules/
+npm-debug.log*
+yarn-error.log
+pnpm-debug.log

.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit "$1"

README.md

@@ -56,4 +56,10 @@ uvicorn main:app --reload
 - ReDoc 문서: http://localhost:8000/redoc
 
 
+### 4. Commit convention & commitlint
+
+- 이 레포는 commitlint/husky를 사용합니다. 클론 후 한 번만 실행:
+  - `npm install`
+  - `git config core.hooksPath .husky` (로컬 기기당 1회)
+
 

docs/prompts/2주차/spec_prompt.md

@@ -0,0 +1,195 @@
+# PrimerFlow specification prompt
+
+## 1. 배경 및 목적
+
+- 작성된 SeqLab 명세서 초안을 바탕으로 개발 팀원들과 공유할 기술 사양을 구체화함. 생물학적 요구사항(1-based Indexing, IUPAC 제한)을 개발 로직에 반영하고, View Culling 및 Auto Layout 등 핵심 기능의 구현 방향과 데이터 스키마를 사전 정의하여 혼선을 방지하고자 함.
+
+## 2. 프롬프트 (User Input)
+
+```text
+너는 technique specification writer다.
+목표: PCR primer design을 기능으로 하는 Seqlab의 software specification를 작성한다.
+독자: 생물학 비전공인 개발자가 이 문서만으로 개발·테스트·출시 판단을 할 수 있어야 한다.
+
+출력 규칙(중요):
+- 반드시 아래 "입력 정보"의 섹션 외의 내용 추가하지 말기.
+- 반드시 아래 "출력 템플릿"의 섹션 순서/제목/번호를 절대 변경하지 말 것.
+- 템플릿에 없는 섹션을 임의로 추가하지 말 것. (필요하면 해당 섹션의 "비고"에 적기)
+- 각 항목을 가능한 한 구체적으로 채우고, 정보가 없으면 "TBD"로 두고 그 이유를 짧게 적기.
+- 모호한 표현(예: 적당히/빠르게/최대한) 금지. 수치·조건·예외를 명시.
+- 요구사항은 MUST/SHOULD/MAY로 구분.
+- 기능 요구사항에는 최소 2개 이상의 예외 케이스를 포함.
+- 마지막에 "확인 질문"은 최대 7개만. 이미 문서에 있는 내용은 다시 묻지 말 것.
+
+입력 정보:
+🧬 PrimeFlow: Frontend Visualization Engine
+
+
+High-Performance PCR Primer Design & Visualization Platform
+대용량 유전자 서열(10,000bp+)을 웹 브라우저에서 지연 없이 분석하고 시각화하는 프론트엔드 엔진 리포지토리입니다.
+📖 프로젝트 개요
+
+PrimeFlow는 생명과학 연구원들이 PCR 프라이머를 설계할 때 겪는 비효율을 해결하기 위한 웹 솔루션입니다. 본 리포지토리(Frontend)는 백엔드에서 분석된 유전자 데이터와 프라이머 후보군을 HTML5 Canvas를 활용해 시각적으로 표현하는 데 집중합니다.
+💡 핵심 기술 (Key Features)
+
+Custom Rendering Engine: DOM 조작 방식이 아닌, Canvas API 기반의 자체 렌더링 엔진을 구현하여 10,000bp 이상의 데이터를 60fps로 부드럽게 렌더링합니다.
+Optimization Algorithms:
+View Culling: 이분 탐색(Binary Search)을 활용하여 화면 밖의 데이터 렌더링을 생략합니다.
+Auto Layout: 그리디(Greedy) 알고리즘을 응용하여 겹치는 프라이머 구간을 자동으로 배치합니다.
+Interactive UX: 행렬 변환(Matrix Transformation)을 적용한 정밀한 Zoom-In/Out 및 Panning 기능을 제공합니다.
+🛠 기술 스택 (Tech Stack)
+
+Core: Next.js 14 (App Router), TypeScript
+Graphics: HTML5 Canvas API (2D Context)
+Styling: Tailwind CSS
+State Management: Zustand
+Data Fetching: SWR / TanStack Query
+Deployment: Vercel
+🏗️ 프로젝트 구조 (Project Architecture)
+
+PrimerFlow-FE/
+├── app/                  # 🌐 [Main] 페이지 및 라우팅 (Next.js App Router)
+│   ├── page.tsx          # 메인 대시보드 화면
+│   └── layout.tsx        # 전역 레이아웃 (Header, Font 등)
+│
+├── components/           # 🧩 UI 컴포넌트 모음
+│   ├── canvas/           # ✨ [Core] 시각화 엔진 (GenomeCanvas, Controls 등)
+│   └── ui/               # 공통 UI (Button, Input, Card 등)
+│
+├── lib/                  # 🧮 순수 함수 및 알고리즘
+│   ├── algorithms/       # [Optimization] 이분 탐색, 레이아웃 알고리즘
+│   ├── math/             # [Math] 좌표 변환(World <-> Screen), 행렬 연산
+│   └── parsers/          # [Data] FASTA 파싱 및 API 데이터 변환
+│
+├── store/                # 💾 전역 상태 관리 (Zustand)
+│   └── useViewStore.ts   # 줌 레벨, 뷰포트 위치 등 관리
+│
+├── docs/                 # 📄 문서 및 프롬프트 아카이브
+│   └── prompts/          # AI 개발을 위한 기능 명세서(Spec) 모음
+│
+└── public/               # 🖼️ 정적 파일 (이미지, 아이콘)
+
+🚀 시작하기 (Getting Started)
+
+사전 요구사항
+
+Node.js 18.17.0 이상
+npm 또는 yarn
+설치 및 실행
+
+# 1. 저장소 클론
+git clone [https://github.com/Seq-Lab/PrimerFlow-FE.git](https://github.com/Seq-Lab/PrimerFlow-FE.git)# 2. 프로젝트 폴더로 이동cd PrimerFlow-FE# 3. 패키지 설치
+npm install# 4. 환경 변수 설정 (.env.local 생성)# (백엔드 API 주소 설정 예시)# echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local# 5. 개발 서버 실행
+npm run dev
+
+프로젝트 구조
+
+PrimerFlow-BE/
+├─ api/
+│  ├─ deps.py
+│  └─ v1/
+│     └─ endpoints/        # 엔드포인트 모음
+├─ schemas/                # Pydantic 모델 모음
+│  └─ schemas.py
+├─ algorithms/             # 알고리즘 모음
+├─ docs/                   # 협업 가이드 문서 모음
+│  └─ prompts/
+│  └─ strategy/
+├─ main.py                 # FastAPI 앱 엔트리포인트 
+├─ requirements.txt        # Python 패키지 목록
+├─ README.md
+└─ .gitignore
+
+개발 환경 설정
+
+1. 가상환경 생성 및 활성화
+
+Windowspython -m venv .venv
+.\.venv\Scripts\Activate.ps1    # PowerShell# 또는
+.\.venv\Scripts\activate.bat    # cmd
+
+macOS / Linuxpython3 -m venv .venvsource .venv/bin/activate
+
+2. 의존성 설치
+
+pip install -r requirements.txt
+
+3. 개발 서버 실행
+
+uvicorn main:app --reload
+
+기본 엔드포인트: http://localhost:8000/
+OpenAPI 문서: http://localhost:8000/docs
+ReDoc 문서: http://localhost:8000/redoc
+
+출력 템플릿:
+1. 개요
+1.1 목적
+1.2 범위(포함/제외)
+1.3 용어 정의
+
+2. 이해관계자/권한
+2.1 사용자 유형
+2.2 권한 매트릭스(역할별 가능/불가)
+
+3. 요구사항
+3.1 기능 요구사항 (FR)
+- FR-001:
+  - 설명:
+  - 입력:
+  - 처리 로직:
+  - 출력:
+  - 예외/에러:
+  - 우선순위(MUST/SHOULD/MAY):
+  - 수용 기준(AC):
+(반복)
+3.2 비기능 요구사항 (NFR)
+- 성능/지연:
+- 가용성:
+- 보안/개인정보:
+- 로깅/감사:
+- 호환성:
+- 접근성:
+
+4. 유저 플로우/시나리오
+4.1 정상 시나리오
+4.2 실패/예외 시나리오
+
+5. API/데이터 설계(해당 시)
+5.1 엔티티/스키마
+5.2 API 목록(엔드포인트/요청/응답/에러코드)
+5.3 상태/이벤트
+
+6. UI 규칙(해당 시)
+6.1 화면 목록
+6.2 화면별 규칙(입력 검증/에러 메시지 문구/빈 상태)
+
+7. 테스트 전략
+7.1 테스트 케이스 요약
+7.2 경계값/부하/보안 테스트
+
+8. 릴리즈/운영
+8.1 롤아웃/마이그레이션
+8.2 모니터링 지표/알람
+8.3 롤백 계획
+
+9. 리스크/의존성
+9.1 리스크
+9.2 외부 의존성
+
+10. 확인 질문(최대 7개)
+```
+
+## 3. AI 응답 요약 (AI Output)
+
+- 핵심 기술 사양 (Core Specifications)
+    - 좌표계 규칙: UI/API는 1-based (생물학 표준), 내부 연산은 0-based (배열 인덱스) 사용. (렌더링 시 변환 필수)
+    - 입력 데이터: A, C, G, T, N 5개 문자만 허용 (IUPAC 확장 문자 불허).
+    - 성능 목표: 10,000bp 이상 데이터를 Canvas로 60fps 렌더링.
+- 기능적 요구사항 및 비기능적 요구사항
+- 유저 시나리오
+
+## 4. 결과 및 적용 (Result)
+
+- GPT와 Gemini에 각각 동일한 프롬프트를 입력하여, 둘의 내용들을 정독한 후 통합한 버전으로 작성하였다.
+- 시나리오와 제한사항들을 설계하여, 이후 개발과정과 테스트 케이스 설계의 기준으로 설정할 수 있다.

docs/spec_API&Data.md

@@ -0,0 +1,82 @@
+# 5. API 및 데이터 설계 (API & Data Design)
+
+## 5.1 엔티티 및 스키마 (Entity Schema)
+
+백엔드와 프론트엔드 간 교환되는 핵심 데이터 모델입니다.
+
+### 1) GenomeSequence
+사용자가 입력한 유전자 서열의 파싱 결과입니다.
+
+```typescript
+interface GenomeSequence {
+  id: string;          // 고유 ID
+  name: string;        // FASTA Header (서열 이름)
+  sequence: string;    // 정규화된 유전자 서열 (A/C/G/T/N...)
+  length_bp: number;   // 서열 길이
+}
+```
+### 2) PrimerCandidate
+
+```typescript
+interface PrimerCandidate {
+  id: string;          // 후보 ID
+  sequence: string;    // 프라이머 서열
+  start_bp: number;    // 시작 위치 (TBD: 0-based vs 1-based 기준 확정 필요)
+  end_bp: number;      // 종료 위치
+  strand: "forward" | "reverse"; // 방향
+  metrics: {           // (TBD) 제공 필드 확정 필요
+    tm_c?: number;       // 녹는점 (Melting Temperature)
+    gc_percent?: number; // GC 함량
+    penalties?: any;     // 패널티 점수 등
+  };
+}
+```
+### 3) PrimerDesignResponse
+```typescript
+interface PrimerDesignResponse {
+  genome: GenomeSequence;        // 분석된 게놈 정보 (요약)
+  candidates: PrimerCandidate[]; // 생성된 후보 목록
+  meta: {                        // (TBD) 메타 데이터
+    params?: any;                  // 요청 시 사용된 파라미터
+    timestamp?: string;            // 생성 시간
+  };
+}
+```
+## 5.2 API 목록 (API Endpoints)
+Note: 백엔드는 FastAPI를 사용하며 OpenAPI(/docs)를 제공합니다. 정확한 경로는 개발 착수 시 확정(TBD)됩니다.
+1) 프라이머 설계 요청 (Design Primers)
+- Endpoint: POST /api/design (예상, TBD)
+- Request:서열 데이터 (Sequence String)
+설계 파라미터 (TBD: Target Product Size, Tm Range 등)
+- Response: PrimerDesignResponse
+- Status Codes & Errors:
+  - 200 OK: 성공
+  - 400 Bad Request: 입력 검증 실패 (잘못된 서열 문자, 파라미터 오류)
+  - 413 Payload Too Large: 입력 서열이 너무 큼 (TBD: 상한선 정책)
+  - 500 Internal Server Error: 서버 내부 알고리즘 오류
+
+2) 헬스 체크 (Health Check)
+- Endpoint: GET / 또는 GET /health (TBD)
+- Response: 서버 상태 문자열 또는 JSON (TBD)
+
+## 5.3 상태 및 이벤트 관리 (State & Events)
+프론트엔드(Zustand)에서 관리해야 할 전역 상태와 주요 이벤트 흐름입니다.
+
+#### 1. 전역 상태 (Global State - Zustand) - 상태 변수
+#### 타입설명
+* viewportStartBpnumber: 현재 뷰포트 시작 위치 (1-based 권장)
+* viewportEndBpnumber: 현재 뷰포트 종료 위치
+* zoomLevelnumber: 캔버스 확대 배율
+* selectedPrimerIdstring: 사용자가 클릭하여 선택한 프라이머 
+* IDhoveredPrimerIdstring(TBD): 마우스 오버 중인 프라이머 
+* IDfilterSortStateobject(TBD): 후보 리스트 필터/정렬 조건
+#### 2. 주요 이벤트 (Key Events) - 데이터 흐름과 UI 반응을 트리거하는 핵심 이벤트
+#### 데이터 처리
+* SEQUENCE_PARSED: FASTA 파싱 완료 시
+* DESIGN_REQUESTED: 설계 요청 시작 (로딩 UI 표시)
+* DESIGN_SUCCEEDED: 결과 수신 완료 (캔버스 렌더링 시작)
+* DESIGN_FAILED: 요청 실패 (에러 배너 표시)
+#### 상호작용
+* VIEWPORT_CHANGED: 줌/팬 동작으로 보고 있는 구간 변경 시
+* PRIMER_SELECTED: 프라이머 클릭 시 (상세 패널 표시)
+* PRIMER_DESELECTED: 빈 공간 클릭 또는 선택 해제 시

docs/spec_QA&Op&Risk.md

@@ -0,0 +1,35 @@
+### 📄 5. `docs/05_QA_Ops_Risks.md`
+
+# 7. 테스트 전략
+
+## 7.1 테스트 케이스
+* **파서:** FASTA 정상/비정상 입력, 허용 문자 검증.
+* **알고리즘:** View Culling 경계값 계산, Auto Layout 겹침 방지.
+* **UI/E2E:** 입력 → 설계 → 렌더링 → 내보내기 흐름 검증.
+* **성능:** 10,000bp 이상 데이터에서 프레임/지연 측정.
+
+## 7.2 경계값 테스트 (Boundary Testing)
+* 서열 길이: 1bp, 9,999bp, 10,000bp.
+* 뷰포트: `start=0`, `start>end` (오류 케이스).
+
+---
+
+# 8. 릴리즈 및 운영
+
+* **배포:** Frontend는 **Vercel**, Backend는 FastAPI.
+* **환경 변수:** `NEXT_PUBLIC_API_URL` 필수.
+* **모니터링:** API 실패율, 주요 UI 액션 실패율.
+* **롤백:** Vercel 배포 히스토리 기반 즉시 롤백.
+
+---
+
+# 9. 리스크 및 의존성
+
+## 9.1 리스크
+* 대용량 데이터 처리 시 브라우저 메모리 증가로 인한 성능 저하.
+* 캔버스 UI의 접근성(스크린 리더) 대응 어려움.
+* **0-based vs 1-based** 좌표계 불일치 시 시각화 오류 발생 가능성.
+
+## 9.2 기술 스택 (Dependencies)
+* **Frontend:** Next.js 16, TypeScript, Tailwind, Zustand, SWR/TanStack Query.
+* **Backend:** FastAPI (Python).

docs/spec_Questions.md

@@ -0,0 +1,11 @@
+# 10. 확인 질문 (To Be Discussed)
+
+개발 착수 전 확정이 필요한 사항들입니다.
+
+1.  **API 스펙 확정:** 설계 요청 API의 정확한 엔드포인트/파라미터/응답 스키마(OpenAPI 기준)가 필요합니다.
+2.  **좌표계 통일:** API 응답의 `start/end`가 **0-based**인지 **1-based**인지 명확해야 합니다. (문서 상 1-based 권장) 
+3.  **IUPAC 확장:** 서열 입력 시 `A/C/G/T/N` 외에 **확장 문자(R, Y 등)**를 허용할 것인지 결정해야 합니다.
+4.  **성능 기준:** 60fps 합격 기준(디바이스 사양, 데이터 상한선) 정의가 필요합니다.
+5.  **내보내기 포맷:** CSV, TSV, FASTA 중 필수 포맷 결정이 필요합니다.
+6.  **필터/정렬:** 프론트엔드 처리 vs 백엔드 파라미터 처리 방식 결정.
+7.  **사용자 권한:** 단일 사용자(무로그인) 모드인지, 관리자 기능이 필요한지 확정 필요.