# Kkiit 사용자 가이드

이 문서는 Kkiit 화면을 쓰는 **구매자와 판매자**를 위한 안내입니다. 설치·설정·운영은
[관리자 가이드](ADMIN_GUIDE.md)에서 다룹니다. 화면 캡처는 v0.2.0 을 실제로 띄워 찍었고,
등장하는 이름·이메일·금액은 모두 가짜 데이터입니다.

## 1. 이 제품이 하는 일

Kkiit 는 사람·기업·AI Agent 가 제공하는 전문 서비스(디자인, 개발, 영상, 문서, 데이터 분석 등)를
`재능 상품 → 요구사항 → 주문 → 작업 → 납품 → 구매확정 → 정산` 한 흐름으로 사고파는
마켓플레이스입니다. 인터넷이 끊긴 사내망에서도 그대로 동작합니다.

**구매자**는 상품을 찾아 요구사항을 적고 결제하면, 작업이 끝날 때까지 돈이 에스크로에 보관됩니다.
납품물을 확인하고 구매확정하면 그때 판매자 정산이 잡히고, 문제가 있으면 수정 요청이나 분쟁 접수로
돈을 멈출 수 있습니다.

**판매자**는 상품과 패키지·추가 옵션·주문 양식을 등록하고, 주문이 들어오면 작업 시작 → 납품 →
구매확정 순서로 진행합니다. 수익·정산 화면에서 지급 예정·보류·누적 지급을 봅니다.

## 2. 처음 5분 — 로그인부터 첫 주문까지

1. 브라우저에서 Kkiit 주소를 엽니다(관리자가 알려 준 주소, 예: `http://kkiit.internal:8080`).
   로그인 없이도 상품을 둘러볼 수 있습니다.
2. 오른쪽 위 **로그인** 을 누릅니다. 계정이 없으면 **새 계정 만들기** 로 아이디·이메일·표시 이름과
   12자 이상의 비밀번호를 입력합니다. 관리자가 소셜 로그인을 켰다면 그 버튼도 함께 보입니다.

   ![로그인 — 아이디 또는 이메일과 비밀번호로 들어간다](assets/guide/login.png)

3. 첫 화면에서 원하는 일을 검색하거나 카테고리 칩(디자인, 개발·IT, 영상·사진 …)을 눌러 상품을
   찾습니다.

   ![서비스 찾기 — 검색창과 카테고리, 가격·납기·제공 방식 필터](assets/guide/marketplace.png)

4. 상품 카드를 누르면 상세 화면이 열립니다. 오른쪽 **주문 구성** 에서 패키지와 추가 옵션을 고르고,
   왼쪽 **주문 전 정보** 양식에 요구사항을 적은 뒤 **주문하기** 를 누릅니다(로그인 전에는
   **로그인하고 주문하기** 로 표시됩니다). 쿠폰이 있으면 **쿠폰 코드** 에 넣고 **적용** 을 눌러
   결제 금액이 줄어드는지 확인합니다.

   ![상품 상세 — 패키지·추가 옵션·쿠폰을 고르고 요구사항을 적는다](assets/guide/talent-detail.png)

5. `주문을 만들었습니다.` 안내와 함께 주문 작업 화면으로 이동합니다. **결제하고 작업 준비** 를
   누르면 `결제를 에스크로에 보관했습니다.` 라고 표시되고 판매자에게 알림이 갑니다. 이제 판매자가
   **작업 시작** 을 누르면 진행 상황을 같은 화면의 **대화** 탭에서 주고받습니다.

## 3. 화면별 사용법

### 3.1 서비스 찾기(첫 화면)

![추천 서비스 — 카드마다 제공 방식, 판매자 등급, 평점, 납기와 시작가가 보인다](assets/guide/marketplace-results.png)

- 검색창에는 "관리자 페이지가 포함된 회사 홈페이지를 300만원 안에서" 처럼 자연어로 적어도 됩니다.
- **최소 가격·최대 가격·납기·제공 방식(HUMAN / AI / HYBRID)** 필터와 **정렬** 로 좁힙니다.
- 카드의 하트를 누르면 **찜한 서비스** 에 저장됩니다(로그인 필요).
- 배지 `신규` 는 거래 실적이 아직 없는 판매자, 별점 옆 숫자는 받은 후기 수입니다.

### 3.2 상품 상세

- 상단에 제공 방식, 카테고리, 판매자 이름(누르면 판매자 프로필), 등급과 평점이 보입니다.
- **서비스 소개**, 포함·불포함 범위, FAQ, **구매자 후기** 를 아래로 내려 확인합니다.
- **판매자에게 문의하기** 로 주문 전에 질문할 수 있습니다. 답변은 개인화 페이지 **상품 문의** 에
  모입니다(`문의를 보냈습니다. 프로필 → 상품 문의에서 답변을 확인하세요.`).
- 오른쪽 **주문 구성** 의 `품질 NN점` 은 거래 실적에서 계산한 상품 품질 점수입니다.
- 조직에 속한 계정이라면 주문 시 **개인 명의** 또는 **조직 명의** 를 고를 수 있습니다. 조직 명의
  주문은 조직 예산에서 차감됩니다.
- 신고가 필요하면 제목 옆 **신고** 를 누릅니다.

### 3.3 내 주문

![내 주문 — 구매·판매 주문을 상태별로 본다](assets/guide/orders.png)

헤더의 **내 주문** 에서 구매한 주문과 판매하는 주문을 한 목록으로 봅니다. **구분**(구매/판매)과
**상태** 로 거릅니다. 상태 배지의 뜻은 다음과 같습니다.

| 배지 | 뜻 |
|---|---|
| 주문 생성 · 결제 대기 | 요구사항은 적었지만 아직 결제하지 않음. 일정 시간 안에 결제하지 않으면 자동 만료됩니다 |
| 결제 완료 · 요구사항 대기 · 작업 준비 | 결제가 에스크로에 들어갔고 판매자가 시작하기를 기다림 |
| 작업 중 | 판매자가 작업을 시작함 |
| 납품 완료 | 판매자가 결과물을 올림. 구매자가 확인할 차례 |
| 수정 요청 | 구매자가 수정을 요청함 |
| 구매확정 · 거래 완료 | 구매자가 결과물을 받아들였고 정산이 잡힘 |
| 분쟁 | 분쟁이 접수되어 운영자가 검토 중. 정산이 멈춰 있음 |
| 취소 요청 · 취소 · 환불 | 종료되었거나 종료 중인 주문. 에스크로 잔액은 구매자에게 돌아감 |

### 3.4 주문 작업 화면

주문을 누르면 열립니다. 왼쪽은 **개요 · 대화 · 납품 · 수정 · 이력** 탭, 오른쪽 **다음 작업** 에는
지금 상태에서 할 수 있는 일만 나타납니다.

![주문 작업 화면 — 개요 탭과 오른쪽 '다음 작업'](assets/guide/order-workspace.png)

![대화 탭 — 구매자와 판매자가 주고받은 메시지](assets/guide/order-workspace-messages.png)

구매자가 하는 일:

- **결제하고 작업 준비** — 주문 생성 직후.
- **구매확정** — 납품 완료 후 결과물을 확인했을 때. 리뷰를 함께 남기려면 **리뷰 등록하고 완료** 를
  누릅니다.
- **수정 요청** — 납품 완료 상태에서 수정할 내용을 적어 보냅니다. 상품에 적힌 무료 수정 횟수를
  다 쓰면 `이 주문에 포함된 수정 요청 N회를 모두 사용했습니다.` 라고 막힙니다.
- **납기 초과로 취소하고 환불** — 납기가 지났는데 진행이 없을 때.

판매자가 하는 일:

- **작업 시작** — 결제가 끝난 주문에서.
- **납품하기** — 납품 내용을 적고 필요하면 **결과 파일 첨부** 로 파일을 올립니다. 파일마다
  SHA-256 이 표시됩니다.

둘 다 할 수 있는 일:

- **대화** 탭에서 메시지와 첨부를 주고받습니다. 새 메시지는 실시간으로 표시됩니다.
- **분쟁 접수** — 작업 중부터 구매확정 직후까지, 사유를 5자 이상 적어 보냅니다. 접수하면 정산이
  보류되고 운영자가 검토합니다. 한 주문에 열린 분쟁은 하나뿐입니다.
- **이 주문 신고**.

![이력 탭 — 결제부터 구매확정까지 시간순 기록](assets/guide/order-workspace-timeline.png)

### 3.5 알림

헤더의 종 아이콘에 읽지 않은 알림 수가 표시됩니다. 주문 상태 변화, 새 메시지, 문의 답변, 견적
도착, 정산 보류·해제 등이 여기에 옵니다. **모두 읽음** 으로 한 번에 지웁니다.

![알림 — 종 아이콘을 누르면 최근 알림이 열린다](assets/guide/notifications.png)

받고 싶지 않은 이벤트는 개인화 페이지 **알림 설정** 에서 끕니다.

### 3.6 개인화 페이지

헤더 오른쪽 이름을 누르고 **개인화 페이지** 를 선택합니다. 왼쪽 메뉴는 계정 종류에 따라 조금
다릅니다 — 판매자 계정에는 **수익·정산**, **받은 후기** 가, 조직 기능이 켜진 배포에는 **조직** 이
추가로 보입니다.

#### 내 프로필

![내 프로필 — 표시 이름과 소개를 고친다](assets/guide/profile.png)

#### API 키

![API 키 — 자동화 스크립트나 AI Agent 가 쓸 키를 만든다](assets/guide/profile-keys.png)

**키 만들기** 로 이름·권한(scope)·허용 IP 대역·분당 요청 한도를 정합니다. **키 원문은 만든 직후 한
번만 보입니다** — 복사해 두세요. 유출이 의심되면 **회전**(새 원문 발급) 또는 **폐기** 합니다.
MCP 로 AI Agent 를 연결하려면 `mcp.use` 권한을 포함한 키가 필요합니다(자세한 것은
[docs/mcp.md](mcp.md)).

#### 로그인 보안

![로그인 보안 — TOTP 2단계 인증, 비밀번호 변경, 로그인된 기기](assets/guide/profile-security.png)

- **MFA 설정** — Authenticator 앱으로 QR 을 읽고 6자리 코드를 넣어 **활성화 확인** 합니다. 이후
  로그인할 때 **인증 앱 코드** 를 함께 묻습니다. 코드는 한 번만 쓸 수 있습니다.
- **비밀번호 변경** — 바꾸면 **지금 사용 중인 기기를 제외한 모든 로그인이 종료** 됩니다.
- **로그인된 기기** — 모르는 접속이 있으면 **다른 기기 로그아웃** 으로 즉시 끊고 비밀번호를
  바꿉니다.

#### 찜한 서비스

![찜한 서비스 — 하트를 누른 상품 목록](assets/guide/profile-favorites.png)

#### 조직

![조직 — 조직 계정, 구성원 역할과 예산](assets/guide/profile-organizations.png)

**조직 만들기** 로 조직을 만들고 **구성원 추가** 로 동료를 초대합니다. **예산 추가** 로 기간별
예산을 두면 조직 명의 주문 시점에 차감되고, 취소·환불되면 되돌아옵니다. 예산을 넘는 주문은
거부됩니다.

#### 판매자·상품 (판매자)

![판매자·상품 — 내 상품 목록과 30일 조회·주문·전환율](assets/guide/profile-seller.png)

- 처음이라면 **판매자로 전환** 을 눌러 판매자 프로필(소개, 기술, **동시 진행 가능** 건수)을 적습니다.
- **새 상품** → 초안을 만든 뒤 **수정** 에서 패키지·추가 옵션·주문 양식·FAQ 를 채우고
  **공개 요청** 을 누릅니다. 운영 정책에 따라 바로 공개되거나 검토 대기(`review_pending`)로 갑니다.
- 상품마다 **30일 조회·주문·전환율**, 누적 주문·완료, 찜 수가 보입니다. 조회가 없으면 카테고리와
  상품명을, 조회는 있는데 주문이 없으면 가격과 소개를 점검하라고 안내합니다.
- **판매 중지 / 판매 재개 / 보관** 으로 상태를 바꿉니다. 판매 중지해도 진행 중인 주문은 계속됩니다.
- **동시 진행 가능** 건수만큼만 새 주문을 받습니다. 넘치면 상품 상세의 주문 버튼이
  **지금은 주문 마감** 으로 바뀌고 `이 판매자가 동시에 진행할 수 있는 주문을 모두 소화하고 있어
  지금은 주문할 수 없습니다.` 가 표시됩니다.

판매자 공개 프로필은 상품 상세의 판매자 이름을 누르면 누구나 볼 수 있습니다.

![판매자 공개 프로필 — 소개, 등급, 상품과 포트폴리오](assets/guide/seller-public.png)

#### 수익·정산 (판매자)

![수익·정산 — 지급 예정, 보류 중, 누적 지급과 수수료 내역](assets/guide/profile-earnings.png)

구매확정된 주문마다 플랫폼 수수료를 뺀 정산이 잡힙니다. **지급 예정** 은 운영 정책의 지연일이
지나면 지급 검토에 들어가고, 위험 평가나 분쟁으로 **보류 중** 이 되면 알림으로 사유를 받습니다.
실제 지급은 운영자가 처리합니다.

#### 받은 후기 (판매자)

![받은 후기 — 구매자 후기와 답글](assets/guide/profile-reviews.png)

#### 견적 프로젝트

![견적 프로젝트 — 견적 요청과 받은 견적 비교](assets/guide/profile-projects.png)

정해진 상품이 없을 때 **프로젝트 등록** 으로 요구사항·예산·희망 기한을 올리면 판매자들이
**견적 제출** 합니다. **견적 비교** 에서 금액·납기·범위를 나란히 보고 **이 견적으로 주문** 을
누르면 그 견적 금액으로 주문이 만들어집니다. (관리자가 `smart_quote` 기능을 켠 배포에서만
보입니다.)

#### 상품 문의

![상품 문의 — 주문 전 질문과 답변](assets/guide/profile-inquiries.png)

#### 알림 설정

![알림 설정 — 이벤트별 수신 여부와 웹훅](assets/guide/profile-notifications.png)

이벤트별로 알림함 수신을 끄고 켭니다. 아래 **웹훅** 에 주소를 등록하면 같은 이벤트를 서명된
`POST` 로 받을 수 있습니다(서명 검증 방법은 README "이벤트와 알림" 절).

#### 내 신고

![내 신고 — 내가 접수한 신고와 처리 결과](assets/guide/profile-reports.png)

## 4. 자주 하는 작업

### 쿠폰으로 할인받아 주문하기

상품 상세 **쿠폰 코드** 에 코드를 넣고 **적용** 을 누릅니다. 결제 금액이 바뀌면 그대로 주문합니다.
`쿠폰을 찾을 수 없습니다.` 가 나오면 코드 오타이거나 사용 기간·횟수가 끝난 것입니다. 할인은
플랫폼이 부담하므로 판매자 정산은 줄지 않습니다.

### 납품물에 문제가 있을 때

1. **수정 요청** — 무료 수정 횟수 안에서 구체적으로 적습니다. 판매자가 다시 납품합니다.
2. 대화로 해결되지 않으면 **분쟁 접수**. 정산이 멈추고 운영자가 납품물·대화·이력을 보고
   전액 환불 / 부분 환불 / 판매자 지급 중 하나로 결정합니다. 결과는 알림으로 옵니다.

### 납기가 지났는데 소식이 없을 때

주문 작업 화면 **다음 작업** 에 **납기 초과로 취소하고 환불** 이 나타납니다. 누르면 주문이 취소되고
에스크로 금액이 돌아옵니다. 먼저 **대화** 로 한 번 물어보는 편이 보통 빠릅니다.

### 판매자로 시작하기

개인화 페이지 → **판매자·상품** → **판매자로 전환** → 프로필 저장 → **새 상품** → **수정** 에서
패키지(BASIC/STANDARD/PREMIUM)와 주문 양식 채우기 → **공개 요청**. 첫 상품이 공개되면 첫 화면에
노출됩니다. 실적이 쌓이면 신뢰 점수·등급이 올라가 검색과 추천 순위에 반영됩니다.

### AI Agent 로 Kkiit 쓰기

**API 키** 에서 `mcp.use` 와 필요한 거래 권한을 포함한 키를 만들고 `/mcp` 엔드포인트에
`Authorization: Bearer <키>` 로 연결합니다. 도구 목록과 예시는 [docs/mcp.md](mcp.md) 에 있습니다.

## 5. 막혔을 때

| 화면에 보이는 문구 | 뜻과 할 일 |
|---|---|
| `아이디 또는 비밀번호가 올바르지 않습니다.` | 아이디는 이메일로도 넣을 수 있습니다. 정지된 계정도 같은 문구가 나옵니다 — 계속되면 관리자에게 확인합니다 |
| `인증 앱의 6자리 코드를 입력해 주세요.` | MFA 가 켜진 계정입니다. 인증 앱의 현재 코드를 넣습니다. 앱을 잃어버렸으면 관리자에게 MFA 초기화를 요청합니다 |
| `인증 코드가 올바르지 않습니다.` | 시간이 어긋났거나 방금 쓴 코드를 다시 쓴 것입니다. 다음 코드를 기다립니다 |
| `요청이 너무 잦습니다. 잠시 후 다시 시도해 주세요.` | 로그인·쿠폰 확인·문의 등에 분당 한도가 있습니다. 1분 뒤 다시 합니다 |
| `로그인 세션이 만료되었습니다. 다시 로그인해 주세요.` | 세션 시간이 지났습니다. 다시 로그인하면 보던 화면으로 돌아갑니다 |
| `현재 신규 가입을 받지 않습니다.` | 관리자가 가입을 닫았습니다. 계정은 관리자에게 요청합니다 |
| `로컬 로그인이 비활성화되어 있습니다.` | 이 배포는 소셜/OIDC 로그인만 씁니다. 로그인 화면의 제공자 버튼을 누릅니다 |
| `본인의 상품은 주문할 수 없습니다.` | 판매자 계정으로 자기 상품을 주문한 것입니다. 다른 계정으로 테스트합니다 |
| `주문 가능한 상품을 찾을 수 없습니다.` | 상품이 비공개·판매 중지되었거나 판매자가 정지되었습니다 |
| `이 판매자는 동시에 진행할 수 있는 주문 N건을 모두 소화하고 있습니다.` | 판매자 동시 진행 한도입니다. 잠시 후 다시 하거나 문의를 남깁니다 |
| `현재 주문 상태에서는 결제할 수 없습니다.` | 이미 결제했거나 만료·취소된 주문입니다. 내 주문에서 상태를 확인합니다 |
| `납품 완료 상태에서만 구매확정할 수 있습니다.` | 아직 납품이 오지 않았습니다 |
| `이 주문에 포함된 수정 요청 N회를 모두 사용했습니다.` | 무료 수정 횟수 소진. 구매확정하거나 분쟁을 접수합니다 |
| `이미 처리 중인 분쟁이 있습니다.` | 한 주문에는 분쟁 하나만 열립니다. 운영자 결정을 기다립니다 |
| `분쟁 중인 주문은 분쟁 처리로 종료해 주세요.` | 분쟁 중에는 취소·확정이 막힙니다. 운영자가 처리합니다 |
| `조직 계정 기능이 비활성화되어 있습니다.` | 관리자가 `enterprise` 기능을 껐습니다. 개인 명의로 주문합니다 |
| `쿠폰을 찾을 수 없습니다.` | 코드 오타, 기간·횟수 종료, 최소 주문 금액 미달 중 하나입니다 |
| `API 키의 분당 요청 한도를 초과했습니다.` | 키에 설정한 한도입니다. 키 설정에서 한도를 올리거나 호출 간격을 둡니다 |
| `교차 사이트 요청이 차단되었습니다.` / `요청 출처를 확인할 수 없습니다.` | 다른 주소에서 열린 페이지에서 요청한 것입니다. 관리자가 알려 준 주소로 직접 접속합니다 |

관리자에게 넘겨야 하는 일: 계정 정지 해제, MFA 초기화, 가입 허용, 소셜 로그인 연동, 분쟁 결정,
정산 지급, 쿠폰 발급, 기능(견적·조직·AI) 켜기.

## 6. 용어

| 용어 | 뜻 |
|---|---|
| 재능 상품 | 판매자가 등록한 서비스 단위. 패키지·추가 옵션·주문 양식을 가집니다 |
| 패키지 | 같은 상품의 가격·납기 단계(BASIC / STANDARD / PREMIUM / CUSTOM) |
| 추가 옵션 | 패키지 위에 더하는 유료 항목. 가격과 추가 납기는 상품이 정합니다 |
| 주문 양식(주문 전 정보) | 판매자가 정한 요구사항 입력 항목 |
| 에스크로 | 결제 후 구매확정까지 플랫폼이 보관하는 금액 |
| 구매확정 | 납품물을 받아들이고 정산을 시작시키는 구매자의 확인 |
| 정산 | 구매확정 금액에서 플랫폼 수수료를 뺀 판매자 지급 예정액 |
| 분쟁 | 운영자에게 결정을 맡기는 절차. 접수 즉시 정산이 보류됩니다 |
| 견적 프로젝트(RFQ) | 상품 대신 요구사항을 올려 판매자 견적을 받는 방식 |
| 조직 | 여러 계정이 함께 쓰는 예산과 주문 명의 |
| 신뢰 점수·등급 | 거래 실적으로 계산되는 판매자 지표. 검색·추천 순위에 반영됩니다 |
| 품질 점수 | 상품 단위의 실적 지표. 상품 상세 오른쪽에 표시됩니다 |
| 제공 방식 | HUMAN(사람) / AI(에이전트) / HYBRID(혼합) |
| MCP | AI Agent 가 Kkiit 도구를 호출하는 프로토콜. API 키의 `mcp.use` 권한이 필요합니다 |