# 디자인 저장소 v3 카드 구조

v3의 목적은 디자인 사례를 "근거가 붙은 문장형 판단 카드"로 저장하는 것입니다.  
사람이 raw YAML을 열어도 읽을 수 있어야 하고, RAG는 문장 단위 판단을 검색해야 하며, 필요하면 원본 자료로 되돌아가 검증할 수 있어야 합니다.

## 핵심 변화

| v2 | v3 |
| --- | --- |
| `value`, `values` 중심 | `statement` 중심 |
| `source_label` | `grounding` |
| `confidence: 높음/중간/낮음` | `confidence: Gold/Silver/Bronze/No data` |
| `quote_snippets`, `evidence`, `source_passages` | 판단 안의 `basis`로 흡수 |
| `quote_id`, `evidence_id`, `passage_id` 추적 | `basis.source_ref`와 `basis.locator`로 원본 위치 표시 |
| 빈 `정보 없음` 필드 반복 | 본문에서는 생략하고 `missing_fields`에만 기록 |
| raw HTML, 원문 전체, 로그가 카드 안에 섞임 | `raw_refs`로 카드 밖 원본 파일 참조 |

## 판단 필드 공통 구조

8가지 카테고리와 설계 이유의 하위 속성은 모두 같은 형태를 가집니다.

```yaml
statement: 사람이 읽는 완성 문장
tags:
  - RAG/필터/매핑용 짧은 값
grounding: original_text | original_plus_inference | image_observation | image_plus_inference | inference | no_data
confidence: Gold | Silver | Bronze | No data
basis:
  - summary: 근거를 한 문장으로 설명
    quote: 짧은 원문 인용
    source_ref: raw/behance/newbe/source.txt
    locator: description paragraph 1
```

### grounding 정의

| 값 | 뜻 | 사용처 |
| --- | --- | --- |
| `original_text` | 원문에 직접 적힌 내용 | 사실 확인, 보고서 근거 |
| `original_plus_inference` | 원문 단서가 있고 해석이 일부 들어간 내용 | 리서치 문장, 사용자/문제 해석 |
| `image_observation` | 이미지에서 직접 관찰한 내용 | 형태, CMF, 구성 방식 |
| `image_plus_inference` | 이미지 관찰에 해석이 일부 들어간 내용 | 형태 전략, 사용 맥락 추정 |
| `inference` | 원문/이미지 단서를 바탕으로 확장한 판단 | 디자인 매핑, 재사용 원칙 |
| `no_data` | 근거가 없거나 확인할 수 없음 | 본문에는 보통 저장하지 않음 |

### confidence 정의

| 값 | 뜻 |
| --- | --- |
| `Gold` | 원문에 직접 있고 해석 여지가 작음 |
| `Silver` | 원문 또는 이미지 단서가 있지만 해석이 일부 들어감 |
| `Bronze` | 이미지 관찰 또는 약한 추론에 가까움 |
| `No data` | 확인된 정보가 없음 |

## 카드 최상위 구조

```yaml
schema: piix.design_knowledge.card
card_version: "3.0"
card_id:

identity:
  product_name:
  brand:
  designers:
  studio:
  source_url:
  source_type:
  collected_at:

summary:
  one_line:
  why_it_matters:

knowledge:
  product_category:
  user:
  use_context:
  problem:
  experience_value:
  form_strategy:
  cmf:
  technology_production:

design_logic:
  perceived_problem:
  intent:
  solution:
  key_design_choices:
  user_experience:
  reusable_principle:

raw_refs:
  source_card_file:
  raw_text_file:
  raw_html_file:
  images_dir:
  ocr_file:
  scrape_log:
  run_log:
  index_file:

missing_fields:
```

## 8가지 카테고리와 하위 속성

### product_category(제품 카테고리)

- `main_category(대분류)`
- `product_type(구체 제품유형)`
- `sub_category(하위 카테고리)`
- `adjacent_domain(인접 도메인)`

### user(사용자)

- `user_group(사용자군)`
- `persona(페르소나)`
- `skill_level(숙련도)`
- `needs(욕구)`
- `things_to_avoid(회피하고 싶은 것)`

### use_context(사용 맥락)

- `place(사용 공간)`
- `situation(사용 상황)`
- `moment(사용 순간)`
- `frequency(사용 빈도)`
- `surrounding_environment(주변 환경)`

### problem(문제)

- `problem_definition(문제 정의)`
- `pain_points(불편 지점)`
- `tension(긴장/충돌)`
- `opportunity_area(기회 영역)`
- `limits_of_existing_solution(기존 방식의 한계)`

### experience_value(경험 가치)

- `core_value(핵심 가치)`
- `emotional_tone(정서 톤)`
- `user_effect(사용자 효과)`
- `before_after(전후 변화)`
- `brand_experience(브랜드 경험)`

### form_strategy(형태 전략)

- `shape_keywords(형상 키워드)`
- `structure(구성 방식)`
- `volume_language(볼륨 언어)`
- `detail_strategy(디테일 전략)`
- `visual_hierarchy(시각적 위계)`
- `product_typology(제품 유형/전형)`

### cmf(CMF)

- `color.main_color(주 색상)`
- `color.accent_color(보조 색상)`
- `color.tone(톤)`
- `color.contrast(대비)`
- `material.main_material(주 소재)`
- `material.secondary_material(부 소재)`
- `material.structural_material(구조 소재)`
- `material.surface_material(표면 소재)`
- `material.transparent_material(투명 소재)`
- `material.flexible_material(유연 소재)`
- `finish.surface_finish(표면 마감)`
- `finish.gloss(광택)`
- `finish.texture(질감)`
- `finish.touch(촉감)`
- `finish.processing_feel(가공 느낌)`

### technology_production(기술/생산 선택)

- `core_technology(핵심 기술)`
- `internal_components(내부 구성요소)`
- `structure_type(구조 타입)`
- `interface(인터페이스)`
- `production_method(생산 방식)`
- `manufacturing_hint(제조 힌트)`
- `constraints(제약 조건)`
- `safety_durability(안전/내구 조건)`

## 설계 이유 흐름

설계 이유는 디자이너, 브랜드, 평가자가 바라본 문제-의도-해결 방식-사용자 경험을 문장으로 저장합니다.

- `perceived_problem(바라본 문제)`
- `intent(의도)`
- `solution(해결 방식)`
- `key_design_choices(주요 디자인 선택)`
- `user_experience(사용자 경험)`
- `reusable_principle(재사용 가능한 원칙)`

## RAG 인덱싱 원칙

- 기본 검색 대상: `statement`, `tags`, `basis.summary`
- 원문 기반 모드: `grounding=original_text`만 사용
- 추론 포함 모드: `original_text`, `original_plus_inference`, `image_observation`, `image_plus_inference`, `inference` 사용
- 필터/가중치 우선 필드: `problem`, `user`, `use_context`, `experience_value`, `design_logic`
- raw 원문 전체, HTML, 로그는 기본 검색 대상에서 제외

## 카드 본문에서 뺄 것

- `quote_snippets`
- `source_passages`
- `evidence`
- `quote_id`
- `evidence_id`
- `passage_id`
- 빈 `정보 없음` 하위 필드
- raw HTML 전문
- 원문 전문
- 전체 이미지 목록
- 실행 로그 전문

필요하면 위 자료는 `raw_refs`에서 파일로 연결합니다.