# TK 안전관리 플랫폼 - 아키텍처 가이드

## 기술 스택

| 분류 | 기술 |
|------|------|
| 프레임워크 | Next.js 15 (App Router, TypeScript, Server Actions) |
| UI | Tailwind CSS + shadcn/ui + Lucide icons + recharts |
| ORM | Drizzle ORM |
| DB | PostgreSQL 16 (컨테이너 `tk-safety-db`) |
| AI 생성 | 맥미니 Ollama qwen3.5:35b-a3b |
| AI 임베딩 | 조립컴 Ollama bge-m3 (1024d) |
| 벡터DB | Qdrant (컬렉션 `safety-docs`) |
| OCR | Apache Tika (port 9998) |
| 인증 | 단일 사용자 (환경변수 비밀번호 + HMAC 쿠키 세션) |

## 포트 매핑

| 서비스 | 호스트:컨테이너 |
|--------|------------------|
| tk-safety (Next.js) | 3100:3000 |
| tk-safety-db (PostgreSQL) | 127.0.0.1:5433:5432 |

## 프로젝트 구조

```
tk-safety/
├── docker-compose.yml      # 서비스 정의
├── Dockerfile              # multi-stage 빌드 (standalone)
├── .env / .env.example     # 환경변수
├── drizzle.config.ts       # Drizzle ORM 설정
├── drizzle/migrations/     # DB 마이그레이션 (자동 생성)
├── uploads/                # 업로드 파일 (documents, photos)
├── docs/                   # 프로젝트 가이드 문서
└── src/
    ├── app/
    │   ├── layout.tsx              # 루트 레이아웃 (다크모드 초기화)
    │   ├── page.tsx                # 인증 리다이렉트
    │   ├── login/page.tsx          # 로그인 페이지
    │   ├── middleware.ts           # 인증 미들웨어
    │   ├── (authenticated)/        # 인증 필요 라우트 그룹
    │   │   ├── layout.tsx          # 사이드바 + 헤더
    │   │   ├── dashboard/          # 대시보드
    │   │   ├── risk-assessment/    # 위험성평가
    │   │   ├── rag/                # 안전 Q&A
    │   │   ├── checklists/         # 점검 체크리스트
    │   │   └── settings/           # 설정
    │   └── api/
    │       ├── auth/               # 로그인/로그아웃 API
    │       ├── ai/                 # AI 엔드포인트 (SSE 스트리밍)
    │       └── health/             # 서비스 헬스체크
    ├── actions/                    # Server Actions (CRUD)
    ├── components/
    │   ├── ui/                     # shadcn/ui 컴포넌트
    │   ├── layout/                 # 사이드바, 헤더, 모바일 내비
    │   ├── dashboard/              # 통계, 차트, 퀵액션
    │   ├── risk-assessment/        # 평가 폼, 매트릭스, AI 패널
    │   ├── rag/                    # 채팅, 문서 관리
    │   └── checklists/             # 템플릿, 점검, NCR
    ├── lib/
    │   ├── db/                     # schema.ts, index.ts
    │   ├── ai/                     # ollama, qdrant, tika, embeddings, prompts
    │   ├── auth.ts                 # 인증 유틸
    │   ├── constants.ts            # 상수 정의
    │   └── utils.ts                # shadcn 유틸
    ├── hooks/                      # use-streaming.ts (SSE)
    └── types/                      # 타입 정의
```

## DB 스키마 (12개 테이블)

### 위험성평가
- `risk_assessments` — 평가 마스터 (제목, 상태, 버전)
- `risk_assessment_hazards` — 유해위험요인 (S×L=위험성)

### RAG 문서
- `rag_documents` — 업로드 문서 (처리 상태 포함)
- `rag_chunks` — 문서 청크 (Qdrant pointId 매핑)
- `rag_conversations` — 대화 세션
- `rag_messages` — 메시지 (질문/답변 + 출처)

### 체크리스트
- `checklist_templates` — 점검 템플릿
- `checklist_template_items` — 템플릿 항목
- `inspections` — 점검 실행 기록
- `inspection_results` — 항목별 결과
- `non_conformances` — 부적합 사항 (NCR)

### 기타
- `app_settings` — 앱 설정 (key-value)

## AI 연동 흐름

### RAG Q&A
```
질문 → bge-m3 임베딩(조립컴) → Qdrant 검색(top-5) → 컨텍스트 + 질문 → qwen3.5 생성(맥미니) → SSE 스트리밍
```

### AI 위험요인 추천
```
작업 설명 → bge-m3 임베딩 → Qdrant 검색(top-3) → 컨텍스트 + 프롬프트 → qwen3.5 JSON 생성 → 구조화 응답
```

### 문서 처리 파이프라인
```
파일 업로드 → Tika 텍스트 추출 → 1500자/200 overlap 청킹 → bge-m3 배치 임베딩(10개씩) → Qdrant 저장
```